<!-- Generated by web/scripts/generate-public-discovery.mjs from web/src/data/onboarding-md. Do not edit by hand. -->

# Seedance 视频生成

这一页解决：用 `seedance-2.0-mini` 生成一段视频，从提交任务到拿到 MP4。

- 令牌分组选 **`seedance`**，模型名写 **`seedance-2.0-mini`**。这个分组的令牌只能生成视频，不能调聊天或画图模型。
- 生成是异步的：`POST /v1/videos` 提交任务，`GET /v1/videos/{id}` 轮询到 `completed`，再下载视频。
- 按视频实际生成的 token 数计费。提交时先预扣一笔固定额度，完成后按实际用量结算，多退少补；失败全额退回。
- 视频生成后请马上转存到自己这边，结果地址会失效。

文生视频、首帧 / 首尾帧生视频、参考图 / 参考视频 / 参考音频都支持。480p、720p 两档分辨率，4 到 15 秒。

---

## 1. 准备

1. 控制台 → **API Key** → **添加令牌**，分组选 `seedance`。单独建一个令牌给视频用，不要和聊天模型共用。
2. 复制 `sk-...`。下文用 `$BEEFAPI_KEY` 代替。

```bash
export BEEFAPI_KEY="sk-..."
```

Base URL 是 `https://beefapi.com`。所有请求带：

```http
Authorization: Bearer $BEEFAPI_KEY
Content-Type: application/json
```

---

## 2. 三步跑通

### 第一步：提交任务

```bash
curl -sS -X POST "https://beefapi.com/v1/videos" \
  -H "Authorization: Bearer $BEEFAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-mini",
    "prompt": "一只橘猫趴在窗台上晒太阳，微风吹动窗帘，镜头缓慢推近",
    "seconds": "5",
    "metadata": {
      "resolution": "720p",
      "ratio": "16:9"
    }
  }'
```

返回：

```json
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "seedance-2.0-mini",
  "status": "queued",
  "created_at": 1757400000
}
```

记下 `id`，后面查询和下载都用它。

### 第二步：轮询状态

```bash
curl -sS "https://beefapi.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Authorization: Bearer $BEEFAPI_KEY"
```

`status` 会从 `queued` 变成 `in_progress`，最后是 `completed` 或 `failed`。建议每 5 秒查一次；一段 5 秒的视频通常几分钟内完成，时长越长、素材越多越慢。

```bash
TASK_ID="task_xxxxxxxxxxxxxxxxxxxxxxxx"
while true; do
  RESULT=$(curl -sS "https://beefapi.com/v1/videos/$TASK_ID" \
    -H "Authorization: Bearer $BEEFAPI_KEY")
  STATUS=$(printf '%s' "$RESULT" | jq -r '.status')
  echo "$STATUS"
  case "$STATUS" in
    completed) echo "$RESULT" | jq '{id,status,metadata}'; break ;;
    failed) echo "$RESULT" | jq .; break ;;
    *) sleep 5 ;;
  esac
done
```

完成时的响应：

```json
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "seedance-2.0-mini",
  "status": "completed",
  "progress": 100,
  "created_at": 1757400000,
  "completed_at": 1757400120,
  "metadata": {
    "url": "https://.../xxxx.mp4"
  }
}
```

### 第三步：下载视频

两种方式任选：

```bash
# 方式 A：直接下载 metadata.url
curl -sS -L "<metadata.url>" -o result.mp4

# 方式 B：通过 BeefAPI 下载，带同一个 API Key
curl -sS -L "https://beefapi.com/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $BEEFAPI_KEY" \
  -o result.mp4
```

两种方式取的是同一份结果。结果地址会在一段时间后失效，失效后两种方式都拿不到文件，所以生成完成后请立刻把视频存到自己的存储里。

任务未完成时方式 B 会返回 JSON 错误而不是视频，先确认 `status` 是 `completed`。

---

## 3. 请求参数

`POST /v1/videos` 的 JSON 字段：

| 字段       | 类型   | 必填 | 说明                                                                                                                           |
| ---------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------ |
| `model`    | string | 是   | 固定写 `seedance-2.0-mini`                                                                                                     |
| `prompt`   | string | 是   | 画面、运动、镜头、对白的描述。中文建议 500 字以内，英文 1000 词以内。想要角色开口说话，把台词放在双引号里                      |
| `seconds`  | string | 否   | 视频时长，**用字符串**，如 `"5"`，模型支持 4 到 15 秒。不写则由模型自选时长，费用随之变化，想控制成本请显式写                  |
| `image`    | string | 否   | 一张图片：公网 HTTPS 地址，或 `data:image/png;base64,...`。模型会把它当作首帧。要严格锁首帧或做首尾帧，改用 `metadata.content` |
| `metadata` | object | 否   | 其余控制项，见下表                                                                                                             |

