Generate Seedance videos with Flatkey

Base URL: https://router.flatkey.ai This guide gives you a copy-ready path for using Seedance through Flatkey. Start with a text-to-video task, poll the task until it completes, then download the generated MP4. If you need reusable product, background, audio, or real-person references, continue to the asset library sections.

Copy-ready examples

Use the copy icon on any command block, then replace YOUR_FLATKEY_API_KEY, task_..., ast_..., and rph_... with your own values.

One async workflow

Create the task with POST /v1/videos, poll it with GET /v1/videos/{task_id}, and download the MP4 from metadata.url.

Use this authorization header on every API request in this guide. The video download URL returned in metadata.url is the only exception.

Authorization: Bearer YOUR_FLATKEY_API_KEY

Keep your API key private. Do not paste it into public logs, pages, or support tickets.

Call Seedance

Start here if you only want to create a text-to-video task and download the finished video.

1. Create a text-to-video task

Send POST /v1/videos with the seedance-2.0 model and a text prompt.

curl -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "Create a calm 5 second video of a ceramic mug on a kitchen table in morning light"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

curl.exe -sS https://router.flatkey.ai/v1/videos `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "Create a calm 5 second video of a ceramic mug on a kitchen table in morning light"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

Copy the returned task_... value. Store it in your database or notes because you need it to check the video.

2. Poll the task

Use this endpoint with the saved task ID:

GET /v1/videos/{task_id}

Poll until status is completed, then read the download URL from metadata.url. If the status is failed, read error.message, fix the request, and create a new task.

TASK_ID="task_3f9a00000000000000000000000000e2"

curl -sS "https://router.flatkey.ai/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

# Run the command above again until status is completed.
# Then copy metadata.url from the response and paste it below.
VIDEO_URL="PASTE_METADATA_URL_HERE"
curl -L "$VIDEO_URL" -o output.mp4

$taskId = "task_3f9a00000000000000000000000000e2"

