# ZPIKA Seedance AI 接入规范

本文档供 AI 编程助手、自动化代理和第三方画布直接读取。请严格使用本文定义的 ZPIKA 接口格式，不要根据其它 Seedance 服务商的字段自行猜测。

## 1. 固定接入信息

- Base URL：`https://vip.zpika.com`
- 创建任务：`POST /v1/videos`
- 查询任务：`GET /v1/videos/{task_id}`
- 认证：`Authorization: Bearer YOUR_API_KEY`
- 密钥创建：<https://vip.zpika.com/keys>，创建时选择支持目标 Seedance 模型的对应分组；使用本站统一报价时通常选择 `seedance` 分组。
- 任务日志：<https://vip.zpika.com/usage-logs/task>
- Content-Type：`application/json`
- 视频生成是异步任务。创建成功后必须保存任务 ID，再轮询原任务。
- 创建请求超时、返回临时 5xx 或任务状态暂时未知时，不要立即重复创建。先在任务记录中核对，再继续查询原任务，避免重复扣费。

图片接口也推荐使用异步任务以避免长连接超时。ZPIKA 无限画布已默认配置直连域名；Seedance 视频本身是异步任务，通常直接使用上述普通域名即可。

## 2. 模型

| 模型 | model | 分辨率 |
| --- | --- | --- |
| Seedance 2.0 Mini | `doubao-seedance-2-0-mini-260615` | `480p`、`720p` |
| Seedance 2.0 Fast | `doubao-seedance-2-0-fast-260128` | `480p`、`720p` |
| Seedance 2.0 满血 | `doubao-seedance-2-0-260128` | `480p`、`720p`、`1080p`、`4K` |
| Seedance 2.5 | `doubao-seedance-2-5-260628` | `480p`、`720p`、`1080p` |

常用比例：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`、`adaptive`。

推荐默认值：Seedance 2.0 Mini、`480p`、5 秒、`16:9`、生成声音。

### 客户价格参考

总体约为官方公开价格的 **8.0-8.5 折**，不同渠道和模型略有差异。

| 模型 | 分辨率 | 约付人民币/秒 |
| --- | --- | --- |
| Seedance 2.0 Mini | 480p / 720p | ¥0.10-0.20 / ¥0.23-0.42 |
| Seedance 2.0 Fast | 480p / 720p | ¥0.20-0.30 / ¥0.46-0.62 |
| Seedance 2.0 满血 | 480p / 720p / 1080p / 4K | ¥0.38-0.39 / ¥0.82-0.86 / ¥2.05-2.14 / ¥5.20-5.30 |
| Seedance 2.5 | 480p / 720p / 1080p | ¥0.56-0.58 / ¥1.23-1.31 / ¥3.10-3.23 |

以上价格仅供参考，可能随时波动，以站点实际定价和任务结算为准。参考视频会按参考时长和数量增加实际支付金额。

## 3. 纯文生视频

```bash
curl --fail-with-body --silent --show-error \
  -X POST 'https://vip.zpika.com/v1/videos' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-0-mini-260615",
    "prompt": "清晨湖面上的游轮缓慢前行，镜头稳定，无文字，无水印。",
    "duration": 5,
    "metadata": {
      "resolution": "480p",
      "ratio": "16:9",
      "generate_audio": true
    }
  }'
