# Seedance API：首尾帧、参考图、时长与分辨率参数及报错

Source: https://ofox.io/zh/docs/develop/models/seedance

字节跳动的视频生成模型，共四款，通过 OfoxAI 视频接口 `POST /v1/videos` 调用。任务以异步方式执行：创建任务后获得任务 ID，再通过该 ID 查询结果。

## 模型选择

**要点**:需要 4K 输出时选用 2.0；需要 30 秒时长或 21:9 画幅时选用 2.5；批量生成 480p、720p 视频时选用 Mini 或 Fast。

| 模型 | 分辨率（默认） | 时长 | 画幅 |
|---|---|---|---|
| Seedance 2.5 | `480p` `720p` `1080p`（`720p`） | 4–30 秒 | `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `adaptive` |
| Seedance 2.0 | `480p` `720p` `1080p` `4k`（`1080p`） | 4–15 秒 | `16:9` `9:16` `1:1` `adaptive` |
| Seedance 2.0 Fast | `480p` `720p`（`720p`） | 4–15 秒 | 同 2.0 |
| Seedance 2.0 Mini | `480p` `720p`（`720p`） | 4–15 秒 | 同 2.0 |

四款均支持文生视频、图生视频与视频参考，并可生成同步音轨（`generate_audio` 默认为 `true`）。`adaptive` 表示沿用输入图片的比例。

**模型 ID（调用时原样复制）**

- Seedance 2.5: `bytedance/seedance-2.5` — 30 秒、21:9
- Seedance 2.0: `bytedance/seedance-2.0` — 4K
- Seedance 2.0 Fast: `bytedance/seedance-2.0-fast` — 480p、720p
- Seedance 2.0 Mini: `bytedance/seedance-2.0-mini` — 480p、720p

上表与 [Models API](https://ofox.io/zh/docs/api/openai/models) 返回的 `video_attributes` 一致；模型能力如有调整，以接口返回为准。按秒计费，实际费用以任务结果中的 `usage.video_cost` 为准，价格请参阅[模型页](https://ofox.io/zh/models/bytedance/seedance-2.5)。

**请显式传入 `resolution` 与 `duration`。** 未传入时 2.0 默认为 `1080p`，费用按分辨率档位计算，高于 `720p`。

## 调用示例

**要点**:五种生成模式共用一个接口，由传入的素材字段决定模式，无需指定模式参数。

以下示例只展示创建任务的请求。创建后查询状态、下载结果的完整流程见 [Video API · 快速开始](https://ofox.io/zh/docs/api/videos#quickstart)。

**文生视频**

仅传 `prompt`。

```bash filename="Terminal"
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0-mini",
    "prompt": "一只狐狸在雪地里奔跑，镜头跟随",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
```

**图生视频**

`frame_images` 传入 1 张 `first_frame`，视频以该图片作为首帧。画幅可设为 `adaptive`，沿用图片比例。

```bash filename="Terminal"
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "画面中的狗向镜头奔跑",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive",
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/dog.jpg" }, "frame_type": "first_frame" }
    ]
  }'
```

**首尾帧**

`frame_images` 传入 `first_frame` 与 `last_frame`，生成两帧之间的过渡。仅传 `last_frame` 会返回 400。

```bash filename="Terminal"
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "花苞缓缓绽放成一朵盛开的玫瑰",
    "duration": 5,
    "resolution": "720p",
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/bud.jpg" }, "frame_type": "first_frame" },
      { "type": "image_url", "image_url": { "url": "https://example.com/rose.jpg" }, "frame_type": "last_frame" }
    ]
  }'
```

**参考图**

`input_references` 传入图片（最多 9 张），用于保持人物、商品或风格一致，不作为固定画面。建议在提示词中以「图 1」「图 2」指代各图片。

```bash filename="Terminal"
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.5",
    "prompt": "图 1 的女孩拿着图 2 的杯子，在咖啡馆窗边微笑",
    "duration": 5,
    "resolution": "720p",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/girl.jpg" } },
      { "type": "image_url", "image_url": { "url": "https://example.com/cup.jpg" } }
    ]
  }'
