SeeDance Videos Generation API Integration Instructions

This document will introduce the SeeDance Videos Generation API integration instructions, which can generate official SeeDance videos by inputting custom parameters.

Application Process

To use the SeeDance Videos Generation API, first go to the 辰汐ai Console to obtain your API Token for future use.

If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and after completion, you will be automatically returned to the current page.

One API Token can call all services on the platform, no need to apply separately for each service. The first application will grant a free quota for a free trial; when the quota is insufficient, you can recharge the general balance in the console.

📘 Complete Documentation: SeeDance Videos Generation API →

Basic Usage

First, understand the basic usage method, which is to input the prompt content.text, type content.type=text, and model model, to obtain the processed result. The specific content is as follows:

Here we can see that we have set the Request Headers, including:

  • accept: the format of the response result you want to receive, here filled as application/json, which is JSON format.
  • authorization: the key to call the API, which can be directly selected after application.

Additionally, we set the Request Body, including:

  • model: the model for generating the video.
    • Seedance 1.x Series: doubao-seedance-1-0-pro-250528, doubao-seedance-1-0-pro-fast-251015, doubao-seedance-1-5-pro-251215, doubao-seedance-1-0-lite-t2v-250428, doubao-seedance-1-0-lite-i2v-250428.
    • Seedance 2.0 Series (supports character and audio-video multimodal references): doubao-seedance-2-0-260128 (standard), doubao-seedance-2-0-fast-260128 (fast), doubao-seedance-2-0-mini-260615 (lightweight).
    • Seedance 2.5: doubao-seedance-2-5-260628, supports up to 30 seconds, pure audio reference, more materials, video editing, and extension.
  • content: input content array, type can be text (prompt), image_url (reference image), audio_url (reference audio), video_url (reference video). Images can specify usage through role: first_frame (first frame) / last_frame (last frame) / reference_image (character / subject reference).
  • resolution: output resolution, optional 480p / 720p / 1080p / 4k. 2.5 supports 480p, 720p, 1080p; 2.0 Fast/Mini supports 480p, 720p; 2.0 Standard supports up to 4k.
  • ratio: aspect ratio, optional 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
  • duration: video length (seconds, integer). 1.0 series 2–12; 1.5 Pro 4–12; 2.0 series 4–15; 2.5 is 4–30. 1.5/2.x supports -1 (automatic duration).
  • seed: random seed, integer, -1 to 4294967295.
  • camerafixed: whether to fix the camera, true / false.
  • watermark: whether to add a watermark, true / false.
  • generate_audio: whether to generate a video with sound, true / false, supported by Seedance 1.5 Pro and 2.x series.
  • return_last_frame: whether to return the last frame image URL in the result.
  • omni_reference_task_type: only 2.5; auto / edit / extend.
  • output_format: only 2.5; mp4 / mov, default mp4.
  • tools: only 2.5; currently supports web_search online search tool, can limit the number of results, keywords, and search sources.
  • priority: 2.5 optional task priority, integer 0–9, default 0.
  • safety_identifier: a stable anonymous end-user identifier of up to 64 characters; please use a hash or internal anonymous ID, do not pass in names, emails, or phone numbers.
  • execution_expires_after: task timeout duration (seconds), range 3600–259200.
  • callback_url: asynchronous callback address, after setting, the API immediately returns task_id, and when the task is completed, it will POST the result to this address.
  • async: optional, set to true when the interface immediately returns task_id, no need to provide callback_url, and then poll the corresponding task query interface to obtain results.

After selection, you can find that the corresponding code is also generated on the right side, as shown in the figure:

Click the "Try" button to test, as shown in the above figure, we obtained the following result:

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

The returned result has multiple fields, described as follows:

  • success, the status of the video generation task at this time.
  • task_id, the ID of the video generation task at this time.
  • trace_id, the tracking ID of the video generation at this time.
  • data, the result list of the video generation task at this time.
    • task_id, the server-side ID of the video generation task at this time.
    • video_url, the video link of the video generation task at this time.
    • status, the status of the video generation task at this time.
      • model, the model used to generate the video.

We can see that we have obtained satisfactory video information, and we only need to obtain the generated SeeDance video based on the video link address in data of the result.

Additionally, if you want to generate the corresponding integration code, you can directly copy the generated code, for example, the CURL code is as follows:

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
}'

Inline Parameter Description