```

成功响应会包含任务 `id`、`status` 和 `progress`。保存 `id`，不要用创建接口查询任务。

任务提交后也可在 ZPIKA 任务日志查看进度、制品并下载：<https://vip.zpika.com/usage-logs/task>。

## 4. 参考素材格式

参考素材放在 `metadata.content` 数组中。每个素材必须同时提供：

1. 正确的 `type`；
2. 与 `type` 对应的 URL 对象；
3. 明确的 `role`。

| 用途 | type | role | URL 字段 |
| --- | --- | --- | --- |
| 普通参考图片 | `image_url` | `reference_image` | `image_url.url` |
| 首帧 | `image_url` | `first_frame` | `image_url.url` |
| 尾帧 | `image_url` | `last_frame` | `image_url.url` |
| 参考视频 | `video_url` | `reference_video` | `video_url.url` |
| 参考音频 | `audio_url` | `reference_audio` | `audio_url.url` |

素材 URL 必须是服务端可直接读取、在任务完成前保持有效的 HTTPS 文件地址。不能填写本地磁盘路径、`blob:` URL、需要交互登录的网页或网盘分享页面。

### 强制组合规则

- 参考视频必须同时提供至少一张普通参考图片。
- 音频参考不能单独使用，必须同时提供至少一张图片或一段视频。
- 首帧/尾帧模式不能与普通参考素材混用。
- 首帧/尾帧模式不能与视频编辑模式混用。
- 可以只提供一张首帧；提供尾帧时必须同时提供首帧，不能只提供尾帧。
- 首帧和尾帧必须是图片；同时提供时，两张图片的像素尺寸必须完全一致。
- Seedance 2.5 使用首帧或首尾帧时，`ratio` 填写 `adaptive`，单独首帧可以使用非标准画幅。
- 本站当前链路只开放已实测成功的 Seedance 2.5 首尾帧。2.0 满血、Fast、Mini 的普通参考素材仍可使用，但首帧/尾帧实测在创建阶段返回 400，因此暂不提交这些角色；这不代表对模型原生能力作判断。
- 普通参考图片、参考视频和纯文生视频仍使用用户选择的固定比例，不套用首尾帧比例规则。
- `content` 内每项素材必须指定正确的 `role`，不能省略或用错角色。
- `generate_audio` 必须是 JSON 布尔值 `true` 或 `false`，不能传字符串。
- 不要用多个兼容字段重复传入同一素材。

### ZPIKA 无限画布的角色转换

当前 ZPIKA 无限画布会按节点类型自动转换普通参考角色：

- `@图片N` -> `reference_image`
- `@视频N` -> `reference_video`
- `@音频N` -> `reference_audio`

提示词中出现任意 `@` 标签时，画布只发送明确引用的素材；没有 `@` 时，发送该任务全部已连接素材。使用 Seedance 2.5 时，在 `@` 菜单选择图片后可继续选择“参考图 / 首帧 / 尾帧”，画布会分别发送 `reference_image`、`first_frame`、`last_frame`。首帧和尾帧都是图片角色，可以只选首帧；选择尾帧时必须先选首帧，且首尾帧不能与普通参考图、参考视频或参考音频混用。

画布对 Seedance 2.5 的首帧或首尾帧请求提交 `adaptive`。2.0 满血、Fast、Mini 会在选择和提交前提示改用 2.5 或普通参考图。两张首尾帧同时存在时，画布会在付费提交前比较像素尺寸，尺寸不同或无法读取时要求先使用图片节点的“裁剪”生成符合要求的新图片，不会静默拉伸。

画布会在本地按模型限制素材数量：Seedance 2.0 满血、Fast、Mini 最多 9 张图片、3 段视频、3 段音频，合计 15 项；Seedance 2.5 最多 30 张图片、10 段视频、10 段音频，合计 50 项。首尾帧计入图片数量，超过限制会明确报错，不会静默丢弃后面的素材。本地图片在 30MiB 内保持原始格式、分辨率和画质上传。

## 5. 图片、视频和音频共同参考

```json
{
  "model": "doubao-seedance-2-0-mini-260615",
  "prompt": "保持图片1的主体外观，延续视频1的镜头运动，参考音频1的节奏。",
  "duration": 5,
  "metadata": {
    "resolution": "480p",
    "ratio": "16:9",
    "generate_audio": true,
    "content": [
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://your-cdn.example/reference.jpg" }
      },
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": { "url": "https://your-cdn.example/reference.mp4" }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": { "url": "https://your-cdn.example/reference.mp3" }
      }
    ]
  }
}
```

只使用部分素材时，删除不需要的数组项，并同步修改提示词；保留参考视频时必须同时保留至少一张普通参考图片。提示词应明确说明每个素材的用途。

## 6. 首尾帧示例

首尾帧属于独立模式，不要再加入 `reference_image`、`reference_video`、`reference_audio` 或视频编辑参数。

以下 2.5 示例假设首帧和尾帧的像素尺寸完全一致，并按上游要求使用 `"ratio": "adaptive"`。

```json
{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "镜头从首帧平稳过渡到尾帧，保持主体一致。",
  "duration": 5,
  "metadata": {
    "resolution": "720p",
    "ratio": "adaptive",
    "generate_audio": true,
    "content": [
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": { "url": "https://your-cdn.example/first.jpg" }
      },
      {
        "type": "image_url",
        "role": "last_frame",
        "image_url": { "url": "https://your-cdn.example/last.jpg" }
      }
    ]
  }
}
```

只使用首帧时，删除 `last_frame` 数组项即可。不能只保留 `last_frame`。同时提供两张图片时，不要为了通过校验而拉伸不同尺寸的图片；应先裁剪出尺寸一致的新图片。

## 7. 查询任务

建议每 5 到 10 秒查询一次原任务：

```bash
curl --fail-with-body --silent --show-error \
  'https://vip.zpika.com/v1/videos/TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

| status | 处理方式 |
| --- | --- |
| `queued` | 继续等待并轮询 |
| `in_progress` | 显示 `progress`，继续轮询 |
| `completed` | 优先读取顶层 `video_url`；兼容读取 `content.video_url`，也可请求 `/v1/videos/{task_id}/content` 下载 |
| `failed` | 显示 `error.message`，保留任务 ID 供排查 |
| `cancelled` | 停止轮询，保留任务 ID 供排查 |

轮询中的临时 502、网络中断或暂时取不到媒体，不等于创建失败。继续查询同一个任务，不要重新调用 `POST /v1/videos`。

当前二开网关会把成功视频登记为任务制品。`video_url` 通常是 ZPIKA 制品地址，可能经过 `media.zpika.com/v1/media?...` 重定向，也可能没有 `.mp4` 后缀；客户端必须跟随重定向并根据 HTTP `Content-Type` 判断文件类型。不要替换 URL、删除查询参数或自行拼接文件名。也可使用 `GET /v1/videos/{task_id}/content`（支持 `HEAD`）读取视频内容；下载时可在该地址后加入 `download=1`。R2 制品默认保留 24 小时，请在完成后尽快下载或转存。

## 8. 客户端实现要求

- API Key 不得写入公开前端代码、日志、URL 或仓库。
- 创建成功后立即持久化任务 ID 和创建参数。
- 页面刷新后应根据任务 ID 恢复轮询，而不是重新创建。
- 任务尚未完成或状态未知时提供“继续查询”，只查询原任务；确认完成后制品取回超过 5 分钟再提供“重新下载”。两个按钮都不得再次创建任务。
- 对参考素材先检查 URL 是否可由公网直接读取。
- 请求前校验模型支持的分辨率和时长，不要向 Mini/Fast 提交未支持的 1080p。
- 明确区分参数错误、内容审核拒绝和网络临时错误；只有参数或素材修改后才重新创建任务。

## 9. 内容安全

避免未授权真人、隐私素材、未成年人敏感情境、色情、暴力、违法内容、品牌商标和受保护影视/动漫 IP。内容审核拒绝通常需要修改提示词或更换素材，重复提交相同内容通常无效。

详细建议见同目录的 `omni-video-content-review-guide.html`。