```

**音视频参考**

`input_references` 可混合传入图片、音频（最多 3 段，每段不超过 15 秒）与视频（最多 1 段）。以视频为输入时，计费秒数可能包含输入视频的时长。

```bash filename="Terminal"
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "角色以这段配音的语气说话，镜头风格参考这段视频",
    "duration": 5,
    "resolution": "720p",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/character.jpg" } },
      { "type": "audio_url", "audio_url": { "url": "https://example.com/voice.mp3" } },
      { "type": "video_url", "video_url": { "url": "https://example.com/style-ref.mp4" } }
    ]
  }'
```

- `frame_images` 与 `input_references` 不可同时传入，同时传入返回 `400 references_conflict`。
- 图片可使用公网 URL，也可使用以 `data:image/...;base64,` 开头的字符串。
- 不需要音轨时传入 `"generate_audio": false`。
- 字段结构的完整说明见[创建视频任务](https://ofox.io/zh/docs/api/videos/create)。

## 真人参考图

**要点**:通过 OfoxAI 调用时，无需完成 Seedance 的素材库认证，在请求顶层加入 `real_person: true` 即可。

字节官方的 Seedance 接口不允许直接上传含真人面部的参考图或视频。[BytePlus Seedance 2.0 官方文档](https://docs.byteplus.com/en/docs/modelark/1520757)要求使用已授权的真人人像素材，[火山方舟真人人像库指南](https://www.volcengine.com/docs/82379/2315856)列出了发起邀约、本人认证授权、上传素材、接收授权并获取素材 ID 等步骤。

| 步骤 | 直连 Seedance 官方接口 | 通过 OfoxAI 调用 |
|---|---|---|
| 首次请求前 | 创建素材组、完成真人认证与授权、上传并校验素材、取得素材 ID | 无需在供应商平台预先入库 |
| 参考图传参 | 使用已生效的授权素材 `asset://<asset_id>` | 在 `frame_images` 或 `input_references` 中传入图片 URL 或 `data:` URI |
| 请求开关 | 改用审核通过的素材 URI | 请求顶层加入 `"real_person": true` |

```json
{
  "model": "bytedance/seedance-2.0",
  "prompt": "画面中的人物走过电影感夜市",
  "duration": 5,
  "resolution": "720p",
  "real_person": true,
  "input_references": [
    { "type": "image_url", "image_url": { "url": "https://example.com/person.jpg" } }
  ]
}
```

