# 跳跳虎视频生成 API

版本：3.1（2026-08-13）  
基础地址：`https://api.yanzi.fun`

本文档仅描述公开调用接口。Seedance 2 使用统一模型名 `seedance-2`：没有图片时生成文字视频，传入图片时生成图片参考视频。Wan 3.0 的模型名及调用方式保持独立。

---

## 1. 鉴权

所有请求使用完整 API Key：

```http
Authorization: Bearer YOUR_API_KEY
```

账号池的 curl 自动解析接口支持机器直接调用，不需要管理员页面会话。请求使用服务器配置的专用 `GW_INGEST_TOKEN`，与下游用户 API Key 分开：

```http
POST /admin/accounts/import-curl
Authorization: Bearer GW_INGEST_TOKEN
Content-Type: application/json
```

```json
{
  "curl": "curl ... /user/info ... -b \"... token=JWT ...\"",
  "storage_state": {
    "cookies": [],
    "origins": [],
    "sessionStorage": {}
  },
  "notes": "可选备注"
}
```

该接口仍要求 curl 中包含 QwenWork 登录态 `token`；缺少该字段时请求会被拒绝，不会创建不可用账号。

JSON 请求同时携带：

```http
Content-Type: application/json
```

---

## 2. 查询视频模型

```http
GET /api/models?modality=video
Authorization: Bearer YOUR_API_KEY
```

当前公开模型：

| 模型 | 用途 | 时长 | 比例 | 清晰度 |
|---|---|---|---|---|
| `seedance-2` | 无图片自动文生；有图片自动图片参考生成 | 1–15 秒 | `9:16`、`16:9` | `720p`、`1080p` |
| `wonderclip:wan3.0-video:t2v` | Wan 3.0 文生视频 | 2–30 秒 | `16:9`、`9:16`、`4:3`、`3:4`、`1:1` | `720p`、`1080p` |
| `wonderclip:wan3.0-video:i2v` | Wan 3.0 图生视频 | 2–30 秒 | 同上 | `720p`、`1080p` |
| `wonderclip:wan3.0-video:r2v` | Wan 3.0 图片、视频、音频参考生成 | 2–30 秒¹ | 同上 | `720p`、`1080p` |
| `seedance933:t2v` | 933 不卡脸文生视频 | 1–15 秒 | `9:16`、`16:9`、`1:1`、`4:3`、`3:4`、`21:9` | `720p`、`1080p` |
| `seedance933:i2v` | 933 不卡脸图生视频 | 1–15 秒 | 同上 | `720p`、`1080p` |
| `genspark:seedance-2.0:t2v` | 第二渠道 Seedance 2.0 文生视频 | 4–15 秒 | `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` | `720p`、`1080p` |
| `genspark:seedance-2.0:i2v` | 第二渠道 Seedance 2.0 图片参考生成 | 4–15 秒 | 同上 | `720p`、`1080p` |

¹ 参考素材包含视频时最长 15 秒。

模型列表返回当前启用状态、支持参数及系统公开标价。实际用户价格以报价接口为准。

### 模型与上游路由

公开模型名不包含上游命名空间。网关按模型固定绑定上游，不会因为渠道字段残留、账号额度不足或请求失败而把任务改投到其他模型：

| 公开模型 | 固定上游 |
|---|---|
| `seedance-2` | Seedance/vidIQ |
| `wonderclip:wan3.0-video:*` | WonderClip |
| `seedance933:*` | 933 不卡脸 |
| `genspark:seedance-2.0:*` | 第二渠道 |

提交 `genspark:seedance-2.0:t2v` 或 `genspark:seedance-2.0:i2v` 时，即使请求中的 `channel` 是旧值，也会按模型绑定到第二渠道。若该模型对应的上游账号或额度不可用，任务会在该上游失败并退款，不会转成 Wan 3.0 或其他模型。

---

## 3. 查询预计扣费

