Skip to main content
POST
Source media tools
Use source media operations when you need a defined transformation rather than a new text-generated scene. Check availability and the current price with GET /v1/models before submitting. Source images must be static PNG, JPEG or WebP, at most 10 MiB and 4096 pixels per side. Video must be MP4, MOV or WebM, at most 25 MiB, 30 seconds and 30 fps. Audio must be a decodable WAV, MP3, M4A, Ogg or WebM file, at most 20 MiB and 30 seconds. Use public HTTP(S) URLs without credentials; private-network and loopback sources are rejected. A mask must have the same dimensions as its source image. The Gateway measures and validates the actual file bytes. You cannot override seconds, a price, the provider, fps, enhancement tier or a fallback supplier. Talking photo uses H3 Max at 480P and requires audio of 5–30 seconds. Video upscaling uses Topaz precision in one pass up to 4×, preserving the source aspect ratio and frame rate. A target requiring a larger pass is rejected before dispatch. Image upscale uses BRIA Increase Resolution, with the delivered image bounded to 4096 pixels per side and 16 MP. The source alpha channel is preserved in PNG. Canvas expansion uses FLUX 2 Pro: both target dimensions are integers from 512 to 4096, total area at most 4194304 pixels. The requested canvas must contain the source and add pixels; it cannot crop or shrink the source. Layer decomposition uses Seedream 5 Flash Layerize. Supply one image with at least 512 pixels per side and aspect ratio from 1:16 to 16:1. Optional prompt is bounded to 5000 characters; output sizing and layer count are automatic. The fixed tier is auto_1K. No n, layer-count, output-format or aspect-ratio override is accepted. The completed layer Task returns 2–17 result.urls plus matching result.layers. Each layer provides url, content_type and z_index; separated elements also provide bounding_box.absolute and bounding_box.normalized rectangles in left/top/right/bottom order. Normalized coordinates use 0–1000. Files are ordered from background (z_index: 0) upwards. Preserve each file’s MIME: a background may be JPEG, while separated transparent elements are PNG. Save the whole bundle and its placement data before upstream links expire. Launch prices are $0.08 for upscale, $0.36 for an expanded canvas up to 4 MP and $0.70 for one complete layer bundle, covering all permitted outputs. Check the live Catalog before quoting; these are whole-request prices, not per-output layer charges to your account.
Transparent video is delivered as WebM, not MP4. Preserve its MIME type and alpha channel when saving or compositing the result. These operations do not include image or video face swap.
HTTP 202 returns a Task ID and a Location: /v1/tasks/{id} header. Poll the task endpoint with the same account. A successful Task contains result.urls and may provide result.content_type. Save the output before the upstream link expires. Reuse the same idempotency key and identical body to recover a lost receipt, rather than creating another paid operation. Video/audio tools currently use a fixed price for the whole request, including up to 30 seconds. They are not billed per second. Confirm the selected resolution in the live Catalog before displaying a quote. Invalid source media fails before dispatch; confirmed failed Tasks release their reservation. An uncertain upstream submission remains under reconciliation and must not be replayed with a new key.