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
grok-imagine-video	Grok Imagine	xAI video generation
grok-imagine-video-1.5-preview	Grok Imagine	xAI 1.5 preview

Supported durations, ratios and resolutions vary by model; see the Models page for per-model details and pricing.

#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→