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 include seedance-2.0 and seedance-2.0-fast. 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. Use "seedance-2.0" or "seedance-2.0-fast".

array

required

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

string

Output resolution: "480p", "720p", or "1080p".

string

Output aspect ratio: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9", or "adaptive".

integer

Video duration from 4 through 15 seconds. Use -1 to let the model choose.

integer

Random seed. Omit it to use a random seed.

boolean

Whether to add a watermark. Default: false.

boolean

Whether to generate synchronized audio.

`content` items

`type`	Value field	Supported `role`	Purpose
`text`	`text`	—	Text prompt. Multiple text items are joined in order.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	Input or reference image. Up to 9 images.
`video_url`	`video_url.url`	`reference_video`	Reference video. Up to 3 videos.
`audio_url`	`audio_url.url`	`reference_audio`	Reference audio. Up to 3 clips.

If an image uses the first_frame or last_frame role, the API uses first/last-frame mode. Other images are treated as references.

Advanced parameters

string

Explicit input mode: "reference" or "first_last_frame". Omit it to infer the mode from content.

boolean

Enable web-search augmentation for the task.

object

Upscale the generated video while retaining the same public task ID.

Show super_resolution_config fields

string

Target resolution: "720p", "1080p", "2k", or "4k". It must exceed the original resolution and cannot be combined with resolution_limit.

integer

Custom short-edge pixel limit from 64 through 2160. It cannot be combined with resolution.

string

Upscaling scene: "aigc", "short_series", "ugc", or "old_film".

string

Upscaling mode: "standard" (default) or "professional".

integer

Output frame rate from 1 through 120. Values above the source frame rate enable frame interpolation.

camera_fixed, frames, callback_url, and return_last_frame are accepted for compatibility but currently have no effect.

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
}

Multimodal reference with upscaling

{
  "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,
  "super_resolution_config": {
    "resolution": "4k",
    "scene": "aigc",
    "tool_version": "professional",
    "fps": 60
  }
}

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"
  },
  "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": "video_generation_failed"
  }
}

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.

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

Advanced parameters

Example requests

First- and last-frame input

Multimodal reference with upscaling

Response

Response fields

Poll task status

Status values

Download the video

Errors

End-to-end example

​Endpoint

​Request

​Headers

​Body parameters

​content items

​Advanced parameters

​Example requests

​First- and last-frame input

​Multimodal reference with upscaling

​Response

​Response fields

​Poll task status

​Status values

​Download the video

​Errors

​End-to-end example

Endpoint

Request

Headers

Body parameters

`content` items

Advanced parameters

Example requests

First- and last-frame input

Multimodal reference with upscaling

Response

Response fields

Poll task status

Status values

Download the video

Errors

End-to-end example