Docs / Video Generation

Video Generation

RelayDance generates video asynchronously: you submit a task, then poll it until it finishes, or set a webhook callback and never poll at all. Two HTTP calls (or one, with a webhook) take you from prompt to finished mp4.

#The task flow

Submit: POST /v1/video/generations returns { "task_id": "...", "status": "submitted" } immediately.
Poll: GET /v1/video/generations/{task_id} until status is succeeded (the url field holds the clip) or failed.
Or webhook: set metadata.callback_url at submit time and the final task state is POSTed to your URL when the task finishes.

#Submit a task

terminalbash

curl https://relaydance.com/v1/video/generations \
  -H "Authorization: Bearer $RELAYDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-1080p",
    "prompt": "A dancer spins in golden hour light, cinematic",
    "seconds": "10",
    "metadata": {
      "ratio": "16:9",
      "resolution": "1080p",
      "generate_audio": true,
      "callback_url": "https://your-server.example.com/webhook"
    }
  }'

response.jsonjson

{
  "task_id": "task_abc123",
  "status": "submitted"
}

Request parameters

Parameter	Type	Description
`model`	string	Video model ID (see the list below)
`prompt`	string	Text description of the clip. With reference images, cite them as @image1 to @imageN
`seconds`	string	Clip length in seconds, as a string (e.g. "5", "10"); maximum depends on the model
`metadata`	object	Vendor parameters: everything model-specific goes in here

metadata fields

Field	Type	Description
`ratio`	string	Aspect ratio, e.g. "16:9", "9:16", "1:1"
`resolution`	string	"480p" \| "720p" \| "1080p" (model-dependent)
`generate_audio`	boolean	Generate a soundtrack (supported on Seedance 2.0 models)
`callback_url`	string	Webhook URL: final task state is POSTed here when the task finishes
`content`	array	Reference media entries (images, videos, audio), see below

callback_url always goes inside metadata, never at the top level of the request body.

#Poll the task

terminalbash

curl https://relaydance.com/v1/video/generations/task_abc123 \
  -H "Authorization: Bearer $RELAYDANCE_API_KEY"

response.jsonjson

{
  "task_id": "task_abc123",
  "status": "succeeded",
  "url": "https://...mp4",
  "format": "mp4",
  "metadata": { "ratio": "16:9", "resolution": "1080p" }
}

Status	Meaning
`submitted`	Task accepted and queued
`running`	Generation in progress
`succeeded`	Done: download the clip from the url field
`failed`	Generation failed; failed tasks are not billed

#Webhook callback

If you set metadata.callback_url when submitting, polling becomes unnecessary: when the task reaches a final state, RelayDance POSTs the same task JSON shown above to your URL, with retries on delivery failure.

Webhooks are the recommended pattern for production: no polling loops, no wasted requests, and your server reacts the moment a clip is ready.

#Reference media and @imageN

Reference media guides the generation: keep a product faithful, reuse a character, match a motion or a soundtrack. Pass entries in metadata.content[]:

content.jsonjson

{
  "model": "seedance-1-5-pro-with-audio",
  "prompt": "@image1 slowly turns its head toward the camera, soft studio light",
  "seconds": "5",
  "metadata": {
    "ratio": "16:9",
    "resolution": "720p",
    "content": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/cat.jpg" },
        "role": "reference_image"
      }
    ]
  }
}

type	Payload field	role	Limit
`image_url`	image_url.url	reference_image	Up to 9 images per request
`video_url`	video_url.url	reference_video	Up to 3 videos per request
`audio_url`	audio_url.url	reference_audio	Up to 3 audio tracks per request

In the prompt, cite reference images as @image1 to @imageN following their order in content[]: @image1 is the first entry, @image2 the second, and so on.

Reference images are mutually exclusive with first/last-frame mode: use one or the other in a single request. Local files can be hosted via Upload Files first.

#Video models

Model ID	Family	Notes
doubao-seedance-2-0-1080p	Seedance 2.0	Flagship quality, 1080p output
doubao-seedance-2-0-720p	Seedance 2.0	720p output
doubao-seedance-2-0-fast-260128	Seedance 2.0	Faster generation
seedance-1-5-pro-with-audio	Seedance 1.5	Generated audio included
seedance-1-5-pro-no-audio	Seedance 1.5	Silent output
happyhorse-1.0-t2v	HappyHorse	Text-to-video
happyhorse-1.0-i2v	HappyHorse	Image-to-video
happyhorse-1.0-r2v	HappyHorse	Reference-to-video
happyhorse-1.0-video-edit	HappyHorse	Video editing

Seedance 2.0 covers 480p, 720p, 1080p and native 4K, plus Fast and Mini variants. Supported durations, ratios and resolutions vary by model; see the Models page for per-model details and pricing.

Tasks start immediately with no queue, no BytePlus account or KYC is required, and face and portrait generation is supported. RelayDance also exposes special SKUs that are not available on the official platform. Failed requests are not billed.

#Next steps

Image-to-Video example : Animate a still image with reference media
Upload Files : Host local images for use as references
Generate Video reference : Full request and response schema
Get Video Task reference : Polling endpoint and status enum

←Overview Image Generation→