Token Switch Documentation

English

中文

English

中文

Appearance

Seedance ​

Note: Seedance materials are bound to specific groups. When creating an API Key, you can select only one Seedance group.

When using real-person images, audio, or videos, the workflow depends on your API Key group:

  • Seedance Third-Party Resource Channel - A: Create videos directly with real-person materials.
  • Other groups (e.g., Seedance Official Resource Channel, Seedance Third-Party Resource Channel - B, etc.): Create a resource first via Resource Management, then create videos.

Create Video ​

http
POST /v1/contents/generations/tasks

Parameter Passing ​

All parameters are passed in the Body as JSON, and the request header must include Content-Type: application/json.

For resolution, ratio, duration, frames, seed, camera_fixed, and watermark parameters, in addition to passing them directly in the request body, you can also append --[parameters] to the text prompt as a weak-validation method.

  • Regular method (recommended): Pass parameters directly in the request body. This is strongly validated — if a parameter is incorrect, the model returns an error.
json
{
    "model": "doubao-seedance-1-5-Pro-251215",
    "content": [
        {
            "type": "text",
            "text": "A kitten yawning at the camera"
        }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "seed": 11,
    "camera_fixed": false,
    "watermark": true
}
  • Weak-validation method: Append --[parameters] to the text prompt. If a parameter is incorrect, it will be ignored or trigger an error.
json
{
    "model": "doubao-seedance-1-5-Pro-251215",
    "content": [
        {
            "type": "text",
            "text": "A kitten yawning at the camera --rs 720p --rt 16:9 --dur 5 --seed 11 --cf false --wm true"
        }
    ]
}

Weak-validation parameter shorthand:

ParameterShorthand
resolution--rs
ratio--rt
duration--dur
seed--seed
camera_fixed--cf
watermark--wm

Request Parameters (Body) ​

ParameterTypeRequiredDefaultDescription
modelstringYes-Model ID. Available after enabling the model service
contentobject[]Yes-Input content list, supporting text, images, audio, video, draft task IDs, and other element types (see content elements)
callback_urlstringNo-Callback URL. When the task status changes, Ark sends a POST request to this address, with the same structure as the query task API response
return_last_framebooleanNofalseWhether to return the last frame of the generated video (png format, no watermark). Can be used to generate consecutive videos
service_tierstringNodefaultService tier: default (online inference, lower latency) or flex (offline inference, lower cost)
execution_expires_afterintegerNo172800Task timeout threshold (seconds), counted from created_at. Range [3600, 259200]. Timed-out tasks are marked as expired
generate_audiobooleanNotrueWhether to generate audio synchronized with the video. The model auto-generates voice, sound effects, and background music based on the prompt and visual content
draftbooleanNofalseWhether to enable draft mode, generating a 480p preview video for quick validation. Lower cost and token consumption
toolsobject[]No-Tool configuration, e.g., web search (see tools elements)
safety_identifierstringNo-End-user unique identifier for safety risk control. Max 64 characters
priorityintegerNo0Execution priority. Range [0, 9]. Higher values mean higher priority. Only affects queue order
resolutionstringNo-Video resolution, e.g., 480p, 720p, 1080p, 4k
ratiostringNo-Video aspect ratio, e.g., 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive
durationintegerNo-Video duration (seconds). Mutually exclusive with frames; frames takes precedence
framesintegerNo-Video frame count. Range [29, 289], supports integer values in 25 + 4n format
seedintegerNo-1Random seed. Range [-1, 2147483647]. -1 means random
camera_fixedbooleanNofalseWhether to fix the camera
watermarkbooleanNofalseWhether to add an AI Generated watermark in the bottom-right corner

content elements ​

content is the input content list, supporting the following element combinations:

  • Text only
  • Text (optional) + Image
  • Text (optional) + Video
  • Text (optional) + Audio
  • Text (optional) + Image + Audio
  • Text (optional) + Image + Video
  • Text (optional) + Video + Audio
  • Text (optional) + Image + Video + Audio
  • Draft task ID: generate a high-quality final video based on a draft

Each element uses type to distinguish the type and role to mark its role in video generation.

Text ​

ParameterTypeRequiredDescription
typestringYesFixed as text
textstringYesText prompt describing the desired video. Chinese recommended up to 500 characters, English up to 1000 words

Image ​

ParameterTypeRequiredDescription
typestringYesFixed as image_url
image_url.urlstringYesImage source: image URL, Base64 encoding (data:image/<format>;base64,<encoding>), or asset ID (asset://<ASSET_ID>)
rolestringNoImage role: first_frame, last_frame, or reference_image

Supported formats: jpeg, png, webp, bmp, tiff, gif. Aspect ratio range [0.4, 2.5]. Single image max 30 MB.

Video ​

ParameterTypeRequiredDescription
typestringYesFixed as video_url
video_url.urlstringYesVideo source: video URL or asset ID (asset://<ASSET_ID>)
rolestringNoFixed as reference_video

Supported formats: mp4, mov. Resolution 480p–4k. Single video max 200 MB. Frame rate [24, 60] FPS.

Audio ​

ParameterTypeRequiredDescription
typestringYesFixed as audio_url
audio_url.urlstringYesAudio source: audio URL, Base64 encoding (data:audio/<format>;base64,<encoding>), or asset ID (asset://<ASSET_ID>)
rolestringNoFixed as reference_audio

Supported formats: wav, mp3. Single audio max 15 MB. Audio cannot be used alone — at least 1 reference video or image is required.

Draft ​

ParameterTypeRequiredDescription
typestringYesFixed as draft_task
draft_task.idstringYesDraft task ID. The platform automatically reuses the draft's model, text, image_url, generate_audio, seed, ratio, duration, camera_fixed to generate the final video

tools elements ​

ParameterTypeRequiredDescription
typestringYesTool type. Currently supports web_search (web search tool)

Response Parameters ​

ParameterTypeDescription
idstringVideo generation task ID, retained for 7 days
task_idstringTask ID, same as id
objectstringFixed as video
modelstringModel ID
statusstringTask status: queued, running, succeeded, failed, expired
progressintegerTask progress, 0–100
created_atintegerTask creation timestamp (seconds)

Response Example:

json
{
    "id": "cgt-20260807102901-rl788",
    "task_id": "cgt-20260807102901-rl788",
    "object": "video",
    "model": "doubao-seedance-2-0-260128",
    "status": "",
    "progress": 0,
    "created_at": 1786069742
}

This is an async API — after obtaining the ID, use the query API to get task status and results.

Call Examples ​

bash
curl --location 'https://neolink.com/api/v1/contents/generations/tasks' \
--header 'Authorization: Bearer <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
         {
            "type": "text",
            "text": "Use the first-person perspective composition from Video 1 throughout, and use Audio 1 as background music throughout. First-person perspective fruit tea promotional ad, Seedance brand 'Ping Ping An An' apple fruit tea limited edition; first frame is Image 1, your hand picks an Aksu red apple with morning dew, crisp apple collision sound; 2-4 seconds: quick cut, your hand drops apple pieces into a shaker cup, adds ice and tea base, shakes vigorously, ice collision and shaking sounds sync with upbeat drum beats, background voice: 'Fresh cut, fresh shake'; 4-6 seconds: first-person product close-up, layered fruit tea poured into a transparent cup, your hand gently squeezes cream foam to spread on top, sticks a pink-red label on the cup body, camera zooms in on the layered texture of cream foam and fruit tea; 6-8 seconds: first-person hand-held cup raising, you raise the fruit tea from Image 2 in front of the camera (simulating the view of handing it to the audience), cup label clearly visible, background voice 'Take a sip of freshness', final frame freezes on Image 2. Background voice unified as female tone."
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"
            },
            "role": "reference_image"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
            },
            "role": "reference_image"
        },
        {
          "type": "video_url",
          "video_url": {
              "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
          },
          "role": "reference_video"
        },
        {
          "type": "audio_url",
          "audio_url": {
              "url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
          },
          "role": "reference_audio"
        }
    ],
    "generate_audio":true,
    "ratio": "16:9",
    "duration": 11,
    "watermark": false
}'
bash
curl --location 'https://neolink.com/api/v1/contents/generations/tasks' \
--header 'Authorization: Bearer <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "doubao-seedance-1-5-pro-251215",
    "content": [
        {
            "type": "text",
            "text": "A girl holding a fox, the girl opens her eyes and looks gently at the camera, the fox is held friendly, the camera slowly pulls out, the girl'"'"'s hair is blown by the wind, wind sound can be heard"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
            }
        }
    ],
    "generate_audio":true,
    "ratio": "adaptive",
    "duration": 5,
    "watermark": false
}'
bash
curl --location 'https://neolink.com/api/v1/contents/generations/tasks' \
--header 'Authorization: Bearer <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "doubao-seedance-1-5-pro-251215",
    "content": [
         {
            "type": "text",
            "text": "The girl in the image says "cheese" to the camera, 360-degree orbit 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"
        }
    ],
    "generate_audio":true,
    "ratio": "adaptive",
    "duration": 5,
    "watermark": false
}'
bash
curl --location 'https://neolink.com/api/v1/contents/generations/tasks' \
--header 'Authorization: Bearer <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "doubao-seedance-1-0-lite-i2v-250428",
    "content": [
        {
            "type": "text",
            "text": "A girl holding a fox, the girl opens her eyes and looks gently at the camera, the fox is held friendly, the camera slowly pulls out, the girl'"'"'s hair is blown by the wind"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "data:image/png;base64,aHR0******cG5n"
            }
        }
    ],
    "ratio": "adaptive",
    "duration": 5,
    "watermark": false
}'
bash
curl --location 'https://neolink.com/api/v1/contents/generations/tasks' \
--header 'Authorization: Bearer <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
        {
            "type": "text",
            "text": "Realistic style, under a clear blue sky, a large field of white daisy flowers, the camera gradually zooms in, finally framing a close-up of a single daisy, with a few crystal dewdrops on the petals"
        }
    ],
    "ratio": "16:9",
    "duration": 5,
    "watermark": false
}'
python
import os
import time
# Install SDK:  pip install 'volcengine-python-sdk[ark]'
from volcenginesdkarkruntime import Ark