顶层的整数 `duration` 字段**不会生效**。时长只认字符串 `seconds`，或下表里的 `metadata.duration`。

`metadata` 里可以放：

| 字段             | 类型    | 说明                                                                                 |
| ---------------- | ------- | ------------------------------------------------------------------------------------ |
| `resolution`     | string  | `480p` 或 `720p`，其他值会在提交时被拒绝。不写则不传，由模型按默认档生成；建议显式写 |
| `ratio`          | string  | `16:9` `9:16` `1:1` `4:3` `3:4`。不写则不传，模型会按输入素材自动选比例              |
| `duration`       | integer | 写整数 `5`，与 `seconds` 同义。两者都写时以 `seconds` 为准                           |
| `generate_audio` | boolean | 不写则不传，模型默认生成有声视频。要无声视频请显式写 `false`                         |
| `camera_fixed`   | boolean | `true` 固定机位                                                                      |
| `watermark`      | boolean | `true` 加模型水印                                                                    |
| `seed`           | integer | 固定种子便于复现                                                                     |
| `content`        | array   | 首尾帧、参考图、参考视频、参考音频。写了它，顶层 `image` 会被忽略，见下一节          |

不要传 `draft`、`service_tier`、`tools`，这几项当前没有价格，提交会被拒绝。

---

## 4. 图片、视频、音频输入

`metadata.content` 是一个数组，每项写明类型和用途（`role`）。提示词仍写在顶层 `prompt`，不用放进 `content`。

| 用途     | `type`      | `role`            | 数量                                                      |
| -------- | ----------- | ----------------- | --------------------------------------------------------- |
| 首帧     | `image_url` | `first_frame`     | 1 张                                                      |
| 尾帧     | `image_url` | `last_frame`      | 1 张，须与首帧同时出现                                    |
| 参考图   | `image_url` | `reference_image` | 最多 9 张                                                 |
| 参考视频 | `video_url` | `reference_video` | 最多 3 个，总时长不超过 15 秒                             |
| 参考音频 | `audio_url` | `reference_audio` | 最多 3 段，总时长不超过 15 秒；必须同时有参考图或参考视频 |

三种玩法互斥，一次请求只选一种：**首帧**、**首尾帧**、**参考素材**（参考图 / 视频 / 音频任意组合）。

素材要求。不满足时提交可能成功，但任务会在生成阶段失败，常见原因就是下面这些：

- 图片：jpeg / png / webp / bmp / tiff / gif，宽高比 0.4 到 2.5，边长 300 到 6000 像素，单张小于 30 MB。
- 视频：mp4 / mov，单个 2 到 15 秒，小于 200 MB，帧率 24 到 60。
- 音频：wav / mp3，单段 2 到 15 秒，小于 15 MB。
- 地址必须是公网可访问的 HTTPS。大文件不要用 base64，改用地址。
- 参考图和参考视频不能含真人人脸。

### 首尾帧

```bash
curl -sS -X POST "https://beefapi.com/v1/videos" \
  -H "Authorization: Bearer $BEEFAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-mini",
    "prompt": "从第一张图的清晨慢慢过渡到第二张图的黄昏，光线自然变化",
    "seconds": "6",
    "metadata": {
      "resolution": "720p",
      "content": [
        { "type": "image_url", "image_url": { "url": "https://example.com/morning.png" }, "role": "first_frame" },
        { "type": "image_url", "image_url": { "url": "https://example.com/dusk.png" }, "role": "last_frame" }
      ]
    }
  }'
```

### 参考图 + 参考视频

```bash
curl -sS -X POST "https://beefapi.com/v1/videos" \
  -H "Authorization: Bearer $BEEFAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-mini",
    "prompt": "让图 1 里的角色按视频 1 的动作跳舞，场景保持图 1 的风格",
    "seconds": "8",
    "metadata": {
      "resolution": "480p",
      "ratio": "9:16",
      "content": [
        { "type": "image_url", "image_url": { "url": "https://example.com/character.png" }, "role": "reference_image" },
        { "type": "video_url", "video_url": { "url": "https://example.com/dance.mp4" }, "role": "reference_video" }
      ]
    }
  }'
```

带参考视频的任务按更低的单价计费，见第 6 节。

---

## 5. 状态与错误

### 任务状态

