Skip to main content
POST

Overview

The dashboard’s Media Generator, from the API: one clip, text-to-video or image-to-video, made with the same models at the same price, and saved to your media library. The call answers 202 right away with the new mediaId; the clip is generated after the response. Poll Get Media until status is COMPLETED (its url is the video) or FAILED. To animate an image, send it as imageMediaId (a finished image of your library, for example one made with Generate Image) or as imageUrl (a public https JPEG, PNG or WEBP, imported into your library first). Without either, the clip is generated from the prompt alone. The model decides what else the request can carry. GET /v1/catalog/video-models lists, per model: A field the model cannot use answers 400 naming it, before anything is charged. model defaults to seedance_2_0.
Priced per second like the dashboard, for the length actually generated (durationSeconds and usedCredits in the answer). Teams on their own provider keys (BYOK) are not charged and need their OpenRouter key; gemini_omni_flash also needs their Gemini key. If the generation fails the credits come back, and one still running after 60 minutes is given up on, reads as FAILED and is refunded too.
Poll Get Media every 10 seconds or so, or pass a webhook (with optional metadata) to be told once it is COMPLETED or FAILED: see media webhooks. A clip usually takes one to a few minutes. A FAILED media says why in its error.

Errors

Every refusal below happens before anything is charged.

Authorizations

x-api-key
string
header
required

Headers

Idempotency-Key
string

Makes the request safe to retry. 1-255 printable ASCII characters, one per operation (your job id, or a UUID you store), reused on every retry. Within 24 hours the same key with the same body answers with the first response and the header Idempotent-Replayed: true, without running or charging again. Keys are scoped to your team and the endpoint. 5xx answers and refusals before anything ran (401, 402, 403, 409, 429) are not kept. See Idempotency.

Required string length: 1 - 255
Pattern: ^[\x20-\x7E]+$

Body

application/json
prompt
string
required

What to generate.

Maximum string length: 5000
model
string
default:seedance_2_0

An id of GET /v1/catalog/video-models.

imageMediaId
string

A finished image of your library to animate from (models with startFrame).

imageUrl
string<uri>

Or a public https URL of the start image (JPEG, PNG or WEBP, up to 25 MB): it is imported into your library first. Not with imageMediaId.

endImageMediaId
string

A library image for the clip to end on (models with endFrame). Needs a start image.

referenceMediaIds
string[]

Library images of a character or style to keep, at most the model's maxReferenceImages.

durationSeconds
number

Clip length. Snapped up to the next of the model's durations (at most its longest); defaults to the model's defaultDuration.

aspectRatio
enum<string>

One of the model's aspectRatios. Defaults to the start image's ratio when the model films it, else ratio_9_16.

Available options:
ratio_9_16,
ratio_1_1,
ratio_16_9
resolution
string

One of the model's resolutions; defaults to its defaultResolution. Some models are priced by resolution.

audio
boolean

Ask for sound with the clip (models with makesSound). Left out, the model's own default.

name
string

Name in your library. Defaults to Generated Image - <date> / Generated Video - <date>.

Maximum string length: 255
webhook
string

Public https URL told once when the media is COMPLETED or FAILED (events media.completed / media.failed, signed like every Hooked webhook). See Webhooks.

Maximum string length: 500
metadata
object

Any JSON object of your own (max 5 KB). Sent back in the webhook payload.

Response

Generation started

success
boolean
message
string
data
object