> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snapgen.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Source media tools

> Upscale, expand and layer images, remove backgrounds or objects, synchronize lips and process source video through one asynchronous SnapGen API.

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`](https://docs.snapgen.org/api-reference/list-models) before submitting.

| Model | Required source fields | Output or supported option |
| - | - | - |
| `image-upscale` | `image_url` | `scale`: 2 or 4; alpha-preserving PNG |
| `image-outpaint` | `image_url`, `target_width`, `target_height` | Centered canvas expansion, PNG |
| `image-layer-decomposition` | `image_url` | Optional `prompt`; complete layer bundle |
| `image-background-remover` | `image_url` | Transparent PNG |
| `image-object-remover` | `image_url`, `mask_url` | PNG; white mask areas are removed |
| `video-upscale` | `video_url` | `resolution`: `1080p`, `2k` or `4k` |
| `video-background-remover` | `video_url` | Transparent WebM with alpha |
| `lip-sync` | `video_url`, `audio_url` | Supplied audio with synchronized lips |
| `talking-photo` | `image_url`, `audio_url` | Fixed `480P`; audio 5–30 seconds |

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.

> [!WARNING]
>
> 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.

```bash theme={null}
curl 'https://api.snapgen.org/v1/media/tools' \
  -H "Authorization: Bearer $SNAPGEN_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-owned-operation-id' \
  -H 'Prefer: respond-async' \
  -d '{
    "model": "image-object-remover",
    "image_url": "https://your-cdn.example/source.png",
    "mask_url": "https://your-cdn.example/mask.png"
  }'
```

HTTP `202` returns a Task ID and a `Location: /v1/tasks/{id}` header. Poll the
[task endpoint](https://docs.snapgen.org/api-reference/task-status.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.