Create Video Generation Task API

This document describes the input and output parameters of the Create Video Generation Task API for your reference when using the interface. The model generates videos based on the input images and text information. After generation is complete, you can query tasks by conditions and obtain the generated videos.

Model Capabilities

Doubao Seedance 2.5 (Audio/Video)
Multi-Modal Reference Video Generation: Input reference images (0~30) + reference videos (0~10) + reference audios (0~10) + text prompts (optional) to generate 1 target video. Supports audio-only input. Supports generating new videos, editing videos, and extending videos. Supports direct output of 30-second coherent videos.
Image-to-Video - First and Last Frames: Input first frame image + last frame image + text prompts (optional) to generate 1 target video.
Image-to-Video - First Frame: Input first frame image + text prompts (optional) to generate 1 target video.
Text-to-Video: Input text prompts to generate 1 target video.

Note Image-to-Video - First Frame, Image-to-Video - First and Last Frames, and Multi-Modal Reference Video Generation (including reference images, videos, and audios) are 3 mutually exclusive scenarios and cannot be mixed. Multi-Modal Reference Video Generation can indirectly achieve the "first & last frame + multi-modal reference" effect by specifying reference images as first/last frames through prompts. If you need to strictly ensure that the first and last frames are exactly the same as the specified images, use Image-to-Video - First and Last Frames (set role to first_frame / last_frame).

Task Types and Special Restrictions

Seedance 2.5 will classify requests into 5 task types: text-to-video, reference-based video generation, video editing, video extension, and first frame/first & last frame video generation based on the content.role parameter values and prompt intent.

• If the task type is video editing, video extension, or first frame/first & last frame video generation, the model has special restrictions on aspect ratio and duration parameters. Violating these restrictions will trigger asynchronous errors.
• If the task type is text-to-video or reference-based video generation, the model has no special restrictions on aspect ratio and duration parameters; however, avoid using words related to video editing or extension in the prompts of reference-based video generation tasks to prevent the model from misjudging and triggering errors.

Task Category	Task Trigger Conditions (Two-Level Judgment)	Special Restrictions
Video Editing	1. content.role must be set to reference_image / reference_video / reference_audio 2. Prompt trigger keywords (containing any one of them): edit video, add/append, delete/remove, modify/replace/change to	- Aspect Ratio: Only supports ratio as adaptive, automatically kept consistent with the video to be edited, no other settings are supported - Duration: Only supports duration as -1, automatically kept basically consistent with the video to be edited, no customization is supported
Video Extension	1. content.role must be set to reference_image / reference_video / reference_audio 2. Prompt trigger keywords (containing any one of them): extend forward/backward, continue, continue writing	- Aspect Ratio: Only supports ratio as adaptive, automatically kept consistent with the video to be extended, no other settings are supported
First Frame / First & Last Frame Video Generation	content.role must be set to first_frame / last_frame	- Aspect Ratio: Only supports ratio as adaptive, the model automatically matches the aspect ratio, no other settings are supported

Request Parameters

Request Information

Item	Value
Request Method	POST
Official Request URL	https://ai-tokenhub.com/api/v3/contents/generations/tasks
Content-Type	application/json
Authentication	API Key Authentication (Bearer Token)
Task Data Retention Period	7 days (calculated from task creation time)

Request Headers

Field Name	Required	Description
Authorization	✓	Format: Bearer $YOUR_API_KEY, where $YOUR_API_KEY is the long-term API key you obtained from the Tianshu platform
Content-Type	✓	Fixed value: application/json

Request Body

---

model string Required

The Model ID of the model you need to call. The Model ID for Seedance 2.5 is doubao-seedance-2-5-260628.

---

content object[] Required

Information input to the model for video generation, supporting text, images, audio, video, draft task ID, and other types of elements.

Supported Input Combinations:

• Text
• Text (optional) + Image
• Text (optional) + Video
• Text (optional) + Audio (only Seedance 2.5 supports audio-only input)
• Text (optional) + Image + Audio
• Text (optional) + Image + Video
• Text (optional) + Video + Audio
• Text (optional) + Image + Video + Audio
• Draft Task ID: A draft refers to a preview video successfully generated by a Seedance model. The model can generate a high-quality formal video based on the draft.