while ($true) {
  $result = curl.exe -sS "https://router.flatkey.ai/v1/videos/$taskId" `
    -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" | ConvertFrom-Json
  Write-Host "status: $($result.status)"

  if ($result.status -eq "completed") { break }
  if ($result.status -eq "failed") {
    $result | ConvertTo-Json -Depth 10
    exit 1
  }
  Start-Sleep -Seconds 5
}

$videoUrl = $result.metadata.url
curl.exe -L "$videoUrl" -o output.mp4

After the task is complete, metadata.url downloads the MP4 file without an authorization header. Treat this URL as private and do not publish it.

Use the asset library

Use the asset library when you want to register a reference once, wait until it is ready, and reuse it in Seedance requests. There are two asset types:

Asset type	What it is for
Virtual assets	Product images, background videos, audio, or other non-person references.
Real-person assets	A specific person’s face, voice, or video. This capability is limited access and must be enabled for your account.

Use the asset://ast_... URI returned by Flatkey in your Seedance requests.

Virtual assets

Virtual assets do not require real-person verification. Create them from a public URL or upload a local file, then reuse the returned Flatkey asset URI.

1. Create a virtual asset from a public HTTPS URL

Send a public https:// URL.

curl -sS https://router.flatkey.ai/v1/assets \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cdn.example.com/reference/product.png",
    "asset_type": "Image",
    "moderation": {
      "strategy": "Default"
    }
  }'

curl.exe -sS https://router.flatkey.ai/v1/assets `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{
    "url": "https://cdn.example.com/reference/product.png",
    "asset_type": "Image",
    "moderation": {
      "strategy": "Default"
    }
  }'

The response includes an id, for example ast_1234567890abcdef1234567890abcdef, and a status such as Processing. Build the reusable URI by adding asset:// before the ID:

asset://ast_1234567890abcdef1234567890abcdef

Do not send model when you create, upload, or query an asset. Flatkey derives the relevant Seedance models from the API key used for the request.

2. Upload a local virtual asset

For a local image, video, or audio file, send multipart/form-data to POST /v1/assets/upload. Use one file field. asset_type can be Image, Video, or Audio.

curl -sS https://router.flatkey.ai/v1/assets/upload \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -F "file=@./reference-a.png" \
  -F "asset_type=Image"

curl.exe -sS https://router.flatkey.ai/v1/assets/upload `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -F "file=@./reference-a.png" `
  -F "asset_type=Image"

The response uses the same asset shape as URL creation. Save its id or asset_url for polling and later video requests.

3. Poll until the selected model is available

Query every asset with the same API key that will create the video task. For example, check two image assets separately:

curl -sS https://router.flatkey.ai/v1/assets/ast_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"
curl -sS https://router.flatkey.ai/v1/assets/ast_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

curl.exe -sS https://router.flatkey.ai/v1/assets/ast_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"
curl.exe -sS https://router.flatkey.ai/v1/assets/ast_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

Every asset response includes available_models. available_models is always an array and lists the models that can use this asset now. A partially ready asset can look like this:

{
  "id": "ast_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "object": "asset",
  "asset_type": "Image",
  "status": "Processing",
  "available_models": ["seedance-2.0-fast"],
  "asset_url": "asset://ast_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "created_at": 1785292000
}

status is the aggregate state across the relevant Seedance models for this API key:

Status	Meaning
`Creating`	The source upload has not finished.
`Processing`	At least one relevant model is still being prepared. Check `available_models`; another model may already be usable.
`Active`	Every relevant model for this API key is ready.
`Failed`	The source failed, or readiness could not be established for at least one relevant model.
`Expired`	The source can no longer be used. Create a new asset.

You do not need to wait for aggregate Active when your chosen model is already listed. Before creating a task, make sure the selected model appears in every asset’s available_models. For fast use seedance-2.0-fast; for pro use seedance-2.0. The task creation request checks readiness again, so retry polling if routing changed between the GET and POST requests. The asset:// URI identifies the asset but does not prove readiness by itself. Deleting means deletion is in progress and the asset cannot be used for a new task. After deletion completes, GET /v1/assets/{asset_id} returns 404 asset_not_found; do not wait for a pollable Deleted status.

4. Call Seedance with two virtual assets

Put each asset://ast_... URI in the media field that matches the asset type: image_url.url for Image, video_url.url for Video, or audio_url.url for Audio. A Seedance request needs text or at least one image/video; audio alone is not enough. This example starts only after both assets list seedance-2.0-fast in available_models.

curl -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "content": [
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ast_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
        },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ast_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
        },
        "role": "reference_image"
      },
      {
        "type": "text",
        "text": "Create a clean studio product video while keeping the product consistent"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

curl.exe -sS https://router.flatkey.ai/v1/videos `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{
    "model": "seedance-2.0-fast",
    "content": [
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ast_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
        },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ast_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
        },
        "role": "reference_image"
      },
      {
        "type": "text",
        "text": "Create a clean studio product video while keeping the product consistent"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

Copy the returned task_... and use GET /v1/videos/{task_id} from the first section to download the finished video from metadata.url.

Real-person assets

Real-person assets are for a specific person’s face, voice, or video. This capability is limited access. Use it only after Flatkey enables it for your account. You will create a profile, send verification_url to the person, wait until the profile is active, create an asset, wait until the asset status is Active, then call Seedance with asset://ast_....

Endpoint	When to use it
`POST /v1/real-persons`	Create a real-person profile and first verification link.
`GET /v1/real-persons`	List your real-person profiles.
`POST /v1/real-persons/{person_id}/verification-sessions`	Create a new verification link if needed.
`GET /v1/real-persons/{person_id}`	Poll the profile status.
`POST /v1/real-persons/{person_id}/assets`	Create an asset from a public URL or a local file.
`GET /v1/real-persons/{person_id}/assets`	List assets under one profile.

File size limits:

File type	Limit
Image	< 30 MiB
Video	<= 50 MiB
Audio	<= 15 MiB

Write requests in this section require Idempotency-Key. Replace each YOUR_UNIQUE_KEY_... placeholder with a new UUID for every new write request. Reuse a key only when retrying the exact same request.

1. Create a real-person profile

curl -sS https://router.flatkey.ai/v1/real-persons \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_PROFILE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My first real-person profile"
  }'

curl.exe -sS https://router.flatkey.ai/v1/real-persons `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_PROFILE" `
  -H "Content-Type: application/json" `
  -d '{
    "name": "My first real-person profile"
  }'

The response includes a profile id, a status, and a one-time verification_url. Send verification_url to the real person and ask them to open it themselves. Do not publish this link. If the link expires or the person needs another link, create a new verification session:

curl -sS -X POST https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/verification-sessions \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_VERIFICATION_SESSION"

curl.exe -sS -X POST https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/verification-sessions `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_VERIFICATION_SESSION"