| `status`      | 含义                                       |
| ------------- | ------------------------------------------ |
| `queued`      | 已提交，排队中                             |
| `in_progress` | 正在生成                                   |
| `completed`   | 成功，`metadata.url` 是视频地址            |
| `failed`      | 失败，`error.message` 说明原因，费用已退回 |

失败示例：

```json
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "seedance-2.0-mini",
  "status": "failed",
  "error": {
    "code": "InvalidParameter",
    "message": "..."
  }
}
```

### 提交时的常见错误

| HTTP      | 现象                                                     | 怎么办                                                                          |
| --------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 400       | `prompt is required`                                     | `prompt` 不能为空                                                               |
| 400       | `invalid_request`，提到 `seconds`                        | `seconds` 要写成字符串 `"5"`，不要写数字 `5`                                    |
| 400       | `resolution "1080p" has no configured video token price` | 只支持 `480p` / `720p`                                                          |
| 400       | 提到 `draft` / `service tier` / `tools`                  | 去掉这几个字段                                                                  |
| 401       | 未授权                                                   | 检查 `Authorization` 头和 key 是否完整                                          |
| 404       | `model_not_found`                                        | 令牌分组不是 `seedance`，重建令牌并选对分组                                     |
| 402 / 403 | 余额不足                                                 | 提交时余额要够付第 6 节的预扣额度；长视频的最终金额可能高于预扣，充值时留出余量 |

任务提交成功但最终 `failed`，常见原因是素材不符合第 4 节的要求、含人脸，或内容审核未通过。以 `error.message` 为准。

---

## 6. 价格

按视频实际生成的 **token 数**计费，控制台 → 日志里每条任务都能看到实际 token 和最终金额。

`seedance` 分组当前价格（2026-09-09 核对，以 [模型广场](https://beefapi.com/pricing) 实时展示为准）：

| 输入方式     | 480p / 720p 单价        |
| ------------ | ----------------------- |
| 不含参考视频 | ¥18.99 / 百万视频 token |
| 含参考视频   | ¥11.39 / 百万视频 token |

480p 和 720p 每 token 同价，但 720p 每秒产生的 token 大约是 480p 的 2.2 倍。按 16:9、24 帧的标准规格估算：

| 分辨率 | 每秒 token 数 | 不含参考视频  | 含参考视频    |
| ------ | ------------- | ------------- | ------------- |
| 480p   | 约 10,044     | 约 ¥0.19 / 秒 | 约 ¥0.11 / 秒 |
| 720p   | 约 21,600     | 约 ¥0.41 / 秒 | 约 ¥0.25 / 秒 |

几个常见组合的估算：5 秒 480p 约 ¥0.95；5 秒 720p 约 ¥2.05；15 秒 720p 约 ¥6.15。实际帧数不同会有小幅偏差，最终以日志里的实际 token 为准。

扣费流程：

1. 提交时先预扣一笔**固定额度**，与你写的时长、分辨率无关：不含参考视频约 ¥4.75，含参考视频约 ¥2.85（按上表价格换算，随价格调整）。余额不够这笔预扣就提交不了。
2. 任务成功后按实际 token 结算：预扣多出的部分退回；实际金额高于预扣时再补扣差额。短视频通常是退回，15 秒 720p 这类长视频可能补扣。
3. 任务失败、取消或超时，预扣全额退回。

---

## 7. 常见问题

**`seconds` 写数字为什么报错？**
这个字段是字符串，写 `"5"`。也可以改用 `metadata.duration: 5`。

**能不能不传时长？**
可以，模型会在 4 到 15 秒内自己选，费用随实际时长变化。想控制成本就显式写时长。

**`ratio` 和首帧图片比例不一致会怎样？**
不写 `ratio` 时模型会跟随首帧图片；写了具体比例则以你写的为准，画面可能被裁切。

**视频链接失效了怎么办？**
结果地址只保留一段时间，失效后 `metadata.url` 和 `GET /v1/videos/{id}/content` 都拿不到文件，也无法重新生成同一段视频。请在任务完成后立刻下载并转存。

**为什么日志里一条任务有两笔记录？**
第一笔是提交时的预扣，第二笔是按实际 token 结算后的退回或补扣。看最终金额即可。

**想要 1080p 或 4K？**
`seedance-2.0-mini` 只提供 480p 和 720p。支持更高分辨率的型号上线后会在模型广场出现。

---

## 下一步

- [分组 / 模型 / 价格](/docs/onboarding/groups-models) - 确认令牌分组
- [错误码排查](/docs/onboarding/errors) - 401 / 404 / 429 通用排查
- [API 接口](/docs/onboarding/api) - 查余额、查日志