Information Types

Text Information object

Prompt information input to the model.

• content.type string Required: The type of input content, should be text
• content.text string Required: The text prompt input to the model, describing the desired generated video.

Notes

• Prompt Language Support: All models support Chinese and English prompts; Seedance 2.5 additionally supports Spanish, Indonesian, Portuguese, Japanese, Malay, Thai, Arabic, Vietnamese, and Korean.
• Prompt Length Recommendation: Chinese prompts should not exceed 500 characters, English prompts should not exceed 1000 words. Excessive length may lead to scattered information, causing the model to potentially ignore details and focus only on key points, resulting in missing elements in the video.
• More Usage Tips: For detailed prompt usage tips, please refer to the Seedance Prompt Guide.

Image Information object

Image information input to the model.

Properties:

• content.type string Required: The type of input content, should be image_url.

• content.image_url object Required: The image object input to the model.

• content.image_url.url string Required: Image URL, image Base64 encoding, or asset ID.

  • Image URL: Enter the public URL of the image.
  • Base64 Encoding: Convert local files to Base64 encoded strings and submit them to the model. Follow the format: data:image/<image_format>;base64,<Base64_encoding>, note that <image_format> should be lowercase, e.g., data:image/png;base64,<Base64 image>.
  • Asset ID: The ID of pre-set assets and virtual avatars for video generation, following the format: asset://<ASSET_ID>. For details, see the Asset Library Usage Guide.
  Single Image Input Requirements

  • Format: jpeg, png, webp, bmp, tiff, gif, heic, heif
  • Aspect Ratio (width/height): [0.4, 2.5]
  • Width/Height (px): [300, 6000]
  • Size: Single image less than 30 MB. Request body size should not exceed 64 MB. Do not use Base64 encoding for large files.

  Image Count:

  • Image-to-Video - First Frame: 1 image
  • Image-to-Video - First and Last Frames: 2 images
  • Seedance 2.5 Multi-Modal Reference Video Generation: 1-30 images

• content.role string Conditionally Required: The position or purpose of the image.

Note

Image-to-Video - First Frame, Image-to-Video - First and Last Frames, and Multi-Modal Reference Video Generation (including reference images, videos, and audios) are 3 mutually exclusive scenarios and cannot be mixed.

Multi-Modal Reference Video Generation can indirectly achieve the "first & last frame + multi-modal reference" effect by specifying reference images as first/last frames through prompts. If you need to strictly ensure that the first and last frames are exactly the same as the specified images, use Image-to-Video - First and Last Frames (set role to first_frame / last_frame).

Image-to-Video - First Frame_role values: Need to input 1 image_url object, with role field as first_frame or left blank.

Image-to-Video - First and Last Frames_role values: Need to input 2 image_url objects, and the role field is required.

• First frame image corresponding role: first_frame
• Last frame image corresponding role: last_frame

Image-to-Video - Reference Image_role values: Required, each reference image's role is: reference_image

Note

The first and last frame images can be the same. When the aspect ratios of the first and last frame images are inconsistent, the first frame image takes precedence, and the last frame image will be automatically cropped to fit.

Video Information object

Video information input to the model.

Properties:

• content.type string Required: The type of input content, should be video_url.
• content.video_url object Required: The video object input to the model.
• content.video_url.url string Required: Video URL or asset ID.

Video URL:

• Enter the public URL of the video.

  Single Video Input Requirements

  • Video Format: mp4, mov, supported encoding formats see table below.
  • Resolution: 480p, 720p, 1080p, 4k
  • Duration: Non-video-editing tasks, single video duration [2, 30] s; video editing tasks, single video duration [4, 30] s. Up to 10 reference videos, total duration of all videos should not exceed 30 s.
  • Dimensions:
    • Aspect Ratio (width/height): [0.4, 2.5]
    • Width/Height (px): [300, 6000]
    • Total Pixels: [614×664=407696, 3326×2494=8295044], i.e., the product of width and height should be within [407696, 8295044].
  • Size: Single video should not exceed 200 MB.
  • Frame Rate (FPS): [24, 60]

Container Formats

