Seedance Video Generation — POST /v1/videos

Use POST /v1/videos to create an asynchronous Seedance video-generation task. Poll the task until it completes, then download the video from the returned Flatkey URL. Supported models are seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, and seedance-2.5. Availability depends on your account; use GET /v1/models to retrieve the current model list.

Endpoint

POST https://router.flatkey.ai/v1/videos

Flatkey also accepts POST /v1/video/generations and GET /v1/video/generations/{task_id}. Use /v1/videos for the standard response structure and native usage data.

Request

Headers

Header	Value
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

Body parameters

string

required

Seedance model ID: "seedance-2.0", "seedance-2.0-fast", "seedance-2.0-mini", or "seedance-2.5".

array

required

Multimodal input items. Include at least one non-empty text item, image, video, or audio item. See content items.

string

Output resolution. Default: "720p".

Model	Supported values
`seedance-2.0`	`"480p"`, `"720p"`, `"1080p"`, `"4k"`
`seedance-2.0-fast`, `seedance-2.0-mini`	`"480p"`, `"720p"`
`seedance-2.5`	`"480p"`, `"720p"`, `"1080p"`

string

Output aspect ratio: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9", or "adaptive". Default: "adaptive". With "adaptive", the model picks the ratio from your input images or videos. For seedance-2.5, first-frame and first/last-frame tasks support only "adaptive".

integer

Video length in seconds. Default: 5. Seedance 2.0 models accept 4 through 15; seedance-2.5 accepts 4 through 30.

Always send a positive duration. Flatkey bills Seedance per second, so -1 (let the model choose the length) is rejected with video_price_not_configured. The only exception is a seedance-2.5 video edit, which requires -1.

boolean

Add an “AI generated” watermark to the lower-right corner. Default: false.

boolean

Generate a synchronized mono audio track. Default: true. Set it to false if you only need video; generated audio can occasionally fail copyright checks.

boolean

Return the last frame of the generated video as an image. Default: false. When true, the completed task includes metadata.last_frame_url, which downloads a JPEG with the same dimensions as the video and no watermark. Use it as the first_frame of the next task to chain clips. Like metadata.url, it needs no authorization header; treat it as private.

string

seedance-2.5 only. Container of the generated video: "mp4" or "mov". Default: "mp4". MOV keeps more color precision for grading and compositing (H.264, YUV 4:4:4, PCM audio), but some players cannot open it. The content endpoint returns video/quicktime for MOV results.

string

seedance-2.5 only, for reference-mode tasks. Tells the model which task you intend: "auto" (default), "reference", "edit", or "extend". Setting it explicitly moves the task-type checks to submission, so an invalid combination fails immediately instead of after the task starts. "reference", "edit", and "extend" all need reference items in content; a text-only request with "reference" is rejected. See video editing and extension.

integer

Queue priority from 0 through 9. Default: 0. Higher values move the task ahead of lower-priority tasks waiting on the same model. Supported on all Seedance 2.0 models and seedance-2.5. Values outside 0–9 are rejected with 400.

integer

Seconds the task may wait and run before it expires. Default: 172800 (48 hours). Use a shorter value when a late result is useless to you.

string

Public HTTPS URL that receives a POST whenever the task changes status. See Task callbacks. Must use https, contain no user credentials, be at most 2,048 characters, and resolve to a public address; otherwise the request is rejected with 400.

`content` items

`type`	Value field	Supported `role`	Limits
`text`	`text`	—	Prompt text. Keep it under about 1,000 English words.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	Up to 9 reference images (`seedance-2.5`: 30). JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, or HEIF; under 30 MB; 300–6000 px per side; aspect ratio 0.4–2.5.
`video_url`	`video_url.url`	`reference_video`	Up to 3 videos, 2–15 seconds each and 15 seconds total (`seedance-2.5`: 10 videos, 30 seconds). MP4 or MOV; under 200 MB; at least about 409,600 total pixels (for example 854×480).
`audio_url`	`audio_url.url`	`reference_audio`	Up to 3 clips, 2–15 seconds each and 15 seconds total (`seedance-2.5`: 10 clips, 30 seconds). WAV or MP3; under 15 MB. Seedance 2.0 models need at least one image or video alongside audio.

Each URL can be a public HTTPS URL, a data:<mime>;base64, data URI (images and audio only), or an asset:// reference from the asset library. The whole request body must stay under 64 MB. Choose one input mode per task. These modes cannot be mixed:

