A Practical Guide to Generating Short Videos with the Seedance API

If you have ever tried to turn a prompt, product idea, or reference image into a short video clip, the tricky part is often not the creative brief. It is getting the API shape right: which model supports which reference type, how image_url is formatted, and where the finished video URL appears.

This guide walks through a practical Seedance video generation workflow on Ace Data Cloud. We will send text and reference inputs to one endpoint, choose output settings, and read the video_url from the result.

What you can do

The Seedance Videos API supports a few useful builder workflows:

• text-to-video with a plain prompt
• image-to-video with a first frame, or first and last frames
• multimodal references with images, audio, or video
• optional audio generation on supported models
• asynchronous jobs through callback_url or async: true
• Seedance 2.5 video editing and extension with reference_video

The endpoint is:

POST https://api.acedata.cloud/seedance/videos

The request headers are:

authorization: Bearer ${bearer_token}
accept: application/json
content-type: application/json

The core body field is content, an array of typed inputs. Each item can be text, image_url, audio_url, or video_url. Image entries may also use roles such as first_frame, last_frame, or reference_image.

A minimal text-to-video request

A basic request needs a model, a prompt in content, and output settings such as resolution, ratio, and duration. For a quick 720p test, the documented example uses doubao-seedance-2-0-fast-260128:

curl -X POST 'https://api.acedata.cloud/seedance/videos' \
  -H 'authorization: Bearer ${bearer_token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "content": [
      {
        "type": "text",
        "text": "A white ceramic coffee mug on a glossy marble countertop with soft morning window light. The camera slowly orbits 360 degrees around the mug, steam gently rising."
      }
    ],
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

A successful response includes success, task_id, trace_id, and a data object. The useful delivery field is usually data.video_url:

{
  "success": true,
  "task_id": "9777f36b-4f44-47ff-962d-45cd2f7aeaa8",
  "trace_id": "ce5da2ca-6695-4459-9d2c-2ef9f86db752",
  "data": {
    "status": "succeeded",
    "model": "doubao-seedance-2-0-fast-260128",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "video_url": "https://cdn.acedata.cloud/assets/examples/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152-102bf9f98e35.mp4"
  }
}

Keep task_id and trace_id in your logs. They are useful when debugging failed jobs or correlating callbacks.

Choose model features intentionally

The model value determines which options are valid. The Seedance 1.x series includes models such as doubao-seedance-1-0-pro-250528 and doubao-seedance-1-0-lite-i2v-250428. The 2.0 series includes doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, and doubao-seedance-2-0-mini-260615. Seedance 2.5 uses doubao-seedance-2-5-260628.

Some fields are model-specific. generate_audio is supported by Seedance 1.5 Pro and the 2.x series, but not by the 1.0 series:

{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {
      "type": "text",
      "text": "A girl holds a fox, the wind blows her hair, you can hear the sound of the wind"
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 5
}

For Seedance 2.5, omni_reference_task_type can be auto, reference, edit, or extend. Version 2.5 supports output_format as mp4 or mov, and supports duration from 4 to 30 seconds or -1 where automatic duration is allowed.

Add reference images without 400 errors

For image-to-video, image_url must be an object with a url field. Passing a raw string is not supported.

Correct:

{
  "type": "image_url",
  "image_url": {
    "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
  }
}

A simple Python request can combine that image with a prompt:

import requests

url = "https://api.acedata.cloud/seedance/videos"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
payload = {
    "content": [
        {
            "type": "image_url",
            "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"}
        },
        {
            "type": "text",
            "text": "A girl holds a fox in her arms. As the camera slowly pulls away, her hair is gently blown by the wind. --ratio adaptive --dur 5"
        }
    ],
    "model": "doubao-seedance-1-0-pro-250528"
}
print(requests.post(url, json=payload, headers=headers).text)

If you need strict first and last frames, use two image_url items and set role to first_frame and last_frame.

Multimodal references and validation

Seedance 2.0 supports reference_image, reference_audio, and reference_video. This helps when you want consistency in a subject, action, rhythm, or camera motion.

Useful validation rules to add before sending the request:

• Do not mix first_frame / last_frame with reference_image, reference_audio, or reference_video.
• Seedance 2.0 supports up to 9 reference images.
• Reference audio should be wav or mp3, 2–15 seconds per item, up to 3 items, and no more than 15 seconds total.
• Reference video should be mp4 or mov, 2–15 seconds per item, up to 3 items, and no more than 15 seconds total.

A clean production flow is: create an internal job, submit async: true or a callback_url, store task_id and trace_id, then persist data.video_url when the task succeeds. That keeps the model call separate from your UI and gives you enough metadata to retry or inspect failures.

For the full parameter table and additional examples, see the Seedance Videos API Integration Guide.