Container Format	Common File Extensions	MIME	Supported Encodings
MP4	mp4	video/mp4	Video: H.264/AVC, H.265/HEVC; Audio: AAC, MP3
QuickTime	mov	video/quicktime	Video: H.264/AVC, H.265/HEVC; Audio: AAC, MP3, PCM

• content.role string Conditionally Required: The position or purpose of the video. Currently only supports reference_video.

Audio Information object

Audio information input to the model.

Note: Seedance 2.5 supports audio-only input, no need to pair with images/videos; can also be submitted together with images/videos.

Properties:

• content.type string Required: The type of input content, should be audio_url.
• content.audio_url object Required: The audio object input to the model.
• content.audio_url.url string Required: Audio URL, audio Base64 encoding, or asset ID.

• Audio URL: Enter the public URL of the audio.
• Base64 Encoding: Convert local files to Base64 encoded strings and submit them to the model. Follow the format: data:audio/<audio_format>;base64,<Base64_encoding>, note that <audio_format> should be lowercase, e.g., data:audio/wav;base64,<base64 audio>.
• Asset ID: The audio asset ID of the virtual avatar for video generation, following the format: asset://<ASSET_ID>.

Single Audio Input Requirements

• Format: wav, mp3
• Duration: Single audio duration [2, 30] s, up to 10 reference audios, total duration of all audios should not exceed 30 s.
• Size: Single audio should not exceed 15 MB, request body size should not exceed 64 MB. Do not use Base64 encoding for large files.

• content.role string Conditionally Required: The position or purpose of the audio. Currently only supports reference_audio.

Draft Task Information object

Draft task information. Generate a formal video based on the draft task ID.

Properties:

• content.type string Required: The type of input content, should be draft_task.

• content.draft_task object Required: The draft task object input to the model.

• content.draft_task.id string Required: The draft task ID. Fill in the id returned by creating a task with draft mode enabled (draft: true), not upstreamTaskId.

  Notes

  • Usage consists of two steps: Step 1 call this API with "draft": true to generate a Draft video; Step 2 if the Draft video meets your expectations, call this API again with the Draft video task ID returned in Step 1 to generate the formal video.
  • When generating a formal video based on a Draft video, some parameters are automatically reused by the model, some are prohibited from being passed again, and some can be re-specified. For details, see the Seedance 2.5 Draft Mode documentation.

---

callback_url string

The callback notification address for this generation task result. When the video generation task status changes, a POST request will be pushed to this address.

The callback request content structure is consistent with the response body of the Query Video Generation Task API.

Callback returned statuses include:

• queued: Queued
• running: Task running
• succeeded: Task succeeded (if sending fails, i.e., successful delivery information is not received within 5 seconds, callback three times)
• failed: Task failed (if sending fails, i.e., successful delivery information is not received within 5 seconds, callback three times)
• expired: Task timed out, i.e., the task has been in running or queued status beyond the expiration time. The expiration time can be set via the execution_expires_after field.

---

return_last_frame boolean

Default: false

• true: Return the last frame image of the generated video. After setting to true, you can obtain the last frame image of the video through the Query Video Generation Task API. The last frame image format is jpeg, with width and height pixels consistent with the generated video, and no watermark. Using this parameter enables multiple continuous videos: use the last frame of the previous generated video as the first frame of the next video task to quickly generate multiple continuous videos.
• false: Do not return the last frame image of the generated video.

---

draft boolean

Default: false

Controls whether to enable draft mode. It generates a low-cost preview video first, so that you can confirm whether the scene structure, camera movement, subject actions, and prompt intent meet your expectations before generating the formal video based on the draft.

• true: Enable draft mode and generate a preview video (Draft video). It consumes fewer tokens than a formal video and costs less.
• false: Disable draft mode and generate a regular video.

Notes

• After enabling draft mode, only 480p Draft videos can be generated (using other resolutions will trigger an error).
• For parameter restrictions and billing rules in draft mode, see the Seedance 2.5 Draft Mode documentation.

---

execution_expires_after integer

Default: 172800

Task timeout threshold. Specifies the expiration time after task submission (unit: seconds), calculated from the created_at timestamp. Default value is 172800 seconds, i.e., 48 hours. Value range: [3600, 259200].

