Seedance Video Generation API: Text-to-Video, Image-to-Video, First and Last Frame, Real Person Reference, All in One Interface

Seedance is the video generation model from Byte's Doubao system. It is very practical in domestic content scenarios: it understands Chinese prompts well, generates videos from images stably, and also supports uploading real photos for "character reference," allowing the same person to appear in entirely new scenes.

This article explains how to use the Seedance API on Ace Data Cloud. The interface is POST https://api.acedata.cloud/seedance/videos, and the documentation can be found at platform.acedata.cloud/documents/seedance-videos. You can get a Token from the console to make calls, and the first application comes with a free quota.

First, Look at Real Outputs and Real Costs

The following clip is a cinematic short film generated using Seedance (a shot of a paper boat drifting on the water). The actual cost recorded by the platform for this call is 5.7 credits—this is not an estimate, but the actual amount deducted for this request.

📹 https://cdn.acedata.cloud/de34c29169.mp4

Basic Usage: Text-to-Video

The input structure of Seedance is slightly different from other video interfaces—prompt words, reference images, and reference audio/video are all placed in a content array, with each item distinguished by type. The simplest text-to-video only includes one type: text:

curl -X POST 'https://api.acedata.cloud/seedance/videos' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
      {"type": "text", "text": "A white paper boat drifts on a calm dark water surface at dusk, cinematic reflection, gentle ripples, slow dolly-in, moody lighting."}
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "async": true
  }'

Video generation takes 1–2 minutes; adding "async": true allows you to immediately receive a task_id:

{
  "success": true,
  "task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39",
  "trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4"
}

Then poll /seedance/tasks; when the task is complete, data.status will be succeeded, and data.video_url will be the final product:

curl -X POST 'https://api.acedata.cloud/seedance/tasks' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{"id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39", "action": "retrieve"}'

{
  "success": true,
  "task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39",
  "data": {
    "task_id": "cgt-20251222072003-x2259",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/....mp4",
    "model": "doubao-seedance-2-0-fast-260128"
  }
}

Image-to-Video: First Frame / First and Last Frame

To animate an image, add an item with type: image_url in the content. Note that image_url must be in object format {"url": "https://..."}, and cannot be passed as a string directly, or it will return a 400 error.

Passing one image → First Frame mode, the video starts moving from this image. Passing two images and marking them role: first_frame and role: last_frame → First and Last Frame mode, the video transitions from the first image to the second:

{
  "model": "doubao-seedance-1-0-pro-250528",
  "content": [
    {"type": "text", "text": "360-degree shot"},
    {"type": "image_url", "role": "first_frame", "image_url": {"url": "https://.../first.jpg"}},
    {"type": "image_url", "role": "last_frame",  "image_url": {"url": "https://.../last.jpg"}}
  ]
}

Real Person / Character Reference (Seedance 2.0)

This is the most interesting capability of the Seedance 2.0 series (doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, doubao-seedance-2-0-mini-260615): upload a photo of a person, marked role: reference_image, and the model will maintain this person's appearance in the generated video, while the scene, clothing, and actions are entirely determined by the prompt—essentially placing the same person "into" any new scene.

{
  "model": "doubao-seedance-2-0-fast-260128",
  "content": [
    {"type": "text", "text": "The same woman wearing a beige coat walks through a sunny autumn park, golden leaves falling around her, she smiles softly at the camera, cinematic tracking shot."},
    {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://.../portrait.jpg"}}
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

Key points:

  • reference_image is only supported in the 2.0 series and cannot be mixed with first_frame / last_frame;
  • Reference images are recommended to be single person, frontal, clear, unobstructed; the clearer the face, the higher the similarity;
  • Real person photos will be automatically registered as underlying materials by the platform before being used for generation; the request and response format remains unchanged, but the first generation will take a few extra seconds.

If you want the person to be accurately replicated in the composition of the photo (rather than "the same person in a different scene"), use first_frame to start the video from this photo.

Common Parameter Quick Reference

  • model: 1.x series (doubao-seedance-1-0-pro-250528, ...-1-5-pro-251215, etc.) and 2.0 series (supports face/character/audio-video multimodal references);
  • resolution: 480p / 720p / 1080p, the 2.0 standard model also supports 4k;
  • ratio: 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / adaptive;
  • duration: duration (seconds), 1.x is 2–12, 2.0 is 2–15;
  • generate_audio: generate videos with sound, only doubao-seedance-1-5-pro-251215 supports;
  • callback_url: asynchronous callback address, the platform will POST the results when the task is complete (can also use async + polling).

What to Do with It

  • Vertical Short Videos: ratio: 9:16 Directly output vertical versions suitable for Douyin/Xiaohongshu, combined with 2.0 real person references, allowing for bulk content creation with fixed on-screen personas;
  • E-commerce and Products: Use the first-frame mode to rotate/display product images, or the first and last frame mode to demonstrate "shape changes";
  • Audio Short Clips: Use doubao-seedance-1-5-pro-251215 + generate_audio to produce clips with ambient sound in one step.

Among these usages, "stable on-screen real person short videos" are particularly valuable—it's the most challenging aspect for content accounts to sustain. Place the tools you use in your homepage, and through Ace Data Cloud Revenue Alliance, earn commissions from user consumption generated by those you registered; this is an additional income outside of content; or package this asynchronous generation process as a tool to sell to businesses that need to produce short videos in bulk, with costs being the platform's usage-based charges (for example, the above-mentioned 5.7 credits).

First, use the free quota to run a text-to-video, then try the real person reference; you will have a more specific judgment on what it can do.