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

# doubao-seedance-2.5 视频生成

>  - 异步处理，返回 task_id 用于查询
- 文生视频 / 多模态参考 / 视频编辑 / 视频延长 / 首尾帧
- 单次最长 30 秒；参考素材最多 30 图 + 10 视频 + 10 音频
- 分辨率仅 480p / 720p；支持 mp4 / mov 输出 

<Info>
  **相对 2.0 的主要变化**：时长上限 15s → **30s**；参考素材 9 图 + 3 视频 + 3 音频 → **30 图 + 10 视频 + 10 音频**；支持**纯音频参考**；新增 **mov** 输出。\
  **注意**：分辨率仅 **480p / 720p**（2.0 的 1080p / 4k 在 2.5 **不可用**）。
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "doubao-seedance-2.5",
      "prompt": "一段极具电影感的30秒蒸汽朋克微缩景观序列",
      "size": "16:9",
      "resolution": "720p",
      "duration": 30
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.apimart.ai/v1/videos/generations"

  payload = {
      "model": "doubao-seedance-2.5",
      "prompt": "一段极具电影感的30秒蒸汽朋克微缩景观序列",
      "size": "16:9",
      "resolution": "720p",
      "duration": 30,
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
  }

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

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/videos/generations";

  const payload = {
    model: "doubao-seedance-2.5",
    prompt: "一段极具电影感的30秒蒸汽朋克微缩景观序列",
    size: "16:9",
    resolution: "720p",
    duration: 30,
  };

  const headers = {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload),
  })
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io/ioutil"
      "net/http"
  )

  func main() {
      url := "https://api.apimart.ai/v1/videos/generations"

      payload := map[string]interface{}{
          "model":      "doubao-seedance-2.5",
          "prompt":     "一段极具电影感的30秒蒸汽朋克微缩景观序列",
          "size":       "16:9",
          "resolution": "720p",
          "duration":   30,
      }

      jsonData, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", "Bearer <token>")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      body, _ := ioutil.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  public class Main {
      public static void main(String[] args) throws Exception {
          String url = "https://api.apimart.ai/v1/videos/generations";

          String payload = """
          {
            "model": "doubao-seedance-2.5",
            "prompt": "一段极具电影感的30秒蒸汽朋克微缩景观序列",
            "size": "16:9",
            "resolution": "720p",
            "duration": 30
          }
          """;

          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(url))
              .header("Authorization", "Bearer <token>")
              .header("Content-Type", "application/json")
              .POST(HttpRequest.BodyPublishers.ofString(payload))
              .build();

          HttpResponse<String> response = client.send(request,
              HttpResponse.BodyHandlers.ofString());

          System.out.println(response.body());
      }
  }
  ```

  ```php PHP theme={null}
  <?php

  $url = "https://api.apimart.ai/v1/videos/generations";

  $payload = [
      "model" => "doubao-seedance-2.5",
      "prompt" => "一段极具电影感的30秒蒸汽朋克微缩景观序列",
      "size" => "16:9",
      "resolution" => "720p",
      "duration" => 30
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer <token>",
      "Content-Type: application/json"
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  echo $response;
  ?>
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01KMCGF6BQGN3X28H3KSR50X5T"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "请求参数无效",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "身份验证失败，请检查您的API密钥",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "账户余额不足，请充值后再试",
      "type": "payment_required"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "请求过于频繁，请稍后再试",
      "type": "rate_limit_error"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": 500,
      "message": "服务器内部错误，请稍后重试",
      "type": "server_error"
    }
  }
  ```
</ResponseExample>

## 认证

<ParamField header="Authorization" type="string" required>
  Bearer Token 认证。访问 [API Key 管理页面](https://apimart.ai/keys) 获取密钥。

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

## 请求参数

<ParamField body="model" type="string" required>
  固定值：`doubao-seedance-2.5`
</ParamField>

<ParamField body="prompt" type="string" required>
  提示词。可用 `@图片1` / `@视频1` / `@音频1` 指代参考素材（下标从 1 起，对应数组顺序）。

  示例：`"全程使用@视频1的第一视角构图，@音频1作为背景音乐，首帧为@图片1"`
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  分辨率，**仅支持**：

  * `480p`
  * `720p`（默认）

  传入 `1080p` / `2k` / `4k` 等会同步 **400**。
</ParamField>

<ParamField body="size" type="string" default="adaptive">
  宽高比（也接受字段名 `aspect_ratio`）。

  可选值：`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`（默认）

  <Warning>
    视频编辑、视频延长、首帧/首尾帧任务对 `size` 有硬性限制，见 [任务类型与限制](#任务类型与限制)。
  </Warning>
</ParamField>

<ParamField body="duration" type="integer" default="5">
  时长（秒）：

  * `4` \~ `30`
  * `-1`：模型自动选择时长（提交时按 30 秒上限预扣，完成后按实际产出多退少补）

  未传时按 **5 秒**生成与计费。
</ParamField>

<ParamField body="generate_audio" type="boolean" default="true">
  是否生成音频（也接受字段名 `audio`）。

  * `true`：有声视频（默认）
  * `false`：无声视频
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  是否添加「AI 生成」水印。默认 `false`。
</ParamField>

<ParamField body="seed" type="integer">
  随机种子。相同请求下不同 seed 通常得到不同结果；相同 seed 结果相近但不保证完全一致。
</ParamField>

<ParamField body="output_format" type="string" default="mp4">
  输出封装格式：

  * `mp4`（默认）
  * `mov`：更高色彩精度，**推荐**用于编辑 / 延长场景
</ParamField>

<ParamField body="image_urls" type="array<string>">
  参考图 URL 数组，一律作为 `reference_image`。

  支持：

  * 普通 URL：`https://example.com/pic.jpg`
  * 私域素材：`asset://cm9xxxxxxxx`

  首帧 / 尾帧请用 `image_with_roles`。

  <Warning>
    * 最多 **30** 张
    * 与 `image_with_roles` 不要混用冲突角色语义；首尾帧请走 `image_with_roles`
  </Warning>