```http
POST /api/system-control/quote
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

请求：

```json
{
  "model": "seedance-2",
  "task_type": "text_to_video",
  "task_count": 1,
  "config_json": {
    "model": "seedance-2",
    "seconds": 5,
    "resolution": "720p"
  }
}
```

图片参考生成时将 `task_type` 设置为 `image_to_video`。

响应：

```json
{
  "available": true,
  "task_count": 1,
  "model": "seedance-2",
  "duration": 5,
  "pricing_unit": "credits_per_second",
  "credits_per_second": "0.12",
  "unit_price": "0.60",
  "total_price": "0.60",
  "balance": "179.65"
}
```

报价和实际扣费使用同一套用户价格规则。任务失败时自动退回本次预扣积分。

---

## 4. 服务器本地上传与 Media ID

图片建议先通过网关返回的上传地址写入服务器本地媒体卷。网关数据库只保存 Media ID，不保存图片 Base64；当前部署不依赖 Cloudflare R2。

### 4.1 获取上传地址

```http
POST /api/upload/presign-object
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json
{
  "filename": "Image1.jpg",
  "content_type": "image/jpeg",
  "size_bytes": 1234567
}
```

响应包含 `media_id`、`upload_url`、`object_key` 和上传请求头。浏览器使用返回的 `upload_url` 执行 PUT，Body 为原始文件二进制；生产配置下该地址落到本机 `/data/media/uploads`。

### 4.2 确认上传

```http
POST /api/upload/confirm-object
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json
{
  "media_id": "MEDIA_ID",
  "object_key": "uploads/USER_ID/DATE/MEDIA_ID.jpg"
}
```

确认成功后，在视频生成请求中传入：

```json
"media_ids": ["MEDIA_ID_1", "MEDIA_ID_2"]
```

---

## 5. 统一提交视频任务

```http
POST /v1/videos/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

通用字段：

| 字段 | 类型 | 必填 | 说明 |
|---|---:|---:|---|
| `model` | string | 是 | 模型名称 |
| `channel` | string | 否 | Seedance 使用 `seedance`；Wan 3.0 使用 `wonderclip`；第二渠道使用 `second_channel`，也可由模型自动识别 |
| `prompt` | string | 是 | 视频提示词 |
| `duration` | integer | 否 | 生成秒数 |
| `ratio` | string | 否 | 画面比例 |
| `resolution` | string | 否 | `720p` 或 `1080p`，默认 `720p` |
| `audio` | boolean | 否 | 是否生成声音，默认 `true` |
| `batch_count` | integer | 否 | 批量任务数量，1–5，默认 1 |
| `images` | array | 否 | 图片数组，支持 `data_b64` 或公网 `url`；可用于图生视频、首尾帧及图片参考 |
| `references` | array | 否 | Base64 参考素材数组，元素类型可为 `image`、`video`、`audio` |
| `image_mode` | string | 否 | 图片模式：`single`、`first_last` 或 `r2v` |
| `reference_mode` | string | 否 | 参考模式；混合图片、视频、音频时可填写 `reference_generation` |

单任务响应：

```json
{
  "task_id": "TASK_ID",
  "status": "queued"
}
```

批量响应：

```json
{
  "task_ids": ["TASK_ID_1", "TASK_ID_2"],
  "count": 2,
  "status": "queued"
}
```

---

## 6. Seedance 2

Seedance 2 固定使用：

```json
"model": "seedance-2"
```

接口根据媒体字段自动选择生成方式：

| 请求内容 | 生成方式 |
|---|---|
| 没有 `images`、首尾帧或 Ingredients | 文生视频 |
| 传入任意图片字段 | 图片参考视频 |

### 5.1 文生视频

```json
{
  "channel": "seedance",
  "model": "seedance-2",
  "prompt": "夏日下午的家庭庭院，草坪在微风中轻轻摇曳，镜头缓慢推进",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "720p",
  "audio": true
}
```

### 5.2 单首帧