- OfoxAI 会在提交前对参考图进行隐私预处理，可减少上游反深度伪造审核的误拒，但不能保证上游一定接受；被上游拒绝的任务不计费。
- `real_person` 是处理指令，不是授权证明。请仅提交依法有权且已获授权使用的图片。
- 图片仍被拒绝时的调整方法与预处理错误码，见[真人参考图](https://ofox.io/zh/docs/api/videos/real-person)。

## 指定供应商

**要点**:Seedance 由两家供应商承载，审核尺度不同；不指定时由网关按权重分流。

| 供应商 | 说明 | 内容审核 |
|---|---|---|
| `volcengine` | 火山引擎方舟，字节跳动国内平台 | 标准审核 |
| `byteplus` | BytePlus，字节跳动海外平台 | 允许不适合所有受众（NSFW）的内容 |

需要固定供应商时，在请求顶层加入：

```json
"provider": { "type": "byteplus" }
```

需要生成不适合所有受众的内容时，必须显式指定 `byteplus`。未指定时请求可能被分流至 `volcengine`，并因内容审核被拒绝。指定供应商后，若该供应商不可用，请求不会自动切换。

`provider.type` 的取值错误返回 `400 invalid_provider_type`；指定的供应商未承载该模型返回 `400 provider_type_unavailable`。通用说明见[视频供应商路由](https://ofox.io/zh/docs/api/videos/provider-routing)。

## 常见报错

**要点**:参数校验错误在创建时即返回，不会创建任务，也不产生费用。报错信息中会列出允许的取值。

| HTTP · code | 报错原文 | 原因 | 处理方法 |
|---|---|---|---|
| 400 `unsupported_parameter` | `duration 3 out of range [4, 15]` | 时长超出该模型范围 | 2.0 系列为 4–15 秒，2.5 为 4–30 秒 |
| 400 `unsupported_parameter` | `resolution "1080p" not supported; allowed: [480p 720p]` | Fast、Mini 不支持 1080p | 改用 `720p`，或改用 2.0 / 2.5 |
| 400 `unsupported_parameter` | `resolution "4k" not supported; allowed: [480p 720p 1080p]` | 仅 2.0 支持 4K | 改用 `bytedance/seedance-2.0` |
| 400 `unsupported_parameter` | `aspect_ratio "21:9" not supported; allowed: [16:9 9:16 1:1 adaptive]` | 2.0 系列不支持 21:9 | 改用 2.5，或改用支持的比例 |
| 400 `references_conflict` | `frame_images and input_references are mutually exclusive` | 同时传入了两种素材字段 | 两者只能选择其一，见[调用示例](#examples) |
| 400 `invalid_request` | `frame_images: last_frame requires a first_frame` | 仅传入了尾帧 | 补充 `first_frame` |
| 400 `too_many_references` | `input_references over limit: images 10/9, audios 0/3, videos 0/1` | 参考素材超过上限 | 图片最多 9 张、音频最多 3 段、视频最多 1 段 |
| 400 `invalid_request` | `real_person requires at least one image reference` | 启用了 `real_person` 但未传入图片 | 补充图片，或移除 `real_person` |
| 400 `invalid_request` | `cannot unmarshal string into Go struct field CreateVideoRequest.duration of type int` | `duration` 传入了字符串，如 `"5s"` | 改为整数，如 `5` |
| 400 `invalid_callback_url` | `callback_url must be a public HTTPS URL` | 回调地址不是 HTTPS，或为内网地址 | 改为公网 HTTPS 地址 |
| 404 `model_not_found` | `model not found` | 模型 ID 拼写错误，如 `bytedance/seedance-2` | 从本页复制模型 ID |
| 402 `insufficient_credits` | — | 余额不足以支付预估费用（任务不会被创建） | 充值后重试 |

任务创建成功后若在生成阶段失败，查询结果为 `status: "failed"`，失败原因见 `error` 字段；超时对应 `error.code: "expired"`。完整错误码见 [Video API 错误码](https://ofox.io/zh/docs/api/videos/errors)。

## 官方文档
- [BytePlus Seedance 2.0 视频生成 API](https://docs.byteplus.com/en/docs/modelark/1520757)
- [火山方舟文档中心](https://www.volcengine.com/docs/82379)
- [OfoxAI · 创建视频任务](https://ofox.io/zh/docs/api/videos/create)

## 常见问题

**Seedance 怎么做首尾帧视频？**

在 frame_images 中传入两张图片，一张 frame_type 为 first_frame，一张为 last_frame。只传 last_frame 会返回 400 last_frame requires a first_frame。frame_images 不能和 input_references 同时传。

**Seedance 2.0 支持 4K 吗？**

只有 bytedance/seedance-2.0 支持 4k。2.5 最高 1080p，Fast 和 Mini 最高 720p，传入不支持的分辨率会返回 400，报错信息中会列出允许的取值。

**Seedance 最长能生成多少秒？**

Seedance 2.5 单个任务 4 至 30 秒，2.0、2.0 Fast、2.0 Mini 为 4 至 15 秒。超出范围返回 400 duration out of range。

**Seedance 支持 21:9 吗？**

只有 Seedance 2.5 支持 21:9。2.0 系列只支持 16:9、9:16、1:1 和 adaptive。

**Seedance 参考图里有真人报错怎么办？**

直连官方需要先在素材库完成本人认证。通过 OfoxAI 调用，在请求顶层加 real_person: true 即可直接传图，OfoxAI 会先做隐私预处理。仍被上游拒绝时不计费，可按真人参考图页面的建议调整图片后重试。

**Seedance 一次最多能传几张参考图？**

input_references 最多 9 张图片、3 段音频（每段不超过 15 秒）、1 段视频。超出返回 400 too_many_references。

**Seedance 视频生成后的地址多久失效？**

优先使用 mirror_urls。只返回 unsigned_urls 时，是上游的临时地址，可能 24 小时后失效，请及时下载保存。