# 小火龙API · 调用文档 > **【计价与显示纪律(2026-09-09 定)】** 一切以人民币为主:定价先定人民币价,存储时 ÷7 写入 ModelPrice;全站显示币种=CNY,计费汇率=充值汇率=7(`Price`/`USDExchangeRate` 均为 7,程序默认 7.3 已覆盖),钱包/日志/广场数字完全一致。改任何价格前先按 ¥ 计算,禁止用美元倒推。 > **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-flash` 🆕 | **DeepSeek V4.1-Flash 正式版**(编程场景主力)· 输入 ¥1/百万tokens(缓存命中 ¥0.02)· 输出 ¥4/百万 · 1M上下文(空闲档,高峰×2)| 按 token(CNY) | | **对话** | `deepseek-v4-pro` | DeepSeek V4 Pro(深度思考)· 输入 ¥4.5/百万tokens · ⚠️ 官方安排 9月14日12:00 起由 V4.1-Flash 按其价格服务 | 按 token(CNY) | | **对话** | `deepseek-v4-flash-vision-exp` | DeepSeek V4 **视觉版**(图片理解)· 已升级 V4.1-Flash · 输入 ¥1/百万 · 输出 ¥4/百万 | 按 token(CNY) | | **生图** | `gpt-image-2-4K` | **统一路由** 4K · 智能路由 · 故障自动转移 · **支持参考图(图生图)** | ¥0.10/张 | | **生图** | `gpt-image-2-ycy` | **高速通道**(2026-09-07 上线)· 成本最低 · 同步直出 + 参考图 | ¥0.06/张 | | **生图** | `gpt-image-2-2K` | **统一路由** 2K · 智能路由 · 故障自动转移 · **支持参考图(图生图)** | ¥0.06/张 | | **生图** | `gpt-image-2-1K` | **统一路由** 1K · 智能路由 · 故障自动转移 · **支持参考图(图生图)** | ¥0.04/张 | | **生图 🆕** | `gpt-image-2.5-flare-1K` | 新架构 2.5 · 1K 快速出图 · **¥0.015/张 全站最低** | ¥0.015/张 | | **生图 🆕** | `gpt-image-2.5-sunburst-1K` | 新架构 2.5 高质 1K | ¥0.015/张 | | **生图 🆕** | `gpt-image-2.5-flare` | 新架构 2.5 主档(支持参考图编辑) | ¥0.06/张 | | **生图 🆕** | `gpt-image-2.5-sunburst` | 新架构 2.5 高质档 | ¥0.10/张 | | **生图 🆕** | `gpt-image-2.5-ycy` 系(3 个) | 2.5 阶梯通道(1K/2K/4K 成本定价 ¥0.04~0.045) | ¥0.04/张起 | | **视频 🆕** | `*-pp` 系(7 个) | PP 通道(独立第三货源):2.0 Mini/Fast、2.5 Pro、MiniMax H3、2.5-30s按条 | 按秒 ¥0.12~0.46 / 按条 ¥3 | | **视频** | `seedance-2.0/2.5-*-` 系列(30 个) | 即梦 Seedance· 933 满血参考 · 4K/卡人脸/**限时线 4K ¥1.20/秒** | 按秒/按条,¥0.22~3.20/秒 | | **视频** | `minimax-h3-*-`(4 个) | 海螺 MiniMax H3 · 480p~2K · 限时回馈 **¥0.08/秒起** | 按秒 | | **视频** | 完整清单见 3.2 节 | 全部走| 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` | **统一路由**(智能路由)| `*.code2alita.com` | ✅ 直接访问 | 4K ¥0.10 / 2K ¥0.06 / 1K ¥0.04 | #### ⭐ 图片/视频结果永久链接(2026-09-02 上线) **所有生图和视频结果的 URL 现在是本站永久链接**(`https://soulhub.top/media/...`): - **不再过期**:结果自动转存到本站存储,链接长期有效,可放心用于「先生图、后提交视频」工作流 - **跨服务引用**:生图返回的 URL 可直接作为视频生成的参考图(`image` / `metadata.images`),不再有临时域失效问题 - 参考图提交时网关会做**预检**:链接不可访问会立即报错(400 invalid_reference),**不提交、不扣费** - 转存文件当前**长期保留、不自动清理**(如需永久保存建议仍下载到本地) - 若转存偶发失败,响应仍返回上游原始 URL(功能自动降级,不影响出图) #### 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" } ``` #### 高速线路:gpt-image-2-ycy(2026-09-07 上线) 低成本备援/主力通道,标准 OpenAI 生图协议,**支持参考图编辑**: | 项 | 说明 | |------|------| | 上游成本 | 按张阶梯:1K ¥0.02 / 2K ¥0.025 / 4K ¥0.03(比星辰线便宜 55%+)| | 售价 | ¥0.06/张(全档统一)| | 端点 | `POST /v1/images/generations`(文生图 + 参考图同一端点)| | 返回 | `data[0].url` = **本站永久链接**(自动转存,不过期)| **文生图**: ```json { "model": "gpt-image-2-ycy", "prompt": "一张干净克制的产品主图,白底,柔和棚拍光", "size": "1024x1024", "quality": "high" } ``` **图生图(参考图)**: ```json { "model": "gpt-image-2-ycy", "prompt": "保持人物面部特征、发型、服装完全不变,将背景改为黄昏海滩", "image": "https://soulhub.top/media/images/xxxx.png", "size": "1024x1024" } ``` **⚠️ 重要**:参考图只放 `image` 字段(单张)。**不要调 `/v1/images/edits`**——直接调会被网关拒绝(500)。 参考图链接推荐用本站永久链接(`soulhub.top/media/...`),不会过期。 可选参数:`quality`(auto/low/medium/high)、`n`(1-4 张)。 #### 协议:同步生图(不要按视频去轮询 task) **gpt-image-2 全系**不是异步任务模型: 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/...` 任务流;**不要和生图混用** 完整对接说明(给客户可转发): `https://soulhub.top/docs/`(在线版) #### 性能 & 并发说明(重要,调用前必读) | 项 | 数值 | |----|------| | **并发上限** | **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 协议 ### 生图完整能力(实测) `gpt-image-2` 全系支持: | 能力 | 用法 | 实测 | |------|------|------| | 文生图 | 只传 `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": "gpt-image-2-1K", "prompt": "一只可爱的橘猫坐在窗台上,阳光从左侧打来", "n": 1, "size": "1024x1024" } ``` #### 单图参考 ```http POST https://soulhub.top/v1/images/generations Authorization: Bearer <你的 API Key> Content-Type: application/json { "model": "gpt-image-2-1K", "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": "gpt-image-2-1K", "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": "gpt-image-2-1K", "prompt": "保持参考图角色外观,生成高清身份板", "size": "3840x2160", "image": "https://your-cdn.com/reference.png", "n": 1 } ``` **实测**:4K + 参考图约 **70-107 秒**。客户端超时 ≥180s。 #### 获取 base64 数据(不走 CDN) ```json { "model": "gpt-image-2-1K", "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 域名 | 国内下载 | 说明 | > |------|-------------|---------|------| > | **`gpt-image-2-*`** | `soulhub.top/media/...`(本站永久链接)| ✅ **直接打开** | 转存本站存储,长期有效 | > > **结论**:**两个生图模型的 URL 国内都能直接下载**,无需自备代理。 > > URL 是临时的(通常 24 小时内有效),请及时下载保存。 ### curl 示例 **gpt-image-2(推荐,国内直接能下载)**: ```bash curl https://soulhub.top/v1/images/generations \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2-1K", "prompt": "a red circle on white background", "size": "1024x1024", "n": 1 }' ``` **图生图(基于参考图修改)**: ```bash curl https://soulhub.top/v1/images/generations \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2-1K", "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 视频(34 个模型) 即梦 Seedance 视频生成(渠道:): > **命名说明(2026-08-18)**:的 20 个旧模型名已全部升级为带 `-` 后缀的新名(如 `seedance-2.0-720p` → `seedance-2.0-720p-`)。**旧名过渡期继续可用**(不少于 14 天),新接入请直接用新名。 > 中转已实测验证:参考图/视频/音频字段 100% 透传到上游,不会出现"无法参考"。 #### ⭐ 完整模型清单(34 个) 模型名规则:`seedance-2.0[-fast]-{分辨率}[-线路后缀]-` - 无后缀 = 普通线路(最便宜)| `-pro` = 专线 | `-face` = 卡人脸专线 | `-flat` = 按条特价 | `-flat2` = 按条标准 | **`-限时` = 限时限量回馈线(channel 64,全网低价)** **🔥 限时限量回馈线(channel 64 · 2026-08-27 上线 · 全部低于普通线)**: | 模型名 | 版本 | 分辨率 | 单价 | |--------|------|--------|------| | `seedance-2.0-fast-480p-限时-` | Fast | 480p | ¥0.22/秒 | | `seedance-2.0-fast-720p-限时-` | Fast | 720p | ¥0.32/秒 | | `seedance-2.0-480p-限时-` | 标准 | 480p | ¥0.30/秒 | | `seedance-2.0-720p-限时-` | 标准 | 720p | ¥0.40/秒 | | `seedance-2.0-1080p-限时-` | 标准 | 1080p | ¥0.70/秒 | | `seedance-2.0-4k-限时-` | 标准 | **4K** | **¥1.20/秒**(普通线 4K 的一半)| **Seedance 2.5(480p/720p 走 63 限时线 · 1080p 走 54 线)**: | 模型名 | 分辨率 | 单价 | |--------|--------|------| | `seedance-2.5-480p-` | 480p | ¥0.38/秒 | | `seedance-2.5-720p-` | 720p | ¥0.65/秒 | | `seedance-2.5-1080p-` | 1080p | ¥2.80/秒 | 2.5 支持 4-30 秒长视频、最多 30 图/10 视频/10 音频参考、带音频生成。 **普通线路(channel 47 · 按秒)**: | 模型名 | 版本 | 分辨率 | 单价 | |--------|------|--------|------| | `seedance-2.0-fast-480p-` | Fast | 480p | ¥0.28/秒 | | `seedance-2.0-fast-720p-` | Fast | 720p | ¥0.42/秒 | | `seedance-2.0-480p-` | 标准 | 480p | ¥0.36/秒 | | `seedance-2.0-720p-` | 标准 | 720p | ¥0.52/秒 | | `seedance-2.0-1080p-` | 标准 | 1080p | ¥0.80/秒 | | `seedance-2.0-4k-` | 标准 | 4K | ¥2.60/秒 | **专线(channel 48 · 按秒 · 模型名加 `-pro`)**: | 模型名 | 版本 | 分辨率 | 单价 | |--------|------|--------|------| | `seedance-2.0-fast-480p-pro-` | Fast | 480p | ¥0.32/秒 | | `seedance-2.0-fast-720p-pro-` | Fast | 720p | ¥0.48/秒 | | `seedance-2.0-480p-pro-` | 标准 | 480p | ¥0.40/秒 | | `seedance-2.0-720p-pro-` | 标准 | 720p | ¥0.58/秒 | | `seedance-2.0-1080p-pro-` | 标准 | 1080p | ¥1.20/秒 | | `seedance-2.0-4k-pro-` | 标准 | 4K | ¥3.20/秒 | **卡人脸专线(channel 53 · 按秒 · 模型名加 `-face`)**: > 卡人脸线针对真人人脸锁定优化。480p/720p/1080p。 | 模型名 | 版本 | 分辨率 | 单价 | |--------|------|--------|------| | `seedance-2.0-fast-480p-face-` | Fast | 480p | ¥0.24/秒 | | `seedance-2.0-fast-720p-face-` | Fast | 720p | ¥0.36/秒 | | `seedance-2.0-480p-face-` | 标准 | 480p | ¥0.32/秒 | | `seedance-2.0-720p-face-` | 标准 | 720p | ¥0.46/秒 | | `seedance-2.0-1080p-face-` | 标准 | 1080p | ¥0.72/秒 | **按条计费(固定 720P · 时长 4-15 秒任选)**: | 模型名 | 版本 | 线路 | 单价 | |--------|------|------|------| | `seedance-2.0-fast-720p-flat-` | Fast | 限时特价(channel 50) | ¥3.50/条 | | `seedance-2.0-720p-flat-` | 标准 | 限时特价(channel 50) | ¥4.50/条 | | `seedance-2.0-fast-720p-flat2-` | Fast | 按条标准(channel 49) | ¥6.00/条 | | `seedance-2.0-720p-flat2-` | 标准 | 按条标准(channel 49) | ¥7.20/条 | **Wan3.0(channel 62 · 按秒 · 2026-09-10 上新)**: > 标准版/Prime 优速版。2-30秒直出 · 支持10图+5视频+5音频全能参考 · 画幅 16:9/9:16/1:1/4:3/3:4。 | 模型名 | 版本 | 分辨率 | 单价 | |--------|------|--------|------| | `wan-3.0-480p-asl` | 标准版 | 480p | ¥0.16/秒 | | `wan-3.0-720p-asl` | 标准版 | 720p | ¥0.32/秒 | | `wan-3.0-1080p-asl` | 标准版 | 1080p | ¥0.52/秒 | | `wan-3.0-prime-480p-asl` | Prime优速 | 480p | ¥0.18/秒 | | `wan-3.0-prime-720p-asl` | Prime优速 | 720p | ¥0.36/秒 | | `wan-3.0-prime-1080p-asl` | Prime优速 | 1080p | ¥0.58/秒 | **MiniMax H3 4K(channel 59 · 按秒 · 2026-09-10 上新)**: | 模型名 | 分辨率 | 单价 | |--------|--------|------| | `minimax-h3-4k-asl` | 4K | ¥0.40/秒 | > MiniMax 系支持文生/图生,5-15秒,9图+3音频,原生真人脸;画幅 16:9/9:16。参考图/音频放 `metadata.images/audios`。 #### 海螺 MiniMax H3 视频(· channel 59 · 2026-08-27 上线) | 模型名 | 分辨率 | 单价 | |--------|--------|------| | `minimax-h3-480p-` | 480p | **¥0.08/秒** | | `minimax-h3-768p-` | 768p | ¥0.12/秒 | | `minimax-h3-1080p-` | 1080p | ¥0.16/秒 | | `minimax-h3-2k-` | 2K | ¥0.20/秒 | 不卡人脸 · 限时回馈价。调用方式与 Seedance 完全一致(`POST /v1/videos` + prompt/seconds/参考图)。 #### 参考能力(933 满血 · 所有模型统一) **全部 22 个模型都支持**: - **9 张参考图**(`inputImagesMax: 9`) - **3 个参考视频**(`inputVideosMax: 3`) - **3 个参考音频**(`inputAudiosMax: 3`) > 参考视频的积分消耗 = 基础 × **1.5**(`inputVideoMultiplier: 1.5`)。参考图/音频不加价。 ### 3.4 超值线路 Seedance(17 个模型 · 2026-09-09 按条SKU改版) > **⚠️ 超值线路说明(2026-09-10 起)**:本线路为低成本通道,上游存在**偶发**画幅异常(如 16:9 出成 1:1)、水印、时长偏差等已知问题,**遇到重试即可**。**此类偶发问题不售后**,下单前请自行斟酌;对画质/画幅有硬性要求的场景建议使用标准线路。 低成本视频通道(**冲量线按条计费**、其余按秒计费),统一协议经网关翻译。 **调用方式(⚠️ 两类模型写法不同,务必区分):** **A. 按条 SKU(模型名带 `-15s` / `-30s` 后缀)**——时长放 `metadata.seconds`,档内任选、条价不变;**不要传顶层 seconds**: ```json { "model": "hx-2.5-chongliang-720p-30s", "prompt": "a white cat walking on green grass", "metadata": { "seconds": 22, "ratio": "16:9", "images": ["https://soulhub.top/media/images/参考图.png"] } } ``` **B. 按秒模型(其余全部:biaozhun / fast / guanbu / wan3 / minimax 等)**——时长**必须**传**顶层 `seconds`**(字符串);传 `metadata.seconds` 无效(网关直接报错提示,不会出片): ```json { "model": "hx-2.5-guanbu-720p", "prompt": "a white cat walking on green grass", "seconds": "30", "metadata": { "ratio": "16:9", "images": ["https://soulhub.top/media/images/参考图.png"] } } ``` - 画幅统一放 `metadata.ratio`(16:9 / 9:16 等);参考图放 `metadata.images` - **prompt ≤ 5000 字符**(网关预检,超长直接 400 拒单,不产生扣费) - 按条计费与时长无关:选错档位/规格由调用方自行负责 #### HX 模型清单(13 个) | 模型名 | 计费 | 说明 | |--------|------|------| | `hx-2.5-chongliang-720p-15s` | **¥3.50/条** | 2.5冲量 720P · 4-15秒任选(时长放 metadata.seconds)· 支持10图(2026-09-16 上游调价)| | `hx-2.5-chongliang-720p-30s` | **¥4.50/条** | 2.5冲量 720P · 16-30秒任选(时长放 metadata.seconds)· 支持10图(2026-09-16 上游调价)| | `hx-2.0-chongliang-720p-15s` | **¥0.8/条** | 2.0冲量 720P · 5-15秒(时长放 metadata.seconds)· 支持9图 | | `hx-2.5-manju-720p-30s` | ~已下架~ | 2.5漫剧 720P(2026-09-16 上游产品下架)| | `hx-wan3-chongliang-1080p-30s` | **¥6/条** | Wan3冲量 1080P · **固定30秒**(metadata.seconds=30)· 支持10图+5音频+5视频参考 | | `hx-wan3-480p` | ¥0.15/秒 | Wan3.0 官方直连 480P · 4-30秒 · 支持20个多模态参考(图/音/视频)· 稳定保底 | | `hx-wan3-720p` | ¥0.30/秒 | Wan3.0 官方直连 720P · 4-30秒 · 支持20个多模态参考(图/音/视频)· 稳定保底 | | `hx-wan3-1080p` | ¥0.60/秒 | Wan3.0 官方直连 1080P · 4-30秒 · 支持20个多模态参考(图/音/视频)· 稳定保底 | | `hx-minimax-h3-2k` | **¥1.5/条** | MiniMax H3 2K · 4-15秒任选(时长放 metadata.seconds)· 支持9图+3音频 · **原生真人脸** | | `hx-2.0-biaozhun-480p` | ¥0.56/秒 | 2.0标准 480P(按实测成本定价) | | `hx-2.0-biaozhun-720p` | ¥0.60/秒 | 2.0标准 720P | | `hx-2.0-fast-480p` | ¥0.35/秒 | 2.0 Fast 480P | | `hx-2.0-fast-720p` | ¥0.40/秒 | 2.0 Fast 720P(优惠版)| | `hx-2.0-720p-duotongdao` | ~~已下架~~ | 多通道线(2026-09-09 下架:上游要求必传 line 参数且成本口径未核实,待重新定价后上架)| | `hx-2.0-480p-duotongdao` | ~~已下架~~ | 同上 | | `hx-2.5-guanbu-480p` | ¥0.40/秒 | 2.5官补 480P · **必须传参考图** · ⚠️ 上游调整中偶发失败(重试可解)| | `hx-2.5-guanbu-720p` | ¥0.70/秒 | 2.5官补 720P · **必须传参考图** · ⚠️ 上游调整中偶发失败(重试可解)| ### 3.5 PP 通道 Seedance(7 个模型 · 2026-09-11 上新 · 独立第三货源) > ⚠️ **写法与 3.4 节 B 类相同(按秒模型)**:时长传**顶层 `seconds`**(字符串);画幅 `metadata.ratio`;参考图 `metadata.images`。按条模型 `seedance-2.5-30s-pp` 固定 30 秒(`seconds: "30"`)。全部原价直售。供应商分组:Seedance 系→即梦、MiniMax→MiniMax。 | 模型名 | 单价 | 规格 | |--------|------|------| | `seedance-2.0-mini-480p-pp` | ~~已下架~~ | 2.0 Mini 480P(PP 上游线路调整,待新货源)| | `seedance-2.0-mini-720p-pp` | ~~已下架~~ | 同上 | | `seedance-2.0-fast-480p-pp` | ~~已下架~~ | 2.0 Fast 480P(同上)| | `seedance-2.0-fast-720p-pp` | ~~已下架~~ | 同上 | | `seedance-2.5-720p-pro-pp` | ~~已下架~~ | 2.5 Pro 720P(PP 上游线路调整)| | `minimax-h3-720p-pp` | ¥0.15/秒 | MiniMax H3 720P · 6-15秒 · 9图(首帧/首尾帧/多图)+3视频+3音频 · 不卡脸 | | `seedance-2.5-30s-pp` | ~~已下架~~ | 2.5-900 30秒(2026-09-15 上游下架)| **扩展档位(2026-09-11 全家桶上新,共 21 个)**: | 模型名 | 单价 | 规格 | |--------|------|------| | `seedance-2.0-pro-480p-pp` | ~~已下架~~ | 2.0 满血 Pro 480P(2026-09-15 上游整线下架)| | `seedance-2.0-pro-720p-pp` | ~~已下架~~ | 2.0 满血 Pro 720P(上游整线下架)| | `seedance-2.0-pro-1080p-pp` | ~~已下架~~ | 2.0 满血 Pro **1080P**(上游整线下架)| | `seedance-2.0-pro-4k-pp` | ~~已下架~~ | 2.0 满血 Pro **4K**(上游整线下架)| | `seedance-2.5-pro-480p-pp` | **¥0.38/秒** | 2.5 Pro 480P · 4-30秒 · 30图+10视频+10音频 · 原生人脸(2026-09-15 上游调价 0.33→0.38)| | `seedance-2.5-pro-1080p-pp` | **¥1.28/秒** | 2.5 Pro **1080P** · 同上(2026-09-15 上游调价 0.76→1.28)| | `seedance-2.5-720p-gt-pp` | ~~已下架~~ | GT 官方线(上游下架)| | `seedance-2.0-mini-gt-pp` | ¥0.28/秒 | 2.0 Mini 官方接口线 · 933过人脸稳定 | | `seedance-2.5-480p-ac-pp` | **¥0.40/秒** | 2.5 480P(HAYA-2)· 4-30秒 · 30图+10视频+3音频(2026-09-15 换货源降价,原AC线下架)| | `seedance-2.0-933s-480p-pp` | ¥2.2/条 | 933稳定线 480P · 15秒(4-15秒)· 图+视频+音频 | | `seedance-2.0-933s-720p-pp` | ¥3.5/条 | 933稳定线 720P · 15秒 · 同上 | | `seedance-2.0-f933-720p-pp` | ¥4.00/条 | 2.0 Fast 933(HN) 720P · 15秒 · 9图+3视频+3音频 · 真人 | | `seedance-2.0-full933-720p-pp` | ¥5.20/条 | 2.0 满血 933(HN) 720P · 15秒 · 同上 | | `seedance-2.0-900md-720p-pp` | ¥1.20/条 | 2.0 900(MD) 720P · 5/10/15秒 · 9图 · 五档画幅 | | `seedance-2.5-900md-720p-pp` | ¥3.50/条 | 2.5 900(MD) 720P · 5/10/15秒 · 9图+人脸 · 五档画幅 | | `seedance-2.0-900-pp` | ¥1.30/条 | 2.0 900 专线 720P · 15秒 · 9图 | | `seedance-2.0-i2v933-720p-pp` | ~~已下架~~ | i2v 933(上游下架)| | `seedance-2.5-30s-yj-pp` | ~~已下架~~ | 2.5 30秒(YJ)(2026-09-15 上游下架)| | `seedance-2.5-30s-10img-pp` | ¥4.50/条 | 2.5 30秒 10图(AC)· 真人参考 | | `seedance-2.5-allref-30s-pp` | ¥4.20/条 | 全能参考 720P · 4-30秒(建议≥20秒)· 30图+10音频 | | `seedance-2.5-301010t-720p-pp` | ~~已下架~~ | 2.5 301010T(2026-09-15 上游下架)| > PP 通道参考图上限均为 **9 张**(超出直接拒绝),参考图需公网 HTTPS 直链。 | `hx-2.0-biaozhun-1080p` | ~~已下架~~ | 2.0标准 1080P(待 HX 报成本后重上)| | `hx-2.5-guanqu-480p` | ~~已下架~~ | 2.5官渠 480P(疑似按条计费,待 HX 确认后重上)| > 2026-09-09 改版:原按秒计费的 `hx-2.5-chongliang-720p`、`hx-2.0-chongliang-720p` 已下架,由上述固定时长按条 SKU 替代(上游按条收费,按秒摊价会导致短时长亏损/长时长虚高)。 #### ⚠️ HX 限制(务必注意) 1. **`hx-2.5-guanbu-480p / -720p` 官补线是全能参考模式——必须传至少 1 张参考图,不支持纯文生**(纯文生会报错,积分自动退还) 2. 参考图支持 9 图 + 3 音频(部分线支持视频参考) 3. ad/多通道线锁画幅(16:9 或 9:16) 4. HX 通道的参考图链接必须公网可访问(推荐用本站永久链接) 5. **prompt ≤ 5000 字符**:网关已做提交预检,超长直接 400 `prompt_too_long`(不再先扣后退) #### 参考:H3 系(慧心同平台价格对照) - `minimax-h3-480p` 有售 ¥0.08/秒;HX 平台同款 ¥0.05/秒(768P)——如需批量可联系开通 #### 时长 - Seedance 2.0:**最短 4 秒,最长 15 秒**,连续可选(任意整数秒) - Seedance 2.5:最长 **29-30 秒** - 用 `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<String> | 多张参考图 URL(追加在 `image` 之后,最多 9 张)| | `metadata.videos` | List<String> | 参考视频 URL(最多 3 个,消耗 ×1.5)| | `metadata.audios` | List<String> | 参考音频 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.24/秒,验证效果用 | | 日常出片(性价比)| `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.top/media/videos/2026-09-02/vid_xxx.mp4" } ``` > **视频 URL 为本站永久链接**(`soulhub.top/media/...`,2026-09-02 起自动转存,长期有效)。 #### 字段说明(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`** | **上游持续故障(生图)** | **等 30s 重试一次(极少出现 <1%)** | | **503 `QUEUE_FULL`** | **同时发超过 80 张** | **等待或分批发送** | --- ## 6. 常见问题 ### Q: 为什么图片/视频 URL 是 soulhub.top/media/ 域名? **A**:2026-09-02 起中转站自动把生成结果**转存到自有存储**,返回本站永久链接(`soulhub.top/media/...`),不再使用上游临时链接——**长期有效不过期**,可放心用于「先生图、后提交视频」等工作流。 ### Q: 国内用户能直接下载吗? **A**:**能,完全无需代理。** 永久链接走本站国内可达通道,浏览器/curl/Python 直接下载。 ### Q: 转存文件会过期吗? **A**:当前**长期保留、不自动清理**。如担心极端情况,重要文件仍建议下载一份到本地。 ### 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` - **文档版本**:v2.0(2026-09-03,媒体永久链接 + 双渠道 + 参考图预检)