```json
{
  "channel": "seedance",
  "model": "seedance-2",
  "image_mode": "single",
  "prompt": "让图片中的人物自然眨眼，背景随微风轻轻摆动",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "720p",
  "media_ids": ["MEDIA_ID_FIRST_FRAME"]
}
```

### 5.3 首尾帧

```json
{
  "channel": "seedance",
  "model": "seedance-2",
  "image_mode": "first_last",
  "prompt": "从第一张画面自然过渡到第二张画面",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p",
  "media_ids": ["MEDIA_ID_START", "MEDIA_ID_END"]
}
```

### 5.4 Ingredients 多图参考

支持 1–9 张图片：

```json
{
  "channel": "seedance",
  "model": "seedance-2",
  "image_mode": "r2v",
  "prompt": "保持三张参考图中的角色外观、服装和场景一致，生成连贯电影镜头",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "720p",
  "media_ids": ["MEDIA_ID_1", "MEDIA_ID_2", "MEDIA_ID_3"]
}
```

`media_ids`/`images` 的数组顺序就是图片编号，可在提示词中使用 `@ImageN`（同时兼容 `@图N`）引用：

```json
{
  "channel": "seedance",
  "model": "seedance-2",
  "image_mode": "r2v",
  "prompt": "保持 @Image1 的女主外观和服装一致，让 @Image1 与 @Image2 出现在 @Image3 的教室场景中",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "720p",
  "media_ids": ["MEDIA_ID_女主", "MEDIA_ID_男主", "MEDIA_ID_场景"]
}
```

对应关系固定为：

```text
@Image1 / @图1 → media_ids[0] 或 images[0]
@Image2 / @图2 → media_ids[1] 或 images[1]
@Image3 / @图3 → media_ids[2] 或 images[2]
```

网关会按请求数组顺序重建素材，不依赖数据库查询返回顺序；若提示词引用的 `@ImageN` 超出实际图片数量，请求会返回参数错误，避免静默错绑。

图片数据规则：

- 推荐使用上传接口获得的 `media_ids`；当前生产环境媒体保存在服务器本地卷。
- 支持公网图片地址：`images: [{"url": "https://example.com/image.jpg", "name": "image.jpg"}]`。网关会校验、压缩并转存到服务器本地媒体目录，任务仅保存 Media ID。
- 兼容接口仍接受旧 `images[].data_b64`。
- `images[].url` 仅接受公网 HTTP/HTTPS 地址，单张原图最大 20MB；URL 与 Base64 不混合传入。
- 不要把 `media_ids` 与 `images` 混合用于同一任务；选择一种传图方式可以让编号最清晰。
- `images[].name` 仅用于记录和排查，不参与上游绑定；真正绑定依据是数组下标。
- 客户端应保持数组稳定，不要使用无序集合、对象键遍历或异步完成顺序来拼装图片数组。
- 单首帧必须为 1 张图片。
- 首尾帧必须为 2 张图片。
- 多图参考支持 1–9 张图片。
- 未填写 `image_mode` 时：1 张图片按单首帧处理，多张图片按 Ingredients 处理。

---

## 7. Wan 3.0

### 6.1 文生视频

```json
{
  "channel": "wonderclip",
  "model": "wonderclip:wan3.0-video:t2v",
  "prompt": "真实庭院里的花朵随风摇曳，镜头稳定推进",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "720p",
  "audio": true
}
```

### 6.2 图生视频

```json
{
  "channel": "wonderclip",
  "model": "wonderclip:wan3.0-video:i2v",
  "prompt": "让图片中的花朵和叶片随微风自然摆动",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "720p",
  "images": [
    {"name": "frame.jpg", "data_b64": "BASE64_IMAGE"}
  ]
}
```

### Wan 3.0 参考生视频（图片 / 视频 / 音频可混合）示例

`references` 可混合图片、视频和音频。单次最多 10 张图片、5 个视频、5 个音频，合计最多 20 个素材。
图片、视频、音频不需要拆成不同接口或不同请求。

