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

1. Submit: POST /v1/video/generations returns { "task_id": "...", "status": "submitted" } immediately.
2. Poll: GET /v1/video/generations/{task_id} until status is succeeded (the url field holds the clip) or failed.
3. 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

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"
    }
  }'

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

Request parameters

metadata fields

#Poll the task

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

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

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

#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[]:

{
  "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"
      }
    ]
  }
}

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.

#Video models

Seedance 2.5 is the newest flagship: clips up to 30 seconds and up to 30 reference images. Seedance 2.0 covers 480p, 720p, 1080p and native 4K, plus Fast and Mini variants. MiniMax H3 generates native stereo audio with every clip (768P or 2K, 4 to 15 seconds, billed per second). Supported durations, ratios and resolutions vary by model; see the Models page for per-model details and pricing.

#Next steps

• Super-Resolution : Upscale an existing clip to native 4K
• 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