</ParamField>

<ParamField body="image_with_roles" type="array<object>">
  带角色的图片数组。

  <Expandable title="字段说明">
    <ParamField body="url" type="string" required>
      图片 URL 或 `asset://...`
    </ParamField>

    <ParamField body="role" type="string" required>
      * `first_frame`：首帧（1 张）
      * `last_frame`：尾帧（1 张，通常与首帧配合）
      * `reference_image`：参考图（合计最多 30 张）
    </ParamField>
  </Expandable>

  示例：

  ```json theme={null}
  [
    {"url": "https://example.com/first.jpg", "role": "first_frame"},
    {"url": "https://example.com/last.jpg", "role": "last_frame"}
  ]
  ```

  <Note>
    若同时存在 `video_urls` / `audio_urls`，`first_frame` / `last_frame` 会自动转为 `reference_image`（多模态参考任务）。
  </Note>
</ParamField>

<ParamField body="video_urls" type="array<string>">
  参考视频 URL 数组（`reference_video`）。支持普通 URL 与 `asset://...`。

  最多 **10** 个；总时长 ≤ **30s**（单段 2\~30s）。
</ParamField>

<ParamField body="audio_urls" type="array<string>">
  参考音频 URL 数组（`reference_audio`）。支持普通 URL 与 `asset://...`。

  最多 **10** 段；总时长 ≤ **30s**（单段 2\~30s）。

  <Note>
    2.5 **支持纯音频参考**（可不配图/视频）。
  </Note>
</ParamField>

<ParamField body="return_last_frame" type="boolean" default="false">
  为 `true` 时，任务成功后额外返回尾帧图片，便于连续生成。
</ParamField>