After the person finishes the verification page, continue with the next step.

2. Poll until the profile is active

curl -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

curl.exe -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

Wait until the profile status is active before creating assets. If it is pending_verification or verifying, wait and poll again. If it is failed or expired, create a new verification session.

3. Create a real-person asset from a public URL

curl -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/assets \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_URL_ASSET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cdn.example.com/reference/person.png",
    "asset_type": "Image",
    "name": "Front-facing reference"
  }'

curl.exe -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/assets `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_URL_ASSET" `
  -H "Content-Type: application/json" `
  -d '{
    "url": "https://cdn.example.com/reference/person.png",
    "asset_type": "Image",
    "name": "Front-facing reference"
  }'

4. Upload a local file

Local upload uses multipart/form-data and is available only for real-person assets. Use one file field and let curl set the multipart boundary.

curl -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/assets \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_FILE_ASSET" \
  -F "asset_type=Image" \
  -F "name=Front-facing reference" \
  -F "file=@./person-reference.png"

curl.exe -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/assets `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_FILE_ASSET" `
  -F "asset_type=Image" `
  -F "name=Front-facing reference" `
  -F "file=@./person-reference.png"

The create response includes an asset ID or asset_uri, for example asset://ast_1234567890abcdef1234567890abcdef.

5. Poll readiness and call Seedance

Real-person asset responses do not include available_models. List the assets under the profile until the asset status is Active:

curl -sS "https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/assets?limit=20" \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

curl.exe -sS "https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/assets?limit=20" `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

If the listed asset is still Processing, wait and poll again. If it is Failed, create a new asset from a better reference. After the asset is Active, call Seedance with the asset://ast_... URI.

curl -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "Create a short greeting video with natural movement"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ast_1234567890abcdef1234567890abcdef"
        },
        "role": "reference_image"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

curl.exe -sS https://router.flatkey.ai/v1/videos `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "Create a short greeting video with natural movement"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ast_1234567890abcdef1234567890abcdef"
        },
        "role": "reference_image"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

Copy the returned task_... and use GET /v1/videos/{task_id} from the first section to download the finished video from metadata.url.

6. Delete an asset when you no longer need it

curl -sS -X DELETE https://router.flatkey.ai/v1/assets/ast_1234567890abcdef1234567890abcdef \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

curl.exe -sS -X DELETE https://router.flatkey.ai/v1/assets/ast_1234567890abcdef1234567890abcdef `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

The delete request returns 204 No Content. After deletion completes, GET /v1/assets/{asset_id} returns 404 asset_not_found.

Quick Start

Code

Mainstream AI Tools

Media Generation

Popular models

Dashboard

Reference

Generate Seedance videos with Flatkey

Copy-ready examples

One async workflow

Call Seedance

1. Create a text-to-video task

2. Poll the task

Use the asset library

Virtual assets

1. Create a virtual asset from a public HTTPS URL

2. Upload a local virtual asset

3. Poll until the selected model is available

4. Call Seedance with two virtual assets

Real-person assets

1. Create a real-person profile

2. Poll until the profile is active

3. Create a real-person asset from a public URL

4. Upload a local file

5. Poll readiness and call Seedance

6. Delete an asset when you no longer need it

Copy-ready examples

One async workflow

​Call Seedance

​1. Create a text-to-video task

​2. Poll the task

​Use the asset library

​Virtual assets

​1. Create a virtual asset from a public HTTPS URL

​2. Upload a local virtual asset

​3. Poll until the selected model is available

​4. Call Seedance with two virtual assets

​Real-person assets

​1. Create a real-person profile

​2. Poll until the profile is active

​3. Create a real-person asset from a public URL

​4. Upload a local file

​5. Poll readiness and call Seedance

​6. Delete an asset when you no longer need it

Call Seedance

1. Create a text-to-video task

2. Poll the task

Use the asset library

Virtual assets

1. Create a virtual asset from a public HTTPS URL

2. Upload a local virtual asset

3. Poll until the selected model is available

4. Call Seedance with two virtual assets

Real-person assets

1. Create a real-person profile

2. Poll until the profile is active

3. Create a real-person asset from a public URL

4. Upload a local file

5. Poll readiness and call Seedance

6. Delete an asset when you no longer need it