Regardless of which service tier is used, it is recommended to set an appropriate timeout based on business scenarios. After this time, the task will be automatically terminated and marked as expired status.

---

generate_audio boolean

Default: true

Controls whether the generated video contains synchronized audio.

• true: The model's output video contains synchronized audio. The model will automatically generate matching human voice, sound effects, and background music based on the text prompt and visual content. It is recommended to place dialogue parts in double quotes to optimize audio generation. Example: A man stops a woman and says: "Remember, never point at the moon with your finger."
• false: The model's output video is a silent video.

Note: All generated audio videos are mono channel, regardless of the input audio channel count.

---

output_format string

Default: mp4

Output video format. Seedance 2.5 exclusive parameter.

• mp4: General format with the best compatibility, using standard color precision. Can be directly played on web, mobile, various players, and distribution platforms.
• mov: High color precision format for professional scenarios, better maintaining color and brightness consistency. Suitable for color grading, keying, compositing, and other professional post-processing that requires high color fidelity. Recommended to use mov format as input and output for video editing and video extension scenarios.

MOV Format Playback Compatibility

The mov format uses professional encoding (H.264 video encoding + yuv444p chroma sampling + PCM audio encoding), and some players may not be compatible. Below are common players that support mov format playback:

Player	macOS	Windows
IINA	✓	✕
VLC	✓	✓
mpv	✓	✓
ffplay	✓	✓

---

tools object[]

Configure the tools the model should call.

Properties:

• tools.type string: Specifies the type of tool to use.
  • web_search: Web search tool. After enabling web search, the model will autonomously decide whether to search internet content (such as products, weather, etc.) based on the user's prompt. This can improve the timeliness of generated videos but will also increase latency.

Note

• The actual number of searches can be obtained through the usage.tool_usage.web_search field returned by the Query Video Generation Task API. If it is 0, it means no search was performed.

---

safety_identifier string

A unique identifier for the end user, used to assist the platform in detecting users in your application who may violate the Volcano Ark usage policy.

This identifier is an English string, should be fixed and unique for a single user, with a length not exceeding 64 characters. It is recommended to pass in a string generated by hashing the username, user ID, or email to avoid leaking user privacy information.

---

priority integer

Default: 0

Sets the execution priority of the current request, determining its position in the queue. Value range: [0, 9], higher values indicate higher priority.

By default, requests will be executed in FIFO (First In, First Out) order. After setting a higher priority, this request will be inserted before all lower priority requests under the same Endpoint.

Note

• Requests with the same priority are still sorted by FIFO
• Priority only affects queue order and will not interrupt tasks that are currently running (status=running)
• Priority only takes effect within the same Endpoint and does not affect tasks in other Endpoints

---

omni_reference_task_type string

Default: auto

Task type guidance. The Seedance 2.5 Multi-Modal Reference Video Generation task includes 3 sub-task types: reference-based video generation, video editing, and video extension. Different task types have special restrictions on parameters. To reduce asynchronous errors after task creation, you can specify the sub-task type through this parameter for early validation of the corresponding restrictions.

• By default, i.e., omni_reference_task_type=auto: the model automatically determines the task type based on the input materials and prompt, then validates the parameter values. If the parameters are incompatible with the actual task type, the task will trigger an asynchronous error.
• Explicitly specifying the task type, i.e., omni_reference_task_type is reference, edit, or extend: the interface performs early validation of the special parameter restrictions for the corresponding task when submitting the task. If the requirements are not met, the interface immediately returns an error and the task will not be created.

Optional Values:

• auto: The model automatically determines the task type based on the input materials and prompt.
• reference: Reference-based video generation task, i.e., generating a new video based on reference images, reference videos, or reference audios. When set to reference, there are no special restrictions on ratio or duration.
• edit: Video editing task, i.e., editing the visuals or audio of the original video. When set to edit, the content must contain at least one reference_video, and the video duration must be 4–30 seconds; ratio must be adaptive; duration must be -1.
• extend: Video extension task, i.e., extending the original video forward or backward. When set to extend, the content must contain at least one reference_video; ratio must be adaptive.