```json
{
  "channel": "wonderclip",
  "model": "wonderclip:wan3.0-video:r2v",
  "prompt": "参考素材的主体、镜头运动和声音节奏生成视频",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p",
  "audio": true,
  "references": [
    {
      "name": "reference.jpg",
      "media_type": "image",
      "mime": "image/jpeg",
      "data_b64": "BASE64_IMAGE"
    },
    {
      "name": "reference.mp4",
      "media_type": "video",
      "mime": "video/mp4",
      "data_b64": "BASE64_VIDEO"
    },
    {
      "name": "reference.mp3",
      "media_type": "audio",
      "mime": "audio/mpeg",
      "data_b64": "BASE64_AUDIO"
    }
  ]
}
```

---

## 8. 933 不卡脸

文生视频使用 `seedance933:t2v`，图生视频使用 `seedance933:i2v`。支持 1–15 秒和 `720p`、`1080p`。

图生视频支持图片、视频、音频混合参考：最多 10 张图片、5 段视频、5 段音频。提示词可用 `@Image1`、`@Video1`、`@Audio1` 指定对应素材；三种素材分别独立编号。

### 8.1 图生视频：直接传入图片

将图片转成 Base64 后放入 `images[].data_b64`：

```json
{
  "channel": "seedance933",
  "model": "seedance933:i2v",
  "prompt": "@Image1 中的人物自然转身，镜头平稳跟随",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "720p",
  "images": [
    {
      "name": "reference.jpg",
      "data_b64": "BASE64_IMAGE"
    }
  ]
}
```

也可以传公网图片地址：

```json
"images": [
  {
    "name": "reference.jpg",
    "url": "https://example.com/reference.jpg"
  }
]
```

网页端选择“933 不卡脸 图生视频”后，在“参考素材”区域点击或拖拽上传图片。图片左上角的 `@Image1` 按钮可将素材编号插入提示词。

### 8.2 图片、视频、音频混合参考

```json
{
  "channel": "seedance933",
  "model": "seedance933:i2v",
  "prompt": "以 @Image1 为主体，参考 @Video1 的动作，并使用 @Audio1 的节奏",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p",
  "references": [
    {"name": "subject.jpg", "media_type": "image", "mime": "image/jpeg", "data_b64": "BASE64_IMAGE"},
    {"name": "motion.mp4", "media_type": "video", "mime": "video/mp4", "data_b64": "BASE64_VIDEO"},
    {"name": "rhythm.mp3", "media_type": "audio", "mime": "audio/mpeg", "data_b64": "BASE64_AUDIO"}
  ]
}
```

```json
{
  "channel": "seedance933",
  "model": "seedance933:t2v",
  "prompt": "电影感街景，人物自然行走，镜头平稳跟随",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "720p"
}
```

---

## 9. 第二渠道 Seedance 2.0

渠道名仅用于 API 的 `channel`/模型显示，不作为服务器名称。第二渠道使用独立的上游凭据和素材上传链路。

支持模型：

```text
genspark:seedance-2.0:t2v
genspark:seedance-2.0:i2v
```

Seedance 2.0 支持 4–15 秒，支持 `21:9`/`16:9`/`4:3`/`1:1`/`3:4`/`9:16`，分辨率为 `720p`、`1080p`。参考素材最多 9 张图片、3 个视频、3 个音频，合计最多 12 个素材。

文生视频：

```json
{
  "channel": "second_channel",
  "model": "genspark:seedance-2.0:t2v",
  "prompt": "电影感街景，人物自然行走，镜头平稳跟随",
  "duration": 10,
  "ratio": "9:16",
  "resolution": "720p",
  "audio": true
}
```

多模态参考：

```json
{
  "channel": "second_channel",
  "model": "genspark:seedance-2.0:i2v",
  "prompt": "以 @Image1 为主体，参考 @Video1 的动作，并使用 @Audio1 的节奏",
  "duration": 15,
  "ratio": "16:9",
  "resolution": "720p",
  "references": [
    {"name": "subject.jpg", "media_type": "image", "mime": "image/jpeg", "data_b64": "BASE64_IMAGE"},
    {"name": "motion.mp4", "media_type": "video", "mime": "video/mp4", "data_b64": "BASE64_VIDEO"},
    {"name": "rhythm.mp3", "media_type": "audio", "mime": "audio/mpeg", "data_b64": "BASE64_AUDIO"}
  ]
}
```

