> ## 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.

# Seedance 2.5 Flash 视频生成

> 支持文生视频、多模态参考、视频编辑与延长、首尾帧，输出 480p / 720p、最长 30 秒的视频。

```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": "seedance-2-5-flash",
  "prompt": "A cinematic shot of a fox walking through a sunlit forest, with a slow tracking camera",
  "resolution": "720p",
  "size": "16:9",
  "duration": 8,
  "generate_audio": true,
  "nsfw_check": true,
  "return_last_frame": true
}'
```

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

payload = {
  "model": "seedance-2-5-flash",
  "prompt": "A cinematic shot of a fox walking through a sunlit forest, with a slow tracking camera",
  "resolution": "720p",
  "size": "16:9",
  "duration": 8,
  "generate_audio": True,
  "nsfw_check": True,
  "return_last_frame": True
}
response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const payload = {
  "model": "seedance-2-5-flash",
  "prompt": "A cinematic shot of a fox walking through a sunlit forest, with a slow tracking camera",
  "resolution": "720p",
  "size": "16:9",
  "duration": 8,
  "generate_audio": true,
  "nsfw_check": true,
  "return_last_frame": true
};
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example_seedance25flash"
    }
  ]
}
```

通过 `POST /v1/videos/generations` 提交任务，从 `data[0].task_id` 获取任务 ID，再调用 `GET /v1/tasks/{task_id}` 查询结果。

**Authorization** `string` *required*

使用 `Authorization: Bearer <token>`，其中 `<token>` 为你的 APIMart API Key。

## 请求参数

**model** `string` *required*

使用 `seedance-2-5-flash`。也接受 `doubao-seedance-2-5-flash`；带点写法 `seedance-2.5-flash` 不受支持。

**nsfw\_check** `boolean` (default: false)

是否在提交视频任务前执行内容审核。

* `true`：使用 `omni-moderation-latest` 审核提示词和输入图片
* `false` 或不传：不发起审核请求，不增加审核成本与延迟（默认）

命中时同步返回 HTTP 400（`nsfw_content_detected`），不创建任务、不扣生成费用。参考视频和音频不送审；审核服务异常时请求可能继续提交。

**prompt** `string` *required*

必填提示词。可用 `@图片1` / `@视频1` / `@音频1` 指代参考素材，下标从 1 开始，对应各类数组的顺序。

**resolution** `string` (default: 720p)

仅支持 `480p` / `720p`，默认 `720p`。传入 `1080p`、`2k`、`4k` 等值同步返回 HTTP 400。

**size** `string` (default: adaptive)

支持 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`（默认）；别名为 `aspect_ratio`。首帧 / 首尾帧、视频编辑和延长只能使用 `adaptive`。

**duration** `integer`

整数秒 `4`–`30`，普通请求省略时为 `5`；`-1` 表示由模型决定。显式 `edit` 只能传 `-1` 或省略，省略时按 `-1` 处理，输出时长跟随源视频。自动时长预扣按 30 秒计算，完成后按实际 token 用量结算。

**generate\_audio** `boolean` (default: true)

是否生成声音，默认 `true`；别名为 `audio`。与输入参考音频 `audio_urls` 不同。

**watermark** `boolean` (default: false)

是否添加 AI 生成水印，默认 `false`。

**seed** `integer`

可选随机种子；相同种子不保证结果完全一致。

**output\_format** `string` (default: mp4)

输出封装格式，支持 `mp4`（默认）或 `mov`。

**omni\_reference\_task\_type** `string` (default: auto)

支持 `auto`（默认）、`reference`、`edit`、`extend`，只用于带参考素材的任务。显式指定类型时在提交阶段校验对应限制，见下方任务类型表。

**image\_urls** `string[]`

参考图数组，均按 `reference_image` 处理。与 `image_with_roles` 中的图片合计最多 10 张。首尾帧请使用 `image_with_roles`。

**image\_with\_roles** `object[]`

每项包含 `url` 和 `role`。`role` 支持 `reference_image`、`first_frame`（最多 1 张）、`last_frame`（最多 1 张，与首帧配合）。与 `image_urls` 合计最多 10 张；不要混用冲突的图片角色。存在 `video_urls` / `audio_urls` 时，首尾帧会转为参考图参与多模态任务。