Note: When actually processing the task, the model will further determine the task type in combination with the prompt. If the actually determined task type is inconsistent with the specified one, an asynchronous error will still be triggered. It is recommended to follow the prompt writing guidelines for each task type to reduce the probability of errors.

---

resolution string

Default: 720p

Video resolution. Seedance 2.5 optional values:

• 480p
• 720p
• 1080p

1080p Output Note

The 1080p videos output by Seedance 2.5 use 10-bit color depth and H.265/HEVC encoding. Compared with the general 8-bit color depth, 10-bit color depth retains richer color layers and smoother gradient transitions. H.265/HEVC encoding may not be compatible with a few playback environments. If you encounter issues, it is recommended to upgrade your system, switch devices, or use players such as VLC, MPV, or QuickTime Player.

---

ratio string

Default: adaptive

Aspect ratio of the generated video. Enum values:

• 16:9
• 4:3
• 1:1
• 3:4
• 9:16
• 21:9
• adaptive: Automatically adapts aspect ratio based on task type and input content

Seedance 2.5 Adaptive Adaptation Rules

Task Type	Adaptation Rule
Text-to-Video	Supports setting from optional aspect ratios, or letting the model automatically select based on the prompt. Supports adaptive or specified aspect ratio.
First Frame / First & Last Frame Video Generation	Automatically keeps the output video's aspect ratio consistent with the first frame image, default and only supports adaptive.
Multi-Modal Reference Video Generation (Video Editing/Extension)	Automatically keeps the output video's aspect ratio consistent with the video to be edited/extended, no other settings are supported, default and only supports adaptive.
Multi-Modal Reference Video Generation (Reference-based)	Supports setting from optional aspect ratios, or letting the model automatically select based on the prompt. Supports adaptive or specified aspect ratio.

Width and Height Pixel Values for Different Aspect Ratios (Seedance 2.5)

Resolution	Aspect Ratio	Width × Height (px)
480p	16:9	854×480
	4:3	752×560
	1:1	640×640
	3:4	560×752
	9:16	480×854
	21:9	992×432
720p	16:9	1280×720
	4:3	1112×834
	1:1	960×960
	3:4	834×1112
	9:16	720×1280
	21:9	1470×630
1080p	16:9	1920×1080
	4:3	1664×1248
	1:1	1440×1440
	3:4	1248×1664
	9:16	1080×1920
	21:9	2206×946

---

duration integer

Default: -1

If you want to generate a video with an integer number of seconds, it is recommended to specify duration.

Generated video duration, only supports integers, unit: seconds.

• Seedance 2.5: Value range [4, 30]; or set to -1 (smart selection, the model autonomously selects the appropriate video length within the valid range)

Note: Seedance 2.5 restrictions in video editing tasks:

• Only supports setting duration to -1, does not support specifying specific output duration.
• The input video to be edited must be within [4, 30] s, otherwise an error will be triggered.

Duration Adaptation Rules (duration = -1)

Task Type	Value Rule
Video Editing Task	Automatically keeps the output video's duration basically consistent with the input video (the output duration may be a non-integer number of seconds and may be slightly shorter than the input video, with an error of approximately 0.4 seconds), no other settings are supported.
Other Task Types	The model autonomously selects an appropriate video length (integer seconds) within the valid range of duration.

Duration Return Value Explanation

The duration value returned by the Query Video Generation Task API is an approximate value of the video duration (integer seconds), which may differ from the actual video duration. Specific return rules are as follows:

• Calculation formula: API returned duration = actual total frames / 24 (rounded down)
• Example: If the final generated video is 133 frames, the actual video duration is 133 / 24 = 5.54 seconds; after rounding down, duration finally returns 5

---

watermark boolean

Default: false

Whether the generated video contains a watermark.

• true: The generated video will display an AI Generated watermark in the bottom right corner.
• false: The generated video does not contain a watermark.

---

Response Parameters

id string

Video generation task ID. Only saved for 7 days (calculated from the created_at timestamp), and will be automatically cleared after timeout.

• Set "draft": true: Draft video task ID.
• Set "draft": false: Regular video task ID.

Creating a video generation task is an asynchronous interface. After obtaining id, you need to query the task status through the Query Video Generation Task API. After the task succeeds, the generated video's video_url will be output.