> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance 2.5 Video Generation

> Generate videos with the Seedance 2.5 model

Seedance 2.5 uses the public model name `seedance-2-5` and the upstream model ID `doubao-seedance-2-5-260628`.

* Supports text-to-video, first-frame / first-last-frame image-to-video, editing, video extension, and multimodal reference workflows.
* Supports image, video, and audio references, including audio-only references.
* The task is asynchronous. The submit API returns a `generation.task`; fetch the finished video from the task status API.

## Authorizations

<ParamField header="Authorization" type="string" required>
  Use Bearer Token authentication for every request.

  Get an API key from the [API Key Management Page](https://toapis.com/console/token).

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" default="seedance-2-5" required>
  Public ToAPIs model name. Use `seedance-2-5`.
</ParamField>

<ParamField body="prompt" type="string">
  Describe the scene, camera movement, subject action, style, and audio mood. When referring to media, use labels such as “image 1”, “video 1”, or “audio 1”.
</ParamField>

<ParamField body="video_operation" type="string" default="generate">
  Video operation: `generate`, `edit`, or `extend`. Editing and extension require at least one `video_with_roles`; extension requires a positive `duration`. All three operations use this endpoint.
</ParamField>

<ParamField body="client_business_id" type="string">
  Your order number or internal job ID. It is stored with the task and can be used for later lookup with `GET /v1/videos/generations/{client_business_id}`.
</ParamField>

<ParamField body="duration" type="integer">
  Duration in seconds. The official range is `4`–`30`; use `-1` for automatic duration. Editing, extension, and first/last-frame tasks require `-1` where specified by the upstream task type.
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Output aspect ratio. Allowed values: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, and `adaptive`.

  Use `adaptive` for editing, video extension, and first/last-frame tasks, or when the input media should determine the ratio.
</ParamField>

<ParamField body="image_urls" type="string[]">
  Compatibility image URL array. For new integrations, prefer `image_with_roles` so each image has an explicit role. Do not send both fields in one request.
</ParamField>

<ParamField body="image_with_roles" type="array">
  Images with explicit roles. Each item contains a required `url` and `role`.

  Roles: `first_frame`, `last_frame`, or `reference_image`.

  Up to 30 images may be supplied. First/last-frame mode and reference-image mode are mutually exclusive.
</ParamField>

<ParamField body="video_with_roles" type="array">
  Reference videos. Each item contains a required `url` and the role `reference_video`. Up to 10 videos may be supplied.
</ParamField>

<ParamField body="audio_with_roles" type="array">
  Reference audio. Each item contains a required `url` and the role `reference_audio`. Up to 10 audio clips may be supplied. Audio-only reference input is supported.
</ParamField>

<ParamField body="resolution" type="string">
  Output resolution: `480p` or `720p`.
</ParamField>

<ParamField body="output_format" type="string" default="mp4">
  Supported formats are `mp4` and `mov`.
</ParamField>

<ParamField body="generate_audio" type="boolean" default={true}>
  Whether to generate synchronized audio.
</ParamField>

<ParamField body="return_last_frame" type="boolean" default={false}>
  Whether to return the generated video's last-frame image in the completed task result.
</ParamField>

<ParamField body="tools" type="array">
  Optional tools. The supported value is `[{ "type": "web_search" }]`.

  Web search is for text-to-video requests and cannot be combined with image, video, or audio inputs.
</ParamField>

<ParamField body="callback_url" type="string">
  ToAPIs task-completion callback URL. See [Task Webhooks](/docs/en/api-reference/webhooks/task-webhooks).
</ParamField>

<ParamField body="trace_id" type="string">
  A caller-supplied tracing ID.
</ParamField>

## Reference input limits

The combined limit is 50 reference items: up to 30 images, 10 videos, and 10 audio clips. Use explicit roles to avoid ambiguous frame/reference interpretation.

<Warning>
  Invalid task-type combinations may be accepted asynchronously and later fail with `InvalidParameter.TaskTypeConstraint`. For editing, extension, and first/last-frame tasks, set `aspect_ratio` to `adaptive` as required by the upstream API.
</Warning>

## Response

<ResponseField name="id" type="string">Task ID used to query status.</ResponseField>
<ResponseField name="client_business_id" type="string">Returned when `client_business_id` was supplied.</ResponseField>
<ResponseField name="object" type="string">Fixed to `generation.task`.</ResponseField>
<ResponseField name="model" type="string">The requested model name.</ResponseField>
<ResponseField name="status" type="string">`queued`, `in_progress`, `completed`, or `failed`.</ResponseField>
<ResponseField name="progress" type="integer">Progress percentage from `0` to `100`.</ResponseField>
<ResponseField name="created_at" type="integer">Creation timestamp.</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://toapis.com/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "seedance-2-5",
      "prompt": "A cinematic product shot, slow camera push-in, natural room tone.",
      "duration": 10,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true
    }'
  ```

  ```json Multimodal reference request theme={null}
  {
    "model": "seedance-2-5",
    "prompt": "Use image 1 for the character, video 1 for motion, and audio 1 for rhythm.",
    "duration": 12,
    "aspect_ratio": "16:9",
    "image_with_roles": [{"url": "https://example.com/ref.png", "role": "reference_image"}],
    "video_with_roles": [{"url": "https://example.com/motion.mp4", "role": "reference_video"}],
    "audio_with_roles": [{"url": "https://example.com/rhythm.mp3", "role": "reference_audio"}]
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "tsk_vid_xxx",
    "object": "generation.task",
    "model": "seedance-2-5",
    "status": "in_progress",
    "progress": 10,
    "created_at": 1781577600
  }
  ```
</ResponseExample>