# 小火龙API · 调用文档

> **Base URL**：`https://soulhub.top/v1`
> **鉴权方式**：HTTP 请求头 `Authorization: Bearer <你的 API Key>`
> **获取 API Key**：登录 `https://soulhub.top` → 控制台 → 令牌
> **OpenAI 兼容**：本接口完全兼容 OpenAI 协议，可直接用 OpenAI SDK / 各种客户端（Cherry Studio、ChatBox、ZCode 等）

---

## 模型总览

| 类别 | 模型 | 用途 | 计费 |
|------|------|------|------|
| **对话** | `deepseek-v4-flash` | DeepSeek V4 快速版（编程场景主力）· 输入 ¥1.5/百万tokens（空闲档，高峰×2）| 按 token（CNY） |
| **对话** | `deepseek-v4-pro` | DeepSeek V4 Pro（深度思考）· 输入 ¥4.5/百万tokens（空闲档，高峰×2）| 按 token（CNY） |
| **对话** | `deepseek-v4-flash-vision-exp` | DeepSeek V4 **视觉版**（图片理解，2026-08-28 新上）· 与 flash 同价 | 按 token（CNY） |
| **生图** | `image2` | OpenAI gpt-image-2 文生图/图生图（**任意分辨率 + 参考图，URL 国内可达**，1K-4K 全支持）| ¥0.15/张 |
| **生图** | `gpt-image-2-4K` | **统一路由** 4K · xxcapi→zexapi→FBIapi 故障自动转移 · **支持参考图（图生图）** | ¥0.10/张 |
| **生图** | `gpt-image-2-2K` | **统一路由** 2K · xxcapi→zexapi 故障自动转移 · **支持参考图（图生图）** | ¥0.06/张 |
| **生图** | `gpt-image-2-1K` | **统一路由** 1K · xxcapi→zexapi 故障自动转移 · **支持参考图（图生图）** | ¥0.04/张 |
| **视频** | `seedance-2.0/2.5-*-渠道1` 系列（30 个） | 即梦 Seedance（aistarlab）· 933 满血参考 · 4K/卡人脸/**限时线 4K ¥1.20/秒** | 按秒/按条，¥0.22~3.20/秒 |
| **视频** | `minimax-h3-*-渠道1`（4 个） | 海螺 MiniMax H3 · 480p~2K · 限时回馈 **¥0.08/秒起** | 按秒 |
| **视频** | `*-渠道2` 系列（45 个） | 即梦 Seedance（aicopy）· 2.5 低价线 + 30秒长视频 + 1080p 2.5 + 按条低价 | 按秒/按条，¥0.27~9.00 |
| **视频** | 完整清单见 3.2 / 3.3 节 | 渠道1 求稳，渠道2 便宜（2.5 便宜 20%）| 2.0: 4-15秒；2.5: 最长30秒 |

---

## 1. 对话（DeepSeek）

完全兼容 OpenAI Chat Completions 协议。

### 价目（人民币 / 百万 tokens，2026-08-28 对齐官方）

| 模型 | 输入（空闲/高峰）| 输出（空闲/高峰）| 缓存命中 |
|------|----------------|----------------|---------|
| `deepseek-v4-flash` | ¥1.5 / ¥3.0 | ¥4.5 / ¥9.0 | ¥0.05 / ¥0.10 |
| `deepseek-v4-pro` | ¥4.5 / ¥9.0 | ¥13.5 / ¥27.0 | ¥0.15 / ¥0.30 |
| `deepseek-v4-flash-vision-exp` | ¥1.5 / ¥3.0 | ¥4.5 / ¥9.0 | 同 flash |

高峰时段：工作日 09:00-12:00、14:00-18:00（北京时间），其余空闲。vision 版图片按尺寸折算 tokens 计费。

### 请求

```http
POST https://soulhub.top/v1/chat/completions
Authorization: Bearer <你的 API Key>
Content-Type: application/json

{
  "model": "deepseek-v4-flash",
  "messages": [
    {"role": "system", "content": "你是一个创意编剧"},
    {"role": "user", "content": "写一个5秒的镜头描述"}
  ],
  "stream": true,
  "max_tokens": 1000,
  "temperature": 0.8
}
```

### curl 示例

```bash
curl https://soulhub.top/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

### Python 示例（用 OpenAI SDK）

```python
from openai import OpenAI

client = OpenAI(
    api_key="你的 API Key",
    base_url="https://soulhub.top/v1"
)

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
```

### 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| model | string | 是 | 模型名（见上方总览） |
| messages | array | 是 | 对话历史，`[{role, content}]` |
| stream | boolean | 否 | true 流式返回（默认 false） |
| max_tokens | int | 否 | 最大生成 token 数 |
| temperature | number | 否 | 0-2，默认 1 |

---

## 2. 文生图

支持多套生图引擎，URL 都在国内可达：

| 模型 | 引擎 | URL 域名 | 国内可达 | 计费 |
|------|------|---------|---------|------|
| `gpt-image-2-4K / -2K / -1K` | **统一路由**（xxcapi→zexapi→FBIapi）| `*.code2alita.com` | ✅ 直接访问 | 4K ¥0.10 / 2K ¥0.06 / 1K ¥0.04 |
| `image2` | OpenAI gpt-image-2 | `oss-us.file-download.life`（Cloudflare CDN）| ✅ 直接访问 | ¥0.15/张 |


#### gpt-image-2-* 统一路由：同步生图 + 参考图（2026-08-15 更新）

`gpt-image-2-4K / -2K / -1K` 同步直出（`POST /v1/images/generations`）：

1. **纯文生图**：只传 `prompt` + `size`，约 30–110s 直出 `data[0].url`
2. **参考图（图生图）**：JSON 里带 `image`（string / string[]）或 `images: [{"image_url": ...}]`
   ——网关检测到参考图后**自动改走图像编辑通道**，模型会严格跟随参考图的人物外观/画风，
   无需换端点、无需改模型名。提示词建议明确写「保持参考图人物外观不变」。耗时约 60–150s
3. 也可直接 `POST /v1/images/edits`（multipart 上传本地文件），效果相同
4. 客户端 HTTP 超时建议 ≥240 秒（4K 带参考图最长约 150s）

```json
{
  "model": "gpt-image-2-4K",
  "prompt": "严格保持参考图中人物的发型、发色、服装和配饰完全不变，将他放到黄昏雪山前，全身照",
  "image": "https://你的图床/ref.png",
  "size": "3840x2160"
}
```

#### image2 协议：同步生图（不要按视频去轮询 task）

image2 **不是**异步任务模型：

1. `POST /v1/images/generations` **一直等到出图**
2. 成功时响应里直接有 `data[0].url` 或 `data[0].b64_json`
3. **优先用 `data[]` 取图**；不要因为响应里偶尔带 `id`/`task_id` 就改去 `GET /v1/images/{id}` 轮询（易 404，前端会假超时/假拥堵）
4. 视频才用 `POST/GET /v1/videos/...` 任务流；**不要和 image2 混用**

完整对接说明（给客户可转发）：  
`https://soulhub.top/docs/image2-guide.md`  
（仓库：`docs/image2-客户调用指南.md`）

#### image2 性能 & 并发说明（重要，调用前必读）

| 项 | 数值 |
|----|------|
| **并发上限** | **20 张同时生成**（无需排队） |
| **稳定吞吐** | **30-40 张/分钟** |
| **单张耗时（实测）** | 1K ≈ 42s / 2K ≈ 50s / 4K ≈ 85-107s |
| **失败自动重试** | ✅ 上游卡顿时自动重试 2 次（指数退避 0.5s/2s/5s） |
| **CF 524 错误** | ❌ 永不再出现（proxy 内部 120s 超时 + 重试吸收） |

**客户端调用建议（关键）**：
- ⚠️ **客户端 HTTP 超时必须设 ≥180 秒**（4K 偶尔会到 120s，设太短会假失败）
- ⚠️ **成功判定：先看 `data[0].url` / `b64_json`**，不要优先轮询 task
- 客户端**不需要自己做重试**（proxy 已自动重试 2 次）
- 如果收到 502 `upstream_unavailable`（极少，<1%），等 30 秒重试一次大概率成功
- 不要同时发超过 20 张（超过会进队列，超过 80 张直接拒绝 503）；排队仍在**同一次 POST** 里完成，不会改成异步 task 协议

### image2 完整能力（2026-08-04 实测更新）

`image2` 单个模型支持：

| 能力 | 用法 | 实测 |
|------|------|------|
| 文生图 | 只传 `prompt` | ✅ ~40–60s |
| **单图参考** | `"image": "https://..."` | ✅ 身份锁定强 |
| **多图参考** | `"image": ["url1","url2",...]` | ✅ **已实测 2/3/7/9 张** |
| 任意分辨率 | `size` | ✅ 1K/2K/4K |
| base64 输出 | `response_format: "b64_json"` | ✅ |

**支持的 size**：`1024x1024` / `1024x1536` / `1536x1024` / `2048x2048` / `3840x2160` 等。

### 请求

#### 文生图

```http
POST https://soulhub.top/v1/images/generations
Authorization: Bearer <你的 API Key>
Content-Type: application/json

{
  "model": "image2",
  "prompt": "一只可爱的橘猫坐在窗台上，阳光从左侧打来",
  "n": 1,
  "size": "1024x1024"
}
```

#### 单图参考

```http
POST https://soulhub.top/v1/images/generations
Authorization: Bearer <你的 API Key>
Content-Type: application/json

{
  "model": "image2",
  "prompt": "保持参考图角色外观，生成多视角身份板，白底",
  "image": "https://example.com/source.jpg",
  "size": "1536x1024",
  "n": 1
}
```

#### 多图参考（2~9 张，推荐写法）⭐

```http
POST https://soulhub.top/v1/images/generations
Authorization: Bearer <你的 API Key>
Content-Type: application/json

{
  "model": "image2",
  "prompt": "使用全部参考图做成一张清晰拼贴，每张参考各占一格，保持可识别，不要编造额外主体",
  "image": [
    "https://example.com/1.jpg",
    "https://example.com/2.jpg",
    "https://example.com/3.jpg"
  ],
  "size": "1024x1024",
  "n": 1
}
```

> **参考图规则（务必看）**
>
> 1. **只认 `image` 字段**（字符串=单图；**字符串数组=多图**）
> 2. **不要用 `images`**（复数）——实测几乎不参考
> 3. 参考图必须是**公网可 GET 的 URL**（或单图 base64）。中转没有单独 upload 接口：先上传到你的 OSS/图床，再把 URL 放进 `image`
> 4. 单图路径：中转会下载后 multipart 直传上游；多图数组路径：JSON 透传上游（已实测到 9 张）
> 5. 单张建议 < 20MB；URL 404/防盗链会导致不参考或 `400 ref_download_failed`
> 6. **`n>1` 不要依赖**（实测常只返回 1 张）；要多张结果请循环请求
> 7. 用户反馈“只能一张”：通常是业务只传了字符串，或误用了 `images` 字段

#### 身份板（4K + 参考图）

```http
POST https://soulhub.top/v1/images/generations
Authorization: Bearer <你的 API Key>
Content-Type: application/json

{
  "model": "image2",
  "prompt": "保持参考图角色外观，生成高清身份板",
  "size": "3840x2160",
  "image": "https://your-cdn.com/reference.png",
  "n": 1
}
```

**实测**：4K + 参考图约 **70-107 秒**。客户端超时 ≥180s。

#### 获取 base64 数据（不走 CDN）

```json
{
  "model": "image2",
  "prompt": "...",
  "response_format": "b64_json"
}
```

返回的 `data[0].b64_json` 是图片的 base64 编码，直接保存为文件即可。

### 响应

```json
{
  "created": 1784523796,
  "data": [
    {
      "url": "https://oss-us.file-download.life/2026/07/20/xxx.png"
    }
  ]
}
```

> **关于图片 URL（重要 - 国内用户必读）**：
>
> | 模型 | 返回 URL 域名 | 国内下载 | 说明 |
> |------|-------------|---------|------|
> | **`image2`** | `oss-us.file-download.life` | ✅ **直接打开**（Cloudflare CDN，~70ms）| 浏览器/curl/Python 都能直接拉，零障碍 |
>
> **结论**：**两个生图模型的 URL 国内都能直接下载**，无需自备代理。
>
> URL 是临时的（通常 24 小时内有效），请及时下载保存。

### curl 示例

**image2（推荐，国内直接能下载）**：

```bash
curl https://soulhub.top/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image2",
    "prompt": "a red circle on white background",
    "size": "1024x1024",
    "n": 1
  }'
```

**image2 图生图（基于参考图修改）**：

```bash
curl https://soulhub.top/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image2",
    "prompt": "background change to blue",
    "image": "https://example.com/source.jpg",
    "n": 1
  }'
```


### 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| model | string | 是 | 所选生图模型 |
| prompt | string | 是 | 图片描述 |
| n | int | 否 | 生成数量，默认 1 |

---

## 3. 视频生成（异步任务）

视频生成是**异步任务**：先 POST 创建任务拿 task_id，再 GET 查询状态，到 `completed` 后拿视频 URL。

### 协议（Seedance 通用）

```
1. POST /v1/videos                 → 拿 task_id（创建任务，按秒预扣/结算）
2. GET  /v1/videos/{task_id}       → 查询状态（轮询 processing/completed）
3. status=completed 时响应里有 url（视频 mp4 地址，已自动转 OSS）
```

### 3.2 即梦 Seedance 视频（渠道1 aistarlab · 34 个模型）

即梦 Seedance 视频生成，两条上游渠道并存：

| | 渠道1（aistarlab）| 渠道2（aicopy）|
|---|---|---|
| 模型名后缀 | `-渠道1` | `-渠道2` |
| 版本 | 2.0 全系 + 2.5 三档 + **限时限量线** | 2.5 十档 + 2.0 三十五档 |
| 独有 | 4K、1080p 按秒、卡人脸按秒、**4K ¥1.20/秒限时价** | 2.5 低价线、30 秒长视频、按条低价 |
| 稳定性 | 已验证稳定 | 低价线为轮换/惊喜性质，测试期 |

> **改名通知（2026-08-18）**：渠道1 的 20 个旧模型名已全部升级为带 `-渠道1` 后缀的新名（如 `seedance-2.0-720p` → `seedance-2.0-720p-渠道1`）。**旧名过渡期继续可用**（不少于 14 天），新接入请直接用新名。

> 中转已实测验证：参考图/视频/音频字段 100% 透传到上游，不会出现"无法参考"。

#### ⭐ 渠道1 完整模型清单（34 个）

模型名规则：`seedance-2.0[-fast]-{分辨率}[-线路后缀]-渠道1`
- 无后缀 = 普通线路（最便宜）| `-pro` = 专线 | `-face` = 卡人脸专线 | `-flat` = 按条特价 | `-flat2` = 按条标准 | **`-限时` = 限时限量回馈线（channel 64，全网低价）**

**🔥 限时限量回馈线（channel 64 · 2026-08-27 上线 · 全部低于普通线）**：

| 模型名 | 版本 | 分辨率 | 单价 |
|--------|------|--------|------|
| `seedance-2.0-fast-480p-限时-渠道1` | Fast | 480p | ¥0.22/秒 |
| `seedance-2.0-fast-720p-限时-渠道1` | Fast | 720p | ¥0.32/秒 |
| `seedance-2.0-480p-限时-渠道1` | 标准 | 480p | ¥0.30/秒 |
| `seedance-2.0-720p-限时-渠道1` | 标准 | 720p | ¥0.40/秒 |
| `seedance-2.0-1080p-限时-渠道1` | 标准 | 1080p | ¥0.70/秒 |
| `seedance-2.0-4k-限时-渠道1` | 标准 | **4K** | **¥1.20/秒**（普通线 4K 的一半）|

**Seedance 2.5（480p/720p 走 63 限时线 · 1080p 走 54 线）**：

| 模型名 | 分辨率 | 单价 |
|--------|--------|------|
| `seedance-2.5-480p-渠道1` | 480p | ¥0.45/秒 |
| `seedance-2.5-720p-渠道1` | 720p | ¥0.68/秒 |
| `seedance-2.5-1080p-渠道1` | 1080p | ¥2.80/秒 |

2.5 支持 4-30 秒长视频、最多 30 图/10 视频/10 音频参考、带音频生成。

**普通线路（channel 47 · 按秒）**：

| 模型名 | 版本 | 分辨率 | 单价 |
|--------|------|--------|------|
| `seedance-2.0-fast-480p-渠道1` | Fast | 480p | ¥0.30/秒 |
| `seedance-2.0-fast-720p-渠道1` | Fast | 720p | ¥0.44/秒 |
| `seedance-2.0-480p-渠道1` | 标准 | 480p | ¥0.36/秒 |
| `seedance-2.0-720p-渠道1` | 标准 | 720p | ¥0.52/秒 |
| `seedance-2.0-1080p-渠道1` | 标准 | 1080p | ¥0.80/秒 |
| `seedance-2.0-4k-渠道1` | 标准 | 4K | ¥2.60/秒 |

**专线（channel 48 · 按秒 · 模型名加 `-pro`）**：

| 模型名 | 版本 | 分辨率 | 单价 |
|--------|------|--------|------|
| `seedance-2.0-fast-480p-pro-渠道1` | Fast | 480p | ¥0.34/秒 |
| `seedance-2.0-fast-720p-pro-渠道1` | Fast | 720p | ¥0.50/秒 |
| `seedance-2.0-480p-pro-渠道1` | 标准 | 480p | ¥0.40/秒 |
| `seedance-2.0-720p-pro-渠道1` | 标准 | 720p | ¥0.58/秒 |
| `seedance-2.0-1080p-pro-渠道1` | 标准 | 1080p | ¥1.20/秒 |
| `seedance-2.0-4k-pro-渠道1` | 标准 | 4K | ¥3.20/秒 |

**卡人脸专线（channel 53 · 按秒 · 模型名加 `-face`）**：
> 卡人脸线针对真人人脸锁定优化。480p/720p/1080p。

| 模型名 | 版本 | 分辨率 | 单价 |
|--------|------|--------|------|
| `seedance-2.0-fast-480p-face-渠道1` | Fast | 480p | ¥0.26/秒 |
| `seedance-2.0-fast-720p-face-渠道1` | Fast | 720p | ¥0.38/秒 |
| `seedance-2.0-480p-face-渠道1` | 标准 | 480p | ¥0.32/秒 |
| `seedance-2.0-720p-face-渠道1` | 标准 | 720p | ¥0.46/秒 |
| `seedance-2.0-1080p-face-渠道1` | 标准 | 1080p | ¥0.72/秒 |

**按条计费（固定 720P · 时长 4-15 秒任选）**：

| 模型名 | 版本 | 线路 | 单价 |
|--------|------|------|------|
| `seedance-2.0-fast-720p-flat-渠道1` | Fast | 限时特价(channel 50) | ¥3.50/条 |
| `seedance-2.0-720p-flat-渠道1` | 标准 | 限时特价(channel 50) | ¥4.50/条 |
| `seedance-2.0-fast-720p-flat2-渠道1` | Fast | 按条标准(channel 49) | ¥6.30/条 |
| `seedance-2.0-720p-flat2-渠道1` | 标准 | 按条标准(channel 49) | ¥7.50/条 |

#### 海螺 MiniMax H3 视频（渠道1 · channel 59 · 2026-08-27 上线）

| 模型名 | 分辨率 | 单价 |
|--------|--------|------|
| `minimax-h3-480p-渠道1` | 480p | **¥0.08/秒** |
| `minimax-h3-768p-渠道1` | 768p | ¥0.12/秒 |
| `minimax-h3-1080p-渠道1` | 1080p | ¥0.16/秒 |
| `minimax-h3-2k-渠道1` | 2K | ¥0.20/秒 |

不卡人脸 · 限时回馈价。调用方式与 Seedance 完全一致（`POST /v1/videos` + prompt/seconds/参考图）。

#### 参考能力（933 满血 · 渠道1 所有模型统一）

**渠道1 全部 22 个模型都支持**：
- **9 张参考图**（`inputImagesMax: 9`）
- **3 个参考视频**（`inputVideosMax: 3`）
- **3 个参考音频**（`inputAudiosMax: 3`）

> 参考视频的积分消耗 = 基础 × **1.5**（`inputVideoMultiplier: 1.5`）。参考图/音频不加价。（渠道2 未设参考加价）

### 3.3 渠道2 Seedance（aicopy · 45 个模型 · 2026-08-18 上线）

**统一调用方式**（与渠道1 相同的端点和字段，网关自动翻译成各线路原生协议）：

```json
{
  "model": "sd-2.5-720p不卡脸(按秒)-渠道2",
  "prompt": "海边日落，镜头缓慢推进",
  "seconds": "10",
  "image": "https://图床/首帧.jpg",
  "metadata": {
    "images": ["https://图床/参考2.jpg"],
    "videos": ["https://图床/运镜.mp4"],
    "audios": ["https://图床/音乐.mp3"],
    "ratio": "16:9"
  }
}
```

- `seconds` 用**字符串**；参考图可放 `image`（首帧）或 `metadata.images`（多参考）；比例用 `metadata.ratio`
- 槽位语义：第 1 张=首帧；恰好 2 张=首帧+尾帧；更多=首帧+参考图
- 端点同样是 `POST /v1/videos` + `GET /v1/videos/{id}` 轮询（约 5 秒一次）

#### Seedance 2.5 · 渠道2（10 档）

| 模型名（加 `-渠道2` 后缀）| 单价 | 特点 |
|------|------|------|
| `sd-2.5-480p不卡脸(按秒)` | ¥0.36/秒 | 不卡脸 · 4-29秒 · 30图/10视频/10音频 · 比渠道1便宜20% |
| `sd-2.5-720p不卡脸(按秒)` | ¥0.54/秒 | 同上 |
| `sd-2.5-480p不卡脸(按秒)-备用` | ¥0.42/秒 | 备用线 |
| `sd-2.5-720p不卡脸(按秒)-备用` | ¥0.60/秒 | 备用线 |
| `sd-2.5-轮换渠道（按秒）` | ¥0.54/秒 | 固定720p · 16:9/9:16 · 动态调价 |
| `sd-2.5-轮换渠道（按次）` | ¥6.30/条 | 固定720p · 4-15秒 |
| `【官方稳定版】2.5-480p` | ¥1.20/秒 | 官方稳定 · 4-30秒 · 6种比例 · 音频生成 |
| `【官方稳定版】2.5-720p` | ¥2.40/秒 | 同上 |
| `【稳定】sd2.5-720p` | ¥1.00/秒 | token折算保守估价（测试期） |
| `【稳定】sd2.5-1080p` | ¥2.30/秒 | **唯一 1080p 2.5**（测试期） |

#### Seedance 2.0 按秒 · 渠道2（12 档）

| 模型名（加 `-渠道2`）| 单价 |
|------|------|
| `sd-2.0-480满血（不卡脸）惊喜渠道` | ¥0.30/秒 |
| `sd-480满血-933（按秒）` | ¥0.27/秒 |
| `sd-720满血（按秒）` | ¥0.36/秒 |
| `sd-720fast（按秒）` | ¥0.36/秒 |
| `sd-2.0-720满血（不卡脸）惊喜渠道` | ¥0.42/秒 |
| `sd-720满血-933（按秒）` | ¥0.45/秒 |
| `sd2.0-720fast-不卡脸（按秒）` | ¥0.57/秒 |
| `sd2.0-720满血-不卡脸（按秒）` | ¥0.69/秒 |
| `sd2.0-1080fast-不卡脸（按秒）` | ¥1.02/秒 |
| `sd2.0-1080满血-不卡脸（按秒）` | ¥1.20/秒 |
| `【官方稳定版】sd2.0-720p-fast` | ¥0.72/秒 |
| `【官方稳定版】sd2.0-720p-满血` | ¥0.84/秒 |

#### Seedance 2.0 按次 · 渠道2（23 档 · 均为固定 15 秒）

| 模型名（加 `-渠道2`）| 单价/条 | 说明 |
|------|--------|------|
| `sd-720满血-900（不售后）` | ¥0.96 | ⚠️全场最低价但**不售后**，仅1-9张参考图 |
| `sd-2.0-480fast（卡脸）惊喜渠道` | ¥2.16 | 卡脸 |
| `sd2.0-480fast-ad渠道16x9` / `9x16` | ¥2.40 | 锁画幅 |
| `sd-2.0-480满血（卡脸）惊喜渠道` | ¥3.00 | 卡脸 |
| `sd2.0-480满血-ad渠道16x9` / `9x16` | ¥3.00 | 锁画幅 |
| `sd-720fast-不卡脸（按次）` | ¥3.00 | |
| `sd-2.0-720fast（卡脸）惊喜渠道` | ¥3.00 | 卡脸 |
| `sd2.0-720fast-ad渠道16x9` / `9x16` | ¥3.00 | 锁画幅 |
| `sd-480满血-933（按次）` | ¥3.00 | 933 |
| `sd-2.0-720满血（卡脸）惊喜渠道` | ¥3.60 | 卡脸 |
| `sd2.0-720满血-ad渠道16x9` / `9x16` | ¥3.60 | 锁画幅 |
| `sd-720满血-较慢（按次）` | ¥3.60 | 出图较慢价格低 |
| `sd-720满血-不卡脸（按次）` | ¥4.20 | |
| `sd-2.0-1080满血（卡脸）惊喜渠道` | ¥6.00 | 卡脸 |
| `sd-720满血-933（按次）` | ¥6.00 | 933 |
| `sd2.0-1080满血-ad渠道16x9` / `9x16` | ¥7.20 | 锁画幅 |
| `sd2.0-720满血（按次）不卡脸` | ¥9.00 | |
| `sd2.0-720fast（按次）不卡脸` | ¥9.00 | |

> **渠道2 各线路限制速查**：ad渠道锁 16:9 或 9:16；轮换/900 固定 720p 仅 16:9/9:16；900 仅多参考图（1-9张，无文生）；933 系与 2.0 不卡脸系支持 9图/3视频/3音频；2.5 不卡脸系 30图/10视频/10音频。
>
> **选线建议**：短视频+按秒 → 渠道1；15秒+按次/低价 → 渠道2；2.5 → 渠道2 便宜 20%（求稳用渠道1）；4K/卡人脸按秒 → 只有渠道1。

#### 时长

- Seedance 2.0：**最短 4 秒，最长 15 秒**，连续可选（任意整数秒）
- Seedance 2.5：最长 **29-30 秒**（渠道1/渠道2 的 2.5 档）
- 用 `duration` 或 `seconds` 字段传（`seconds` 建议用字符串，如 `"seconds": "10"`）

#### 创建任务

```bash
curl -X POST https://soulhub.top/v1/videos \
  -H "Authorization: Bearer <你的key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-720p",
    "prompt": "图片1中的角色正面微笑，镜头缓慢推近。参考视频1的运动节奏。",
    "image": "https://你的图床/参考图1.jpg",
    "duration": 5,
    "size": "16:9"
  }'
```

响应：
```json
{
  "id": "task_xxx",
  "object": "video",
  "model": "seedance-2.0-720p",
  "status": "queued",
  "progress": 0,
  "seconds": "5",
  "size": "16:9"
}
```

#### ⭐ 参考素材怎么传（933 满血用法）

参考素材通过**请求体字段** + **prompt 里 `@图片N` 引用**配合使用：

| 字段 | 类型 | 说明 |
|------|------|------|
| `image` | String | 单张参考图 URL（作为第 1 张）|
| `metadata.images` | List&lt;String&gt; | 多张参考图 URL（追加在 `image` 之后，最多 9 张）|
| `metadata.videos` | List&lt;String&gt; | 参考视频 URL（最多 3 个，消耗 ×1.5）|
| `metadata.audios` | List&lt;String&gt; | 参考音频 URL（最多 3 个）|
| `metadata.mode_type` | String | `text2video`（默认）/ `image2video`（全能参考）/ `frames2video`（首尾帧）|

**prompt 里用 `@图片N` `@视频N` `@音频N` 引用**（N 从 1 开始，按传入顺序）：
- `@图片1` = 第 1 张参考图（`image` 字段那张）
- `@图片2` = `metadata.images` 第 1 张
- `@视频1` = `metadata.videos` 第 1 个

**完整 933 参考示例**（3 图 + 1 视频 + 1 音频）：

```bash
curl -X POST https://soulhub.top/v1/videos \
  -H "Authorization: Bearer <你的key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-720p",
    "prompt": "图片1中的角色按照视频1的动作走路，配音频1的背景音乐，图片2和图片3作为场景参考",
    "image": "https://图床/角色定妆.jpg",
    "duration": 5,
    "size": "16:9",
    "metadata": {
      "mode_type": "image2video",
      "images": ["https://图床/场景1.jpg", "https://图床/场景2.jpg"],
      "videos": ["https://图床/动作参考.mp4"],
      "audios": ["https://图床/背景音乐.mp3"]
    }
  }'
```

> **mode_type 说明**：
> - `text2video`：文生视频，不允许传参考图
> - `image2video`：全能参考（默认，传了参考图自动选这个）
> - `frames2video`：首尾帧，必须正好 2 张参考图（首帧+尾帧）

> **只支持 http/https URL**，不支持 base64/文件上传。参考图必须公网可达。

#### 查询任务（轮询）

```bash
curl https://soulhub.top/v1/videos/task_xxx \
  -H "Authorization: Bearer <你的key>"
```

处理中 → `status: "in_progress"`，完成 → `status: "completed"`，结果在 `metadata.result_url`：

```json
{
  "id": "task_xxx",
  "status": "completed",
  "progress": 100,
  "metadata": { "result_url": "https://xxx/result.mp4" }
}
```

> 视频 URL 有效期约 30 天，建议及时下载。

#### 参数完整说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | String | 是 | 上表 20 个模型名之一 |
| `prompt` | String | 是 | 提示词，用 `@图片N` 引用参考素材 |
| `image` | String | 否 | 参考图 URL（单张）|
| `duration` / `seconds` | Int/String | 否 | 时长 4-15 秒，默认 5 |
| `size` | String | 否 | `16:9` / `9:16` / `1:1` |
| `metadata.images` | List | 否 | 参考图 URL 列表（最多 9 张）|
| `metadata.videos` | List | 否 | 参考视频 URL（最多 3 个，×1.5 计费）|
| `metadata.audios` | List | 否 | 参考音频 URL（最多 3 个）|
| `metadata.mode_type` | String | 否 | 生成模式，见上 |

#### 计费说明

- **按秒模型**：扣费 = duration × 单价（如 720p 5 秒 = 5 × ¥0.52 = ¥2.60）
- **按条模型**（`-flat`/`-flat2`）：固定单价/条，时长 4-15 秒任选不加价
- **参考视频加价**：传了 `metadata.videos` 的任务，消耗 ×1.5

#### Python 完整示例（创建 + 轮询）

```python
import time, requests

API_KEY = "你的key"
BASE = "https://soulhub.top/v1"

# 创建任务（带参考图）
resp = requests.post(f"{BASE}/videos",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={
        "model": "seedance-2.0-720p",
        "prompt": "图片1中的角色正面微笑，镜头缓慢推近",
        "image": "https://图床/参考图.jpg",
        "duration": 5,
        "size": "16:9"
    }, timeout=60)
task_id = resp.json()["id"]
print(f"任务: {task_id}")

# 轮询
while True:
    r = requests.get(f"{BASE}/videos/{task_id}",
                     headers={"Authorization": f"Bearer {API_KEY}"})
    d = r.json()
    print(f"状态: {d['status']} progress={d.get('progress',0)}")
    if d["status"] == "completed":
        url = d.get("metadata",{}).get("result_url","")
        print(f"视频 URL: {url}")
        break
    if d["status"] == "failed":
        print(f"失败: {d.get('error',{})}")
        break
    time.sleep(10)
```

#### 线路怎么选

| 需求 | 推荐模型 | 说明 |
|------|---------|------|
| 最便宜测试 | `seedance-2.0-fast-480p-face` | ¥0.26/秒，验证效果用 |
| 日常出片（性价比）| `seedance-2.0-720p` | ¥0.52/秒，普通线 720p |
| 最高画质 | `seedance-2.0-1080p-pro` 或 `4k-pro` | 专线，画质最好 |
| 真人人脸锁定 | `seedance-2.0-720p-face` | 卡人脸专线 |
| 固定预算（不限时长）| `seedance-2.0-fast-720p-flat` | ¥3.50/条，4-15 秒任选 |

即梦 Seedance 2（豆包视频模型）视频生成，**全部按秒计费**。

#### 完整模型清单 & 价格

| 模型名 | 系列 | 分辨率 | 单价（¥/秒） |
|--------|------|--------|-------------|
| `seedance-2-fast-480p` | Fast（快速版） | 480p | ¥0.48/秒 |
| `seedance-2-fast-720p` | Fast（快速版） | 720p | ¥0.96/秒 |
| `seedance-2-480p` | 标准 | 480p | ¥0.60/秒 |
| `seedance-2-720p` | 标准 | 720p | ¥1.20/秒 |
| `seedance-2-1080p` | 标准（高清） | 1080p | ¥3.36/秒 |
| `seedance-2-4k` | 标准（超高清） | 4K | ¥6.00/秒 |
| `seedance-2-mini-480p` | Mini（轻量版） | 480p | ¥0.38/秒 |
| `seedance-2-mini-720p` | Mini（轻量版） | 720p | ¥0.82/秒 |
| `seedance-2-enhance-720p` | **Enhance（画质增强）** | 720p | ¥0.60/秒 |
| `seedance-2-fast-enhance-720p` | **Fast Enhance（快速画质增强）** | 720p | ¥0.48/秒 |

> 计费公式：`扣费 = duration（秒） × 单价`。例：`seedance-2-fast-720p` duration=10 → 10 × ¥0.96 = ¥9.60。

#### ⭐ 关于 Enhance（画质增强）—— 用户必读

很多用户问 enhance 怎么配，这里统一说明：

**enhance 不是特殊接口，调用方式和普通 seedance 完全一样**，只是 model 名带 `-enhance-`：

```bash
# 普通 720p
"model": "seedance-2-720p"

# 画质增强 720p（改个 model 名就行，其他参数都不变）
"model": "seedance-2-enhance-720p"
```

**enhance 是什么**：即梦后端的「火山生成 + 画质增强」级联工作流——先用标准模型生成视频，再自动做一轮画质超分增强。比直接生成画质更好，但耗时稍长。

**enhance 和普通版的区别**：
| 项 | 普通版 | Enhance 版 |
|----|--------|-----------|
| 调用方式 | 完全一样 | 完全一样 |
| 画质 | 标准 | 生成后额外增强一轮（更清晰） |
| 耗时 | 较快 | 稍长（多了增强步骤） |
| 参数 | `duration` / `ratio` / `prompt` | 完全相同 |

**注意**：enhance 走的是 special 端点，`duration` 最短 **5 秒**（和标准版一致）。

#### 创建任务

```bash
curl -X POST https://soulhub.top/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-enhance-720p",
    "prompt": "一只猫在草地上奔跑，阳光明媚",
    "duration": 5,
    "ratio": "16:9"
  }'
```

响应：
```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "model": "seedance-2-enhance-720p",
  "status": "processing",
  "progress": 0
}
```

#### 查询任务

```bash
curl https://soulhub.top/v1/video/generations/task_xxx \
  -H "Authorization: Bearer $API_KEY"
```

响应（完成）：
```json
{
  "id": "task_xxx",
  "status": "completed",
  "progress": 100,
  "url": "https://soulhub-media-xxx.oss-ap-southeast-1.aliyuncs.com/..."
}
```

> **视频 URL 国内可达**（阿里云 OSS 预签名，1 小时有效），无需代理。

#### 字段说明（Seedance 专属）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 上表任一模型名（含 enhance/mini） |
| `prompt` | string | 是 | 视频描述，中英文均可 |
| `duration` | int | 否 | 时长（秒）。**标准/Fast/Enhance：5-15；Mini：4-15**。不传默认 5 |
| `ratio` | string | 否 | 画面比例：`16:9` / `9:16` / `1:1`，默认 `16:9` |

#### duration 限制（重要，传错会扣费但失败）

| 模型系列 | 最短 | 最长 | 端点 |
|---------|------|------|------|
| 标准 / Fast / Enhance | **5 秒** | 15 秒 | special 端点 |
| Mini | **4 秒** | 15 秒 | face 端点 |

> ⚠️ **传 1-4 秒会失败但仍扣费**（即梦上游行为，中转无法拦截）。标准/Fast/Enhance 系列务必 ≥5 秒。

#### 完整 Python 示例（创建+轮询）

```python
import time, requests

API_KEY = "你的 API Key"
BASE = "https://soulhub.top/v1"

# 1. 创建任务（这里用 enhance 画质增强版示例）
resp = requests.post(f"{BASE}/video/generations",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={
        "model": "seedance-2-enhance-720p",   # 改 model 名就能切换：标准/Fast/Mini/Enhance
        "prompt": "一只猫在草地上奔跑，阳光明媚",
        "duration": 5,                          # 标准/Fast/Enhance ≥5，Mini ≥4
        "ratio": "16:9"                         # 16:9 / 9:16 / 1:1
    },
    timeout=60)
task = resp.json()
task_id = task["task_id"]
print(f"已创建任务: {task_id}")

# 2. 轮询查询（enhance 比普通版慢一点，因为有增强步骤）
while True:
    r = requests.get(f"{BASE}/video/generations/{task_id}",
                     headers={"Authorization": f"Bearer {API_KEY}"})
    data = r.json()
    status = data["status"]
    print(f"状态: {status} progress={data.get('progress', 0)}")
    if status == "completed":
        print(f"视频 URL: {data['url']}")
        break
    if status == "failed":
        print(f"失败: {data.get('error')}")
        break
    time.sleep(15)
```

---


## 4. 真人参考注意事项

即梦 Seedance 2.0 的参考能力（933 满血）对**所有模型统一开放**，不需要单独走人像库/认证流程。但要注意：

### 内容审核（prompt_unsafe）

AIStartLab 上游有内容审核。以下情况可能被拒（返回 `451 prompt_unsafe`，**失败不扣费**）：
- prompt 描述涉及未成年人 + 敏感内容（如"8岁男孩...脸庞清晰"可能触发）
- 参考图含真人面孔 + prompt 描述不当
- 其他违规内容

**解决办法**：
- 调整 prompt 措辞，避免敏感词组合
- 用 AI 生成的写实人像代替真人照片
- 失败的任务不扣费，可以放心重试

### 真人照片 vs AI 人像

| 参考类型 | 是否可用 | 说明 |
|---------|---------|------|
| AI 生成的写实人像 | ✅ 直接用 | 传 `image` 字段即可，无需认证 |
| 动漫/卡通角色 | ✅ 直接用 | 同上 |
| 真人照片（本人授权）| ⚠️ 看审核 | 可能被审核拦，调整 prompt 重试 |
| 真人照片（未授权）| ❌ 禁止 | 平台禁止，会被拒 |

> 不再需要旧版的人像库（portrait）流程。AIStartLab 直接用 `image` / `metadata.images` 字段传参考图 URL 即可。

---

## 5. 错误码参考

| 错误码 | 含义 | 处理 |
|--------|------|------|
| 200 | 成功 | - |
| 400 | 参数错（model 不存在/prompt 空/duration 不合法） | 检查请求体 |
| 401 | API Key 无效 | 检查 Authorization 头 |
| 402 | 余额不足 | 充值 |
| 429 | 限流/capacity | 稍后重试 |
| 500/502/504 | 服务异常 | 稍后重试，或联系管理员 |
| **502 `upstream_unavailable`** | **上游持续故障（image2 特有）** | **等 30s 重试一次（极少出现 <1%）** |
| **503 `QUEUE_FULL`** | **同时发超过 80 张** | **等待或分批发送** |

---

## 6. 常见问题

### Q: 为什么图片/视频 URL 是 OSS 域名？
**A**：视频/生图结果统一转存国内可达的存储，URL 是临时的，请及时下载。

### Q: 国内用户能直接下载吗？
**A**：**能，完全无需代理。** 中转站已配置：
- **OSS 转存**：拉到后上传阿里云 OSS（新加坡 region），返回预签名 URL
- 用户拿到的就是 OSS 直链，浏览器/curl/Python 直接就能下载

实测国内本机下载：99KB JPEG ~11 秒，5MB MP4 视频 ~30 秒（带宽 1.7MB/s 左右）。

### Q: URL 多久失效？
**A**：
- `image2`：通常 24 小时内有效（CDN 自动管理）



### Q: Seedance 视频为什么按秒计费？
**A**：豆包 Seedance 上游按秒收费（如 720p 120 积分/秒），中转站按秒透传给用户（无加价）。用户传 duration=5 就扣 5 秒的钱。

### Q: 视频任务为什么一直 processing？
**A**：视频生成需要 30 秒到 3 分钟（special 端点的「画质增强级联工作流」更慢）。请耐心轮询，最长 5 分钟。

### Q: 跨用户查 task 返回 task_not_exist？
**A**：NewAPI 按 user 隔离 task，**用创建任务时的同一个 API Key 查询**即可。

---

## 7. 联系与状态

- **状态页**：`https://soulhub.top/api/status`
- **控制台**：`https://soulhub.top`
- **文档版本**：v1.0（2026-07-20）