Seedance 2.0 图片参考生成：

```json
{
  "channel": "second_channel",
  "model": "seedance-2.0:i2v",
  "prompt": "保持 @Image1 和 @Image2 中的角色与场景特征，参考 @Video1 的动作，并跟随 @Audio1 的节奏",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "720p",
  "image_mode": "r2v",
  "reference_mode": "reference_generation",
  "images": [
    {"name": "start.jpg", "mime": "image/jpeg", "data_b64": "BASE64_IMAGE_1"},
    {"name": "end.jpg", "mime": "image/jpeg", "data_b64": "BASE64_IMAGE_2"}
  ],
  "references": [
    {"name": "motion.mp4", "media_type": "video", "mime": "video/mp4", "data_b64": "BASE64_VIDEO"},
    {"name": "rhythm.mp3", "media_type": "audio", "mime": "audio/mpeg", "data_b64": "BASE64_AUDIO"}
  ]
}
```

第二渠道的 `seedance-2.0:i2v` 仅保留 `r2v` 参考生成；`single` 和 `first_last` 已取消。

管理员可导入第二渠道凭据；网关会自动把它加入第二渠道账号池。

参考素材上传可通过 711proxy 转发。配置第二渠道代理后，获取上传地址和向对象存储上传文件都会使用同一个代理出口；代理传输失败时会自动更换出口重试。视频生成流本身保持普通连接。

---

## 10. 查询任务

```http
GET /v1/tasks/{TASK_ID}
Authorization: Bearer YOUR_API_KEY
```

成功响应：

```json
{
  "task_id": "TASK_ID",
  "type": "video",
  "channel": "seedance",
  "status": "success",
  "model": "seedance-2",
  "ratio": "9:16",
  "duration": 5,
  "progress": "生成完成",
  "result_urls": ["/v1/tasks/TASK_ID/video"],
  "video_url": "/v1/tasks/TASK_ID/video",
  "download_url": "/v1/tasks/TASK_ID/video",
  "error": null,
  "points_cost": 0.6,
  "refunded": false,
  "balance_after": 179.05
}
```

任务状态：

| 状态 | 说明 |
|---|---|
| `queued` | 已进入队列 |
| `running` | 正在生成 |
| `success` | 生成完成 |
| `failed` | 生成失败；预扣积分自动退回 |

建议每 10–30 秒查询一次，直至进入 `success` 或 `failed`。

---

## 8. 下载视频

```http
GET /v1/tasks/{TASK_ID}/video
Authorization: Bearer YOUR_API_KEY
```

cURL：

```bash
curl -L "https://api.yanzi.fun/v1/tasks/TASK_ID/video" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o result.mp4
```

---

## 9. 常见 HTTP 状态

| 状态码 | 说明 |
|---:|---|
| `200` | 请求成功 |
| `400` | 参数、图片数量或媒体格式错误 |
| `401` | API Key 无效 |
| `402` | 用户余额不足 |
| `404` | 任务不存在 |
| `429` | 用户任务或全局队列达到上限 |
| `500` | 任务提交异常 |
| `503` | 模型或渠道已停用 |

生成任务失败时，查询接口中的 `status` 为 `failed`，并返回稳定的公开错误信息；本次预扣积分会自动退回。

---

## 10. 完整 cURL 示例

### Seedance 2 文生视频

```bash
curl -X POST "https://api.yanzi.fun/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel":"seedance",
    "model":"seedance-2",
    "prompt":"夏日下午的庭院，草坪随微风轻轻摆动",
    "duration":5,
    "ratio":"9:16",
    "resolution":"720p"
  }'
```

### 查询任务

```bash
curl "https://api.yanzi.fun/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```