Choose a generation task and model

Every request starts with a task. Use image.create, image.edit, video.create, video.edit, or a supported processing task to describe the result you need. Then choose one of that task's available models when the task requires it.

Read the task before building input

GET /v1/tasks returns each task's availability, models, variants, input schemas, defaults, and output schema. GET /v1/models provides the inverse view: each model and the tasks it supports.

For a model-backed task, send both task and model. For a model-less task, omit model entirely. Do not send null.

Apply defaults deliberately

Defaults are valid starting values, not hidden request fields. Send explicit values when dimensions, duration, resolution, or processing thresholds matter to your integration.

Edit an existing video

Use video.edit with seedance-2.5 to change a person, object, or scene in an existing clip. Provide one source video between 4 and 30 seconds. The output inherits its duration and aspect ratio, so omit duration_seconds and aspect_ratio. Optional reference images, videos, and audio guide the edit.

Add up to nine videos in reference_videos, each 2–30 seconds. The source and all reference videos must total at most 30 seconds. The source is submitted first, followed by the reference videos in the order you supply; describe which clip to edit and how the references should guide it in your prompt.

Send this body to POST /v1/estimates, then to POST /v1/generations with your API key and a new Idempotency-Key:

{
  "task": "video.edit",
  "model": "seedance-2.5",
  "input": {
    "video": { "url": "https://example.com/source.mp4" },
    "prompt": "Edit the first video: replace the person using the identity image and use the second video's lighting. Preserve the first video's motion and framing.",
    "reference_images": [{ "url": "https://example.com/identity.jpg" }],
    "reference_videos": [{ "url": "https://example.com/lighting.mp4" }],
    "resolution": "720p",
    "generate_audio": false
  }
}

Editing is priced on all input video seconds (source plus references) plus output video seconds at the selected resolution. Estimates use measured durations when available and reserve for the 30-second input budget when any input video cannot be measured; an unmeasured source also reserves 30 seconds of output. Settlement uses execution evidence. Use video.create for a new clip with a requested duration and aspect ratio, even when reference media guides the generation.

Understand social search context

social.search applies a US search context where the selected platform integration supports country selection. TikTok searches are pinned to the US. The current Instagram Reels and YouTube Shorts integrations do not accept a country or locale, so those searches use the integration's default context and do not guarantee US-localized results.

Search photo carousels

Set media_type to carousel with platform: "tiktok" to search multi-image TikTok photo posts instead of videos. Each carousel result has media_type: "carousel", its ordered slide images in image_urls, and no duration_seconds. Posts with fewer than two images are not returned, so a search can return fewer results than its limit. max_duration_seconds does not apply to carousels, and carousel search is not available for Instagram Reels or YouTube Shorts. Image URLs are signed by the source platform and expire, so download the slides you need soon after searching.

TikTok video searches can also surface photo posts. Those results are labelled media_type: "carousel" with their image_urls rather than presented as videos, and max_duration_seconds does not filter them out.

See the generated models and tasks reference for complete current schemas and prices.