At the end of the content[].text prompt, you can pass generation parameters in the form of --parameter value (old method, weak validation, defaults will be used if filled incorrectly). The complete parameter list is as follows:

Inline Parameter Corresponding Field Description Value Range
--rs resolution Output Resolution 480p / 720p / 1080p
--rt ratio Aspect Ratio 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive
--dur duration Video Duration (seconds) 2–12
--frames frames Video Frame Count Integers satisfying 25+4n in [29, 289] (only 1.0 series supports)
--fps framespersecond Frame Rate Only supports 24
--seed seed Random Seed -1 to 4294967295
--cf camerafixed Whether to Fix Camera true / false
--wm watermark Whether to Add Watermark true / false

Recommended Practice: Directly use the corresponding top-level fields (such as resolution, ratio, etc.) in the Request Body for strong validation mode. If parameters are filled incorrectly, clear error messages will be returned, making it easier to troubleshoot issues.

Generate Audio Video

Seedance 1.5 Pro and 2.x series support generating audio videos through the generate_audio parameter:

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

The 1.0 series does not support this parameter.

doubao-seedance-2-5-260628 supports 480p / 720p / 1080p, 4–30 seconds or automatic duration, and increases the material limit to 30 reference images, 10 reference videos, and 10 reference audio clips (a total of up to 50). 2.5 also supports only passing reference audio, no longer requiring images or videos to be provided simultaneously.

Ordinary full modal generation can omit omni_reference_task_type, or set it to auto. Video editing and extension must pass in reference_video:

{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {"type": "text", "text": "Replace the sky with a warm sunset while preserving the subject and camera motion."},
    {"type": "video_url", "role": "reference_video", "video_url": {"url": "https://cdn.acedata.cloud/input.mp4"}}
  ],
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": -1,
  "omni_reference_task_type": "edit",
  "output_format": "mov"
}
  • edit: Must use ratio: adaptive and duration: -1; output duration is billed based on actual results.
  • extend: Must use ratio: adaptive; duration can be 4–30 or -1.
  • auto: The model automatically selects generation, editing, or extension based on the prompt and materials.
  • If the task type does not match the materials or prompts, the task will fail and return a locatable parameter error; please adjust according to the above constraints and resubmit.

Image to Video First Frame

If you want to perform an image to video task, the content parameter must first include an item with type as image_url, and the image_url field must be in object format: {"url": "https://..."} or Base64 format {"url": "data:image/png;base64,..."}.

Note: image_url does not support direct string format (e.g., "image_url": "https://cdn.acedata.cloud/e724d7f13d.png"), it must use object format "image_url": {"url": "https://..."}, otherwise a 400 error will be returned.

Corresponding code:

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. She opens her eyes and gazes tenderly at the camera, while the fox affectionately holds her back. 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"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Clicking run, you can find that an immediate result is obtained, as follows:

{
    "success": true,
    "task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39",
    "trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4",
    "data": {
        "task_id": "cgt-20251222072003-x2259",
        "status": "succeeded",
        "video_url": "https://platform.cdn.acedata.cloud/seedance/6afb78b8-5ba8-424f-adcd-69423a700b50.mp4",
        "model": "doubao-seedance-1-0-pro-250528"
    }
}

You can see that the generated effect is an image to video, and the result is similar to the above text.

Image to Video First and Last Frame

If you want to perform an image to video first and last frame, the content parameter must first pass in the type image_url, and set the role to first_frame and last_frame, allowing you to specify the following content:

  • role: Specify the first frame or last frame.
  • image_url
    • url Image link At the same time, content also needs to input a type text as the prompt.

Corresponding code:

import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
   "model": "doubao-seedance-1-0-pro-250528",
    "content": [
         {
            "type": "text",
            "text": "360-degree shot"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg"
            },
            "role": "first_frame"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg"
            },
            "role": "last_frame"
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Clicking run, you can find that you will immediately get a result as follows:

{
    "success": true,
    "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
    "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
    "data": {
        "task_id": "cgt-20251222073134-54qcw",
        "status": "succeeded",
        "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
        "model": "doubao-seedance-1-0-pro-250528"
    }
}

It can be seen that the generated effect is a character-generated video, and the result is similar to the above text.

Character and Audio-Video Multimodal Reference (Seedance 2.0)

Seedance 2.0 series (doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, doubao-seedance-2-0-mini-260615) supports reference_image, reference_audio, and reference_video. You can use your own or authorized materials to maintain consistency in character, subject, action, camera movement, sound, and rhythm.