**video\_urls** `string[]`

最多 5 个参考视频，单个 2–30 秒，合计不超过 30 秒。视频编辑的源视频须为 4–30 秒。

**audio\_urls** `string[]`

最多 5 段参考音频，单段 2–30 秒，合计不超过 30 秒。支持纯音频参考，可不配图片或视频。

**return\_last\_frame** `boolean` (default: false)

设为 `true` 时，成功后额外返回尾帧图片，地址位于 `data.result.videos[].last_frame_url`。

**web\_search** `boolean` (default: false)

是否允许模型按需联网搜索，默认 `false`。

**tools** `object[]`

可选工具列表，例如 `[{"type":"web_search"}]`，用于联网搜索。

> [!WARNING]
>
> 不支持 `draft` / `draft_task_id`，请从请求中移除；传入样片字段会同步返回 HTTP 400。需要样片功能时使用 [Seedance 2.5](https://docs.apimart.ai/cn/api-reference/videos/seedance-2-5/generation.md)。

## 素材要求

素材使用公网可访问的 `http(s)` 链接，或已审核通过的 `asset://` 素材 ID。输出分辨率与输入视频的像素限制分别校验。

| 素材 | 限制 |
| - | - |
| 图片 | 两个图片字段合计 ≤10 张；JPEG / PNG / WebP / BMP / TIFF / GIF / HEIC / HEIF；宽、高各 300–6000 px；宽高比 0.4–2.5；单张 `<30 MB`。 |
| 视频 | ≤5 个；MP4 / MOV，视频编码 H.264 / H.265，音轨 AAC / MP3；单个 2–30 秒、合计 ≤30 秒；单个 ≤200 MB；宽、高各 300–6000 px，宽高比 0.4–2.5，宽 × 高为 409,600–8,295,044 像素，帧率 24–60 FPS。 |
| 音频 | ≤5 段；WAV / MP3；单段 2–30 秒、合计 ≤30 秒；单段 ≤15 MB。 |

## 任务类型与限制

| 模式 | 用法与限制 |
| - | - |
| 文生视频 | 提供 `prompt`，不传参考素材；省略 `omni_reference_task_type`。 |
| 参考生视频 | 提供参考素材，可传 `reference`；仍须满足普通时长和比例范围。 |
| 首帧 / 首尾帧 | 使用 `image_with_roles`；`size` / `aspect_ratio` 只能为 `adaptive`。 |
| 视频编辑 | `edit`；至少 1 个参考视频，源视频 4–30 秒；比例只能为 `adaptive`，`duration` 只能为 `-1` 或省略。 |
| 视频延长 | `extend`；至少 1 个参考视频，比例只能为 `adaptive`。 |

显式类型不符合限制时同步返回 HTTP 400，不创建任务、不扣费。`auto` 由模型根据素材和提示词判断任务类型，可能在生成阶段因类型限制而失败；即使显式指定类型，提示词意图不匹配仍可能返回 `InvalidParameter.TaskTypeMismatch`。

## 请求示例

### 多模态参考

```json theme={null}
{
  "model": "seedance-2-5-flash",
  "prompt": "Use the composition of @视频1, the subject in @图片1, and @音频1 as background music",
  "image_urls": [
    "https://example.com/reference.jpg"
  ],
  "video_urls": [
    "https://example.com/reference_8s.mp4"
  ],
  "audio_urls": [
    "https://example.com/music_5s.mp3"
  ],
  "omni_reference_task_type": "reference",
  "duration": 8,
  "size": "16:9"
}
```

### 首尾帧生成

```json theme={null}
{
  "model": "seedance-2-5-flash",
  "prompt": "Smoothly transition from the first frame to the last frame",
  "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": "seedance-2-5-flash",
  "prompt": "Edit @视频1: replace the cloudy sky with a clear sunset while preserving the camera movement",
  "video_urls": [
    "https://example.com/source_10s.mp4"
  ],
  "omni_reference_task_type": "edit",
  "size": "adaptive",
  "duration": -1,
  "output_format": "mov"
}
```

### 视频延长

```json theme={null}
{
  "model": "seedance-2-5-flash",
  "prompt": "Extend @视频1 forward: continue the camera movement as the subject walks into the forest",
  "video_urls": [
    "https://example.com/source_10s.mp4"
  ],
  "omni_reference_task_type": "extend",
  "size": "adaptive",
  "duration": 5
}
```

## 使用私域素材

含真人人脸的参考图或视频应先通过素材库审核，再使用 `asset://`。上传素材时，`model` 也传 `seedance-2-5-flash`。可参考 [素材库接口](https://docs.apimart.ai/cn/api-reference/videos/seedance-2-0/private-avatar.md)，并使用下方 Flash 模型名。

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/seedance2/private-avatar/assets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2-5-flash",
  "group": {
    "name": "flash-assets"
  },
  "asset_type": "Image",
  "assets": [
    {
      "url": "https://example.com/reference.jpg",
      "name": "reference"
    }
  ]
}'
```

通过统一任务接口轮询素材审核任务，审核通过后从素材列表获取 `asset://` ID，填入 `image_urls`、`image_with_roles[].url`、`video_urls` 或 `audio_urls`。

## 查询任务与结果

通过[任务查询接口](https://docs.apimart.ai/cn/api-reference/tasks/status.md)轮询。`pending` / `processing` 表示处理中，`completed` 表示成功，`failed` 表示失败。成功后读取 `data.result.videos[0].url[0]`；注意 `url` 是数组。

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/tasks/task_example_seedance25flash' \
  --header 'Authorization: Bearer <token>'
```

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_seedance25flash",
    "status": "completed",
    "progress": 100,
    "cost": 0.3104,
    "credits_cost": 3.104,
    "usage": {
      "completion_tokens": 38800
    },
    "result": {
      "videos": [
        {
          "url": [
            "https://example.com/generated-video.mp4"
          ],
          "last_frame_url": "https://example.com/generated-last-frame.png"
        }
      ]
    }
  }
}
```

| 字段 | 说明 |
| - | - |
| `data.usage.completion_tokens` | 最终结算使用的 token 数；完成后的最初几秒可能尚未返回，可再次查询。 |
| `data.cost` | 本次实际扣费金额（美元），已含账户优惠，以实际返回为准。 |
| `data.credits_cost` | 本次实际扣除的积分。 |
| `data.result.videos[].url` | 视频地址数组，请及时下载保存。 |
| `data.result.videos[].last_frame_url` | 仅在请求 `return_last_frame: true` 且任务成功时返回的尾帧图片地址。 |
| `data.error.message` | 失败原因；失败任务的 `data.cost` 为 0，预扣费用退回。 |

## 计费规则

* 提交时按分辨率对应的每秒档位预扣；有参考视频时使用带输入档位，预扣秒数为输出时长加参考视频总时长。
* 普通请求未传 `duration` 时按 5 秒输出预扣；`duration: -1` 或 `edit` 省略时长时，按 30 秒输出预扣。
* 成功后按 `data.usage.completion_tokens` 结算：token 数 ÷ 1,000,000 × 对应的每百万 token 单价，再应用账户优惠；与预扣多退少补。是否带参考视频决定使用 `token` 或 `token-input` 档位。最终实扣以 `data.cost` 为准。
* 提交失败不扣生成费用，生成失败退回预扣费用。单价和账户优惠以[价格页](https://apimart.ai/pricing)为准。

## 常见错误

| 场景 | 处理方式 |
| - | - |
| HTTP 400：分辨率不支持 | 仅传 `480p` / `720p`，不要传 `1080p`。 |
| HTTP 400：素材数量超限 | 图片合计 ≤10，视频 ≤5，音频 ≤5，并检查各类时长限制。 |
| HTTP 400：样片字段不支持 | 移除 `draft` / `draft_task_id`。 |
| HTTP 400：类型、时长或比例错误 | 检查 `omni_reference_task_type`、`duration`、`size` / `aspect_ratio` 的组合。 |
| HTTP 400：`nsfw_content_detected` | 按审核拒绝处理，读取 `error.message` 并修改内容。 |
| 模型不存在 | 使用 `seedance-2-5-flash`，不要使用带点的 `seedance-2.5-flash`。 |
| 任务 `failed` | 读取 `data.error.message`；检查素材与提示词是否符合任务类型，预扣费用会退回。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.