<ParamField body="tools" type="array<object>">
  工具列表，用于联网搜索等增强能力。

  示例：

  ```json theme={null}
  "tools": [{"type": "web_search"}]
  ```

  <Expandable title="字段说明">
    <ParamField body="type" type="string" required>
      工具类型

      可选值：

      * `web_search` - 联网搜索，生成时参考网络信息
    </ParamField>
  </Expandable>
</ParamField>

## 素材要求

| 素材 | 限制                                                                                                                               |
| -- | -------------------------------------------------------------------------------------------------------------------------------- |
| 图片 | ≤30 张；jpeg / png / webp / bmp / tiff / gif / heic / heif；宽高比 \[0.4, 2.5]；边长 \[300, 6000]px；单张 \<30MB                             |
| 视频 | ≤10 个；mp4 / mov（H.264 / H.265 + AAC / MP3）；单个 \[2, 30]s 且**总时长 ≤30s**；480p / 720p；总像素 \[409600, 8295044]；fps \[24, 60]；单个 ≤200MB |
| 音频 | ≤10 段；wav / mp3；单段 \[2, 30]s 且**总时长 ≤30s**；单个 ≤15MB                                                                              |

## 任务类型与限制

系统会按参考素材与**提示词意图**判定任务类型。后三种对 `size` / `duration` 有硬性限制，**违反会在任务开始后异步失败**（如 `InvalidParameter.TaskTypeConstraint`）：

| 任务类型     | 触发条件                                               | 限制                                                  |
| -------- | -------------------------------------------------- | --------------------------------------------------- |
| 文生视频     | 仅文本                                                | 无                                                   |
| 参考生视频    | 参考素材 + 普通描述提示词                                     | 无。**避免**在提示词中出现「编辑 / 延长 / 续写 / 删除 / 替换」等词，防止误判      |
| 视频编辑     | 参考素材 + 提示词含「编辑视频 / 增加 / 删除 / 修改 / 替换」等             | `size` 仅 `adaptive`，`duration` 仅 `-1`；待编辑视频须 4\~30s |
| 视频延长     | 参考素材 + 提示词含「向前 / 向后延长 / 延续 / 续写」                   | `size` 仅 `adaptive`                                 |
| 首帧 / 首尾帧 | `image_with_roles` 使用 `first_frame` / `last_frame` | `size` 仅 `adaptive`（提交阶段也会同步校验）                     |

## 私域素材库（`asset://`）

与 [Seedance 2.0 私域虚拟人像](/cn/api-reference/videos/doubao-seedance-2-0/private-avatar) 相同：在 `image_urls` / `image_with_roles` / `video_urls` / `audio_urls` 中可直接使用已审核通过的素材 ID：

```json theme={null}
"video_urls": ["asset://cm9xxxxxxxx"]
```

已提交素材对 **2.0 / 2.5 通用**。

## 计费

* 按 **秒 × 分辨率档** 计费。
* **有参考视频输入时**：计费秒数 = 输入视频总时长（≤30s）+ 输出时长，走带输入参考的优惠档单价。
* `duration = -1`（自动时长）：提交时按上限 **30 秒**预扣，完成后按**实际产出**多退少补。
* 未传 `duration`：按 **5 秒**生成与计费。
* 任务失败或内容审核拦截：**全额退款**（仅成功出片收费）。

## 请求示例

### 文生视频（30 秒）

```json theme={null}
{
  "model": "doubao-seedance-2.5",
  "prompt": "一段极具电影感的30秒蒸汽朋克微缩景观序列",
  "size": "16:9",
  "resolution": "720p",
  "duration": 30
}
```

### 多模态参考（图 + 视频 + 音频）

```json theme={null}
{
  "model": "doubao-seedance-2.5",
  "prompt": "全程使用@视频1的第一视角构图，@音频1作为背景音乐，首帧为@图片1",
  "image_urls": [
    "https://example.com/pic1.jpg",
    "https://example.com/pic2.jpg"
  ],
  "video_urls": ["https://example.com/ref.mp4"],
  "audio_urls": ["https://example.com/bgm.mp3"],
  "size": "16:9",
  "duration": 11
}
```