Please only upload your own or authorized real person and character materials. Different models support real person materials in different ways; the request format remains unchanged, and if the materials do not meet the requirements, a clear error will be returned.

Usage points:

  • Only Seedance 2.0 series models support reference_image; 1.x models should use first_frame / last_frame (the first and last frames of the image-generated video).
  • reference_image cannot be mixed with first_frame / last_frame, only one can be chosen.
  • The upper limit of multimodal reference quantity: up to 9 image_url; 2.0 also supports audio_url (with role as reference_audio, up to 3 entries) and video_url (with role as reference_video, up to 3 entries).
  • Reference audio (audio_url) material requirements: formats wav / mp3; single duration 2~15 seconds, up to 3 entries and total duration not exceeding 15 seconds; single entry not exceeding 15 MB. Exceeding the duration range will fail during material processing.
  • Reference video (video_url) material requirements: formats mp4 / mov; single duration 2~15 seconds, up to 3 entries and total duration not exceeding 15 seconds.
  • It is recommended to use single person, frontal, clear, unobstructed photos for reference images; the clearer the face, the higher the similarity.

Example 1: Close-up to Maintain Character Appearance

Input a face photo, letting the character smile and wave at the camera. The corresponding code:

import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
        {
            "type": "text",
            "text": "The woman looks at the camera, gives a warm natural smile and waves her hand, soft studio lighting, gentle camera push-in."
        },
        {
            "type": "image_url",
            "role": "reference_image",
            "image_url": {
                "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
            }
        }
    ],
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

The returned result is as follows, and the character in the generated video remains consistent with the reference photo:

{
  "success": true,
  "task_id": "895eb5ea-bbe1-41a3-a9e9-48608e03f93a",
  "trace_id": "83544791-7a84-44de-b8d2-afe171a1c0e4",
  "data": {
    "task_id": "458abf29-cc39-4fd0-bcea-24f89a70d8de",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
  }
}

Example 2: Placing the Same Person in a Brand New Scene

The power of reference_image lies in: only retaining character identity, while the scene, clothing, and actions are completely determined by the prompt. Below, using the same face photo, let the character wear a beige coat and walk in an autumn park:

{
  "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://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

The returned result is as follows, the character's appearance is retained, while the scene has switched to an autumn park:

{
  "success": true,
  "task_id": "00872de7-16b7-431f-b4f7-6bf38ae86157",
  "trace_id": "577a07c3-4f5f-4cc7-86fe-535bb8332614",
  "data": {
    "task_id": "32fe1537-ba3e-452a-8749-3ef8890d37fd",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/44f47593-556b-4fda-afa5-7a71eefcd228.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "720p",
    "ratio": "9:16",
    "duration": 5
  }
}

💡 If you want the character to accurately replicate the composition in the photo (rather than "the same person in a different scene"), you can use first_frame (the first frame of the video generated from the image) to start the video movement from this photo.

Asynchronous Callback

Since the SeeDance Videos Generation API takes a long time to generate (about 1-2 minutes), you can use the callback_url field to employ asynchronous mode, avoiding long HTTP connection occupation.

Overall process: When the client initiates a request, specify the callback_url, and the API immediately returns a response containing the task_id; after the task is completed, the platform will send the generated result to the callback_url in POST JSON format, which also contains the task_id for association.

{
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}

When the task is completed, the content pushed to the callback_url by the platform is as follows:

{
  "success": true,
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
  "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
  "data": {
    "task_id": "cgt-20251222073134-54qcw",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}

The task_id field in the result is consistent with the one returned during the request, allowing for task association through this field.

Error Handling

When calling the API, if an error occurs, the API will return the corresponding error code and message. For example:

  • 400 token_mismatched: Bad request, possibly due to missing or invalid parameters.
  • 400 api_not_implemented: Bad request, possibly due to missing or invalid parameters.
  • 401 invalid_token: Unauthorized, invalid or missing authorization token.
  • 429 too_many_requests: Too many requests, you have exceeded the rate limit.
  • 500 api_error: Internal server error, something went wrong on the server.

Error Response Example

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusion

Through this document, you have learned how to use the Seedance Videos Generation API for text-to-video, first and last frame, and multimodal reference generation, as well as how to edit or extend videos using Seedance 2.5. We hope this document helps you complete the API integration; if you have any questions, please contact technical support.