client = Ark(
    base_url='https://neolink.com/api/v1',
    api_key=os.environ.get("API_KEY"),
)

if __name__ == "__main__":
    print("----- create request -----")
    create_result = client.content_generation.tasks.create(
        model="doubao-seedance-2-0-260128",
        content=[
            {
                "type": "text",
                "text": "Use the first-person perspective composition from Video 1 throughout, and use Audio 1 as background music throughout. First-person perspective fruit tea promotional ad, Seedance brand 'Ping Ping An An' apple fruit tea limited edition...",
            },
            {
                "type": "image_url",
                "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"},
                "role": "reference_image",
            },
            {
                "type": "image_url",
                "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"},
                "role": "reference_image",
            },
            {
                "type": "video_url",
                "video_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"},
                "role": "reference_video",
            },
            {
                "type": "audio_url",
                "audio_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"},
                "role": "reference_audio",
            },
        ],
        generate_audio=True,
        ratio="16:9",
        duration=11,
        watermark=False,
    )
    print(create_result)

    print("----- polling task status -----")
    task_id = create_result.id
    while True:
        get_result = client.content_generation.tasks.get(task_id=task_id)
        status = get_result.status
        if status == "succeeded":
            print("----- task succeeded -----")
            print(get_result)
            break
        elif status == "failed":
            print("----- task failed -----")
            print(f"Error: {get_result.error}")
            break
        else:
            print(f"Current status: {status}, Retrying after 30 seconds...")
            time.sleep(30)