Mode	How to build `content`
First frame	One image with `role: "first_frame"`.
First and last frames	Two images, one with `role: "first_frame"` and one with `role: "last_frame"`. `last_frame` always needs a `first_frame`, and neither can be combined with reference items.
Reference	Any combination of `reference_image`, `reference_video`, and `reference_audio` items.

Video editing

seedance-2.5 can edit or extend an existing video in reference mode. Describe the change in the prompt and refer to the video as @Video1.

Task	Required settings	Output length
Edit (replace a subject, add or remove objects, change audio)	At least one `reference_video` 4–30 seconds long, `ratio: "adaptive"`, `duration: -1`. Recommended: `omni_reference_task_type: "edit"`.	Same as the edited input video
Extend (continue a video forward or backward)	At least one `reference_video`, `ratio: "adaptive"`, a positive `duration`. Recommended: `omni_reference_task_type: "extend"`.	`duration`

{
  "model": "seedance-2.5",
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": -1,
  "omni_reference_task_type": "edit",
  "content": [
    { "type": "text", "text": "Edit @Video1: make the ball bright green and keep everything else unchanged." },
    { "type": "video_url", "video_url": { "url": "https://example.com/input.mp4" }, "role": "reference_video" }
  ]
}

Like every seedance-2.5 request with a reference video, an edit is billed at the resolution’s with-video rate for a fixed 30 seconds, regardless of the input or output length.

Draft mode

seedance-2.5 can render a cheap 480p draft first, so you can check the scene, shots, and motion before paying for the final video. It takes two requests:

Create the draft. Send a normal request with "draft": true and "resolution": "480p". It is billed as a regular 480p video.
Render the final video. After the draft completes, send a request whose only content item is a draft_task pointing at the draft’s task ID, with "resolution": "1080p".

{
  "model": "seedance-2.5",
  "resolution": "1080p",
  "content": [
    { "type": "draft_task", "draft_task": { "id": "task_3f9a00000000000000000000000000e2" } }
  ]
}

The final video reuses the draft’s prompt, media, duration, ratio, seed, audio setting, and task type. Do not send duration, ratio, frames, seed, generate_audio, omni_reference_task_type, draft, or any other content item with a draft_task; the request is rejected with 400. You can still set return_last_frame, output_format, watermark, priority, execution_expires_after, and callback_url.

Rule	Detail
Model	`model` must match the draft.
Draft task ID	Use the `task_…` ID Flatkey returned for the draft. It must be your own task and must have completed.
Resolution	Draft: `480p` only. Final video: `1080p` only.
Expiry	A draft can be used for 7 days after it was created.
Billing	The final video is billed at the 1080p rate for the draft’s duration. If the draft used a reference video, the with-video rate applies for a fixed 30 seconds.

Seedance does not accept images or videos that show real human faces directly. Upload them as real-person assets and reference them with asset://.

Example requests

import os
import requests

response = requests.post(
    "https://router.flatkey.ai/v1/videos",
    headers={
        "Authorization": f"Bearer {os.environ['FLATKEY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2.0",
        "content": [
            {
                "type": "text",
                "text": "An astronaut walking on the moon, cinematic lighting, slow camera push-in",
            }
        ],
        "resolution": "1080p",
        "ratio": "16:9",
        "duration": 5,
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://router.flatkey.ai/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLATKEY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.0",
    content: [
      {
        type: "text",
        text: "An astronaut walking on the moon, cinematic lighting, slow camera push-in",
      },
    ],
    resolution: "1080p",
    ratio: "16:9",
    duration: 5,
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

curl https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "An astronaut walking on the moon, cinematic lighting, slow camera push-in"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

First- and last-frame input

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "The camera slowly moves forward" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first.jpg" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/last.jpg" },
      "role": "last_frame"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false
}

Multimodal reference

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "A woman smiles at the camera during a beach sunset" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/reference.jpg" },
      "role": "reference_image"
    }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "watermark": false
}

Response

{
  "id": "task_3f9a00000000000000000000000000e2",
  "task_id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "model": "seedance-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1780306574
}

Response fields

string

Public task ID used to poll the task and download the completed video. task_id contains the same value.

string

Task status: queued, in_progress, completed, or failed.

integer

Generation progress from 0 through 100.

integer

Unix timestamp for task creation.

Poll task status

GET https://router.flatkey.ai/v1/videos/{task_id}

curl https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2 \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

While generation is running, the response includes the current progress:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "in_progress",
  "progress": 50,
  "model": "seedance-2.0",
  "created_at": 1780306574
}

When the task completes, the response includes the video URL and token usage:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content",
    "last_frame_url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/last-frame"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

