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 stable videos from images, and 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 by 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 for 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; by adding "async": true, you can immediately get the task_id:

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

Then poll /seedance/tasks, and 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"}}
  ]
}

The Seedance 2.0 series allows for the combination of character, audio, and video references; Seedance 2.5 (doubao-seedance-2-5-260628) further supports up to 30 reference images, 10 video segments, 10 audio segments, pure audio references, and editing or extending reference videos.

{
  "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:

  • First frame, first and last frame, and full modal references are mutually exclusive: first_frame / last_frame cannot be mixed with reference_image / reference_video / reference_audio;
  • The omni_reference_task_type for 2.5 can be set to auto, reference, edit, or extend;
  • Please only upload real, character, and audio/video materials that you own or have authorized.

If you want the character to precisely replicate the composition in 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, 1.5, 2.0, and doubao-seedance-2-5-260628;
  • resolution: 480p / 720p / 1080p, with 2.0 Standard also supporting 4k;
  • ratio: 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / adaptive;
  • duration: 2.0 is 4–15 seconds, 2.5 is 4–30 seconds, both support -1 for automatic duration;
  • generate_audio: 1.5 Pro and 2.x support generating videos with sound;
  • callback_url: Asynchronous callback address, where the platform will POST the results when the task is complete (can also use async + polling).

Use It to Do Something

  • 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 generation 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 "form 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 through your registration, providing an 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.