Supported Models:

  • doubao-seedance-2-0-260128
  • doubao-seedance-2-0-fast-260128
  • doubao-seedance-2-0-mini-260615
  • doubao-seedance-2-5-260628

Get Video ​

http
GET /v1/contents/generations/tasks/{task_id}
bash
curl --location 'https://neolink.com/api/v1/contents/generations/tasks/{{task_id}}' \
--header 'Authorization: Bearer <API Key>'
python
import time
from volcenginesdkarkruntime import Ark

client = Ark(
    base_url='https://neolink.com/api/v1',
    api_key=os.environ.get("API_KEY"),
)

if __name__ == "__main__":
    task_id = '{{task_id}}'
    while True:
        get_result = client.content_generation.tasks.get(task_id=task_id)
        status = get_result.status
        if status == "succeeded":
            print("----- task succeeded -----")
            print(get_result)
            break
        elif status == "failed":
            print("----- task failed -----")
            print(f"Error: {get_result.error}")
            break
        else:
            print(f"Current status: {status}, Retrying after 30 seconds...")
            time.sleep(30)

Response Parameters ​

ParameterTypeDescription
idstringTask ID
modelstringModel ID
statusstringTask status: queued, running, succeeded, failed, expired
content.video_urlstringGenerated video download URL (returned on success, valid for 24 hours)
video_urlstringGenerated video download URL (same as content.video_url)
created_atintegerTask creation timestamp (seconds)
updated_atintegerTask update timestamp (seconds)
draftbooleanWhether it is a draft
durationintegerVideo duration (seconds)
execution_expires_afterintegerTask timeout threshold (seconds)
framespersecondintegerVideo frame rate (FPS)
generate_audiobooleanWhether the video has audio
output_formatstringOutput format, e.g., mp4
priorityintegerExecution priority
ratiostringVideo aspect ratio
resolutionstringVideo resolution
seedintegerRandom seed
service_tierstringService tier
usage.completion_tokensintegerToken consumption
usage.total_tokensintegerTotal tokens