Failed tasks return the error details with the task response:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "failed",
  "error": {
    "message": "The video generation task failed.",
    "code": ""
  }
}

Any pre-consumed balance is refunded automatically.

Status values

Status	Meaning
`queued`	The task is waiting to start.
`in_progress`	The video is being generated. `progress` ranges from 0 through 100.
`completed`	The video is ready at `metadata.url`, and token usage is available in `usage`.
`failed`	Generation failed. Details are available in `error.message`, and any pre-consumed balance is refunded.

Task callbacks

Set callback_url to receive status changes instead of, or in addition to, polling. Flatkey sends a POST with Content-Type: application/json when the task moves to in_progress, completed, or failed. The body is exactly what GET /v1/videos/{task_id} returns at that moment, including metadata.url and metadata.last_frame_url for completed tasks.

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

Header	Value
`X-Flatkey-Event-Id`	`<task_id>:<status>`, for example `task_3f9a…e2:completed`. The same event can be delivered more than once; use this header to ignore duplicates.

Respond with any 2xx status within 5 seconds. Otherwise Flatkey retries twice, after 2 and 8 seconds, and then gives up. Redirects are not followed. Callbacks are not signed, so verify a result by polling the task before acting on it, and keep polling as the source of truth in case a callback is lost.

Download the video

GET https://router.flatkey.ai/v1/videos/{task_id}/content

curl -L "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content" \
  -o output.mp4

The content endpoint streams video/mp4 data, or video/quicktime when the task used output_format: "mov". It does not require a Bearer token and can be used directly as a <video> source.

The content endpoint works only after the task completes and is rate-limited by client IP. Treat the URL as sensitive because anyone with it can download the video.

Errors

Request-time errors use Flatkey’s standard error envelope:

{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}

Scenario	Behavior
Empty `content`	The request is rejected. Include non-empty text, an image, or a video.
Unavailable model	The requested `model` is not enabled for the route.
Insufficient balance	The task is not created.
`priority` outside 0–9	The request returns `400` with `invalid_request`.
Invalid `callback_url`	The request returns `400` with `invalid_request` when the URL is not HTTPS, contains credentials, is longer than 2,048 characters, or points to a private or local address.
`duration: -1` outside a `seedance-2.5` video edit	The request returns `400` with `video_price_not_configured`.
Invalid input for the model	The request returns `400` with `fail_to_fetch_task`, or, for requests that use `asset://` references, the task fails with `task preparation failed`. Check resolution, duration, content limits, and input-mode rules above. You are not charged.
Temporary service failure	Retry later using your normal backoff policy.

End-to-end example

This example creates a task, polls it every five seconds, and downloads the completed video. It requires jq.

#!/usr/bin/env bash
set -euo pipefail

BASE="https://router.flatkey.ai"
: "${FLATKEY_API_KEY:?Set FLATKEY_API_KEY before running this script}"

RESPONSE=$(curl -sS "$BASE/v1/videos" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      { "type": "text", "text": "An astronaut walking on the moon, cinematic lighting" }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }')

TASK_ID=$(echo "$RESPONSE" | jq -r '.id')
echo "task: $TASK_ID"

while true; do
  RESULT=$(curl -sS "$BASE/v1/videos/$TASK_ID" \
    -H "Authorization: Bearer $FLATKEY_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  echo "status: $STATUS"

  [ "$STATUS" = "completed" ] && break
  if [ "$STATUS" = "failed" ]; then
    echo "failed: $(echo "$RESULT" | jq -r '.error.message')" >&2
    exit 1
  fi
  sleep 5
done

VIDEO_URL=$(echo "$RESULT" | jq -r '.metadata.url')
curl -L "$VIDEO_URL" -o output.mp4
echo "saved -> output.mp4"

Overview

Endpoints

Seedance Video Generation — POST /v1/videos

Endpoint

Request

Headers

Body parameters

`content` items

Video editing

Draft mode

Example requests

First- and last-frame input

Multimodal reference

Response

Response fields

Poll task status

Status values

Task callbacks

Download the video

Errors

End-to-end example

​Endpoint

​Request

​Headers

​Body parameters

​content items

​Video editing

​Draft mode

​Example requests

​First- and last-frame input

​Multimodal reference

​Response

​Response fields

​Poll task status

​Status values

​Task callbacks

​Download the video

​Errors

​End-to-end example

Endpoint

Request

Headers

Body parameters

`content` items

Video editing

Draft mode

Example requests

First- and last-frame input

Multimodal reference

Response

Response fields

Poll task status

Status values

Task callbacks

Download the video

Errors

End-to-end example