### 视频编辑

```json theme={null}
{
  "model": "doubao-seedance-2.5",
  "prompt": "编辑视频：删除 @视频1 中的所有路人，只保留主角",
  "video_urls": ["https://example.com/input.mp4"],
  "size": "adaptive",
  "duration": -1,
  "output_format": "mov"
}
```

### 首尾帧生视频

```json theme={null}
{
  "model": "doubao-seedance-2.5",
  "prompt": "图中女孩对着镜头说\"茄子\"，360度环绕运镜",
  "image_with_roles": [
    {"url": "https://example.com/first.jpg", "role": "first_frame"},
    {"url": "https://example.com/last.jpg", "role": "last_frame"}
  ],
  "size": "adaptive",
  "duration": 5
}
```

### 私域素材

```json theme={null}
{
  "model": "doubao-seedance-2.5",
  "prompt": "人物在城市街道自然行走，阳光明媚",
  "image_urls": ["asset://cm9xxxxxxxx"],
  "duration": 5,
  "resolution": "720p"
}
```

### 联网搜索

```json theme={null}
{
  "model": "doubao-seedance-2.5",
  "prompt": "根据最新资讯生成一段科技新闻短视频开场",
  "size": "16:9",
  "resolution": "720p",
  "duration": 8,
  "tools": [{"type": "web_search"}]
}
```

## 常见错误

| 现象                                                             | 原因                                                |
| -------------------------------------------------------------- | ------------------------------------------------- |
| 400 `This model only supports 480p or 720p resolution`         | 传了 1080p / 2k / 4k 等，2.5 不支持                      |
| 400 `This model only supports duration 4-30 seconds, or -1`    | `duration` 不在允许范围                                 |
| 400 `first_frame/last_frame tasks only support ratio=adaptive` | 首尾帧任务指定了具体宽高比                                     |
| 任务异步失败（编辑 / 延长类提示）                                             | 提示词被判定为编辑 / 延长，但 `size` / `duration` 不满足对应限制（见上表） |
| 任务异步失败 `SensitiveContentDetected`                              | 素材或产物触发内容审核                                       |

## 响应

<ResponseField name="code" type="integer">
  响应状态码，成功时为 200
</ResponseField>

<ResponseField name="data" type="array">
  提交时返回 `status` / `task_id`

  <Expandable title="数组元素">
    <ResponseField name="status" type="string">
      初始为 `submitted`
    </ResponseField>

    <ResponseField name="task_id" type="string">
      任务 ID，用于 [查询状态](/cn/api-reference/tasks/status)
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  使用 [获取任务状态](/cn/api-reference/tasks/status) 轮询。成功后取 `result.videos[0].url`（已转存，长期有效）。`return_last_frame=true` 时结果中附尾帧图片。
</Note>

## 与 2.0 的差异

| 特性            | 2.0                      | 2.5                    |
| ------------- | ------------------------ | ---------------------- |
| 模型名           | `doubao-seedance-2.0` 等  | `doubao-seedance-2.5`  |
| 时长            | 约 4\~15s                 | **4\~30s**，或 `-1` 自动   |
| 分辨率           | 480p / 720p / 1080p / 4k | **仅 480p / 720p**      |
| 参考图           | ≤9                       | **≤30**                |
| 参考视频          | ≤3，总时长约 \<15s            | **≤10，总时长 ≤30s**       |
| 参考音频          | ≤3，总时长 ≤15s              | **≤10，总时长 ≤30s**；支持纯音频 |
| 输出格式          | 主要为 mp4                  | **mp4 / mov**          |
| 水印            | —                        | `watermark`            |
| 私域 `asset://` | 支持                       | **通用**（同一私域接口）         |