Response Example:

json
{
    "content": {
        "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/doubao-seedance-2-0/02178606974202400000000000000000000ffffac145a704a6874.mp4?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTYWJkZTExNjA1ZDUyNDc3YzhjNTM5OGIyNjBhNDcyOTQ%2F20260807%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260807T023347Z&X-Tos-Expires=86400&X-Tos-Signature=196ff1aeba19d81988ef1f0a3656170cd5b2f4f29df138af6fb5545f54b34d8c&X-Tos-SignedHeaders=host"
    },
    "created_at": 1786069741,
    "draft": false,
    "duration": 5,
    "execution_expires_after": 172800,
    "framespersecond": 24,
    "generate_audio": true,
    "id": "cgt-20260807102901-rl788",
    "model": "doubao-seedance-2-0-260128",
    "output_format": "mp4",
    "priority": 0,
    "ratio": "16:9",
    "resolution": "720p",
    "seed": 2293,
    "service_tier": "default",
    "status": "succeeded",
    "updated_at": 1786070032,
    "usage": {
        "completion_tokens": 108900,
        "total_tokens": 108900
    },
    "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/doubao-seedance-2-0/02178606974202400000000000000000000ffffac145a704a6874.mp4?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTYWJkZTExNjA1ZDUyNDc3YzhjNTM5OGIyNjBhNDcyOTQ%2F20260807%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260807T023347Z&X-Tos-Expires=86400&X-Tos-Signature=196ff1aeba19d81988ef1f0a3656170cd5b2f4f29df138af6fb5545f54b34d8c&X-Tos-SignedHeaders=host"
}

Note: The variable task_id is returned after a successful video creation request.