# 账户与用量
Source: https://looptoken.vibelab.me/docs/account-usage
> 用 API Key 查询账户余额、今日/本月/累计用量、Key 配额，以及单个任务实际扣除的积分
## 查询账户用量
使用与模型调用相同的 API Key 鉴权，不需要控制台登录令牌。返回 API Key 所属账户的当前余额、请求统计，以及当前 API Key 的配额状态。
```bash
curl https://api.vibelab.me/v1/account/usage \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
## 响应示例
```json
{
"object": "account.usage",
"timezone": "Asia/Shanghai",
"balance": "98.75",
"month_credits": "12.75",
"total_recharged_credits": "130",
"usage": {
"today": {
"requests": 12,
"successful_requests": 11,
"credits": "1.5"
},
"month": {
"requests": 86,
"successful_requests": 82,
"credits": "12.75"
},
"all_time": {
"requests": 240,
"successful_requests": 231,
"credits": "31.25"
}
},
"api_key": {
"used": "20.5",
"quota": "100",
"remaining_quota": "79.5"
}
}
```
## 字段说明
| 字段 | 类型 | 说明 |
| ----------------------------- | -------------- | ------------------------------ |
| `object` | string | 固定为 `account.usage` |
| `timezone` | string | 今日和本月统计的时区,固定为 `Asia/Shanghai` |
| `balance` | string | 当前可用积分;提交任务后的预冻结金额已经从该值扣除 |
| `month_credits` | string | 本月成功结算请求实际消耗的积分,按 UTC+8 自然月统计 |
| `total_recharged_credits` | string | 账户历史充值到账的积分总额;不包含管理员调账、退款或其他流水 |
| `usage.*.requests` | integer | 对应周期内的全部请求数,包含失败请求 |
| `usage.*.successful_requests` | integer | 对应周期内成功结算的请求数 |
| `usage.*.credits` | string | 对应周期内成功结算请求实际消耗的积分 |
| `api_key.used` | string | 当前 API Key 的终身累计用量,用于配额控制 |
| `api_key.quota` | string \| null | 当前 API Key 的配额;未设置配额时为 `null` |
| `api_key.remaining_quota` | string \| null | 剩余配额,最低为 `0`;未设置配额时为 `null` |
积分字段以精确十进制字符串返回,调用方不应使用二进制浮点数进行财务计算。
## 统计范围与更新时机
* `balance` 和 `usage` 是 API Key 所属**整个账户**的数据,包含该账户下其他 API Key 的调用。
* `api_key` 只描述本次鉴权使用的 API Key。
* `today` 按 UTC+8 自然日统计,`month` 按 UTC+8 自然月统计,`all_time` 为全部历史记录。
* 请求结算与用量日志写入可能存在短暂延迟。刚完成调用后立即查询时,余额通常已更新,但用量统计可能稍后才可见。
## 查询单个任务的消耗积分
按提交任务时返回的任务 ID 查询实际扣除的积分。鉴权方式与模型调用相同，只能查询 API Key 所属账户的任务。
```bash
curl https://api.vibelab.me/v1/tasks/vt_0192f3a8-7c1e-7d4b-9a10-3b5e8c2d6f41/billing \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
```json
{
"task_id": "vt_0192f3a8-7c1e-7d4b-9a10-3b5e8c2d6f41",
"model": "seedance-2-0",
"status": "succeeded",
"credits_charged": 12.5,
"created_at": "2026-10-18T03:21:07Z",
"completed_at": "2026-10-18T03:23:41Z"
}
```
| 字段 | 类型 | 说明 |
| ----------------- | -------------- | -------------------------- |
| `task_id` | string | 请求中的任务 ID |
| `model` | string | 任务使用的模型 |
| `status` | string | 任务状态,取值随任务类型而异,与对应任务查询接口一致 |
| `credits_charged` | number \| null | 实际扣除的积分;任务尚未结算时为 `null` |
| `created_at` | string | 任务创建时间 |
| `completed_at` | string \| null | 任务结束时间;未结束时为 `null` |
支持的任务 ID:
| 前缀 | 任务类型 |
| --------- | ------------------------------ |
| `vt_` | 视频 |
| `it_` | 图像 |
| `mj_` | Midjourney |
| `at_` | 音频 |
| `avatar_` | 数字人素材 |
| 无统一前缀 | 方舟协议视频任务,使用其任务 ID(如 `cgt-...`) |
说明:
* 任务失败、过期或取消时不收费,`credits_charged` 为 `0`。
* 任务运行中或刚结束时,`credits_charged` 可能暂时为 `null`,稍后再查。
* 任务不存在或不属于当前账户返回 HTTP 404 `task_not_found`;当前 API Key 无权使用该模型返回 403 `model_not_allowed`。
* 暂不支持 Kling 旧风格接口的任务和文本对话请求。
## 鉴权错误
缺失、格式错误、已禁用或不存在的 API Key 返回 HTTP 401 和 `invalid_api_key`。参见[鉴权](/authentication)与[错误码](/errors)。
# 鉴权
Source: https://looptoken.vibelab.me/docs/authentication
> 所有 /v1/* 接口使用 Authorization Bearer sk-lt-... 鉴权（Claude 的 /v1/messages 也接受 x-api-key）；API Key 的配额、模型白名单、IP 白名单与限流行为
所有 `/v1/*` 接口都要求在请求头中携带 API Key：
```
Authorization: Bearer sk-lt-...
```
缺失该请求头、或值不以 `Bearer sk-lt-` 开头，直接返回 401。
Claude 系列的 [`/v1/messages`](/chat/claude) 与 Anthropic 官方一致，也接受 `x-api-key: sk-lt-...`（Anthropic SDK、Claude Code 配 `ANTHROPIC_API_KEY` 时使用）；两个头都带时以 `Authorization` 为准。
## 管理 API Key
在控制台API Key 管理页可以：
* 创建 key（可填名称，可选设置配额）。
* 随时查看已创建 key 的明文。
* 禁用 key，立即生效，无需等待缓存过期。
## 限制行为
| 限制 | 触发条件 | HTTP | `code` | 说明 |
| ----- | ----------------------- | ---- | ------------------- | ---------------------------------------------------------------------------------------------- |
| 配额 | 已设置配额的 key 累计已结算用量达到配额 | 403 | `quota_exceeded` | 不设置配额则不受限；仅对非 GET/HEAD 请求生效，查询接口不受影响；用[账户与用量接口](/account-usage)（`GET /v1/account/usage`）查询配额状态 |
| 模型白名单 | key 配有白名单，且请求的模型不在其中 | 403 | `model_not_allowed` | 不设置白名单则可调用全部模型；控制台暂未开放白名单自助设置 |
| 鉴权失败 | key 不存在、已禁用、已过期、缺失或格式错误 | 401 | `invalid_api_key` | 缺失或格式错误时 `message` 为 `missing or malformed API key`，否则为 `invalid or disabled API key` |
\| IP 白名单 | key 配有 IP 白名单，且客户端 IP 不在其中 | 403 | `ip_not_allowed` | `message` 为 `client IP not allowed for this key` |
\| 限流 | 用户或 key 的请求频率超限（非 GET/HEAD） | 429 | `rate_limit_exceeded` | 稍后重试；限流组件不可用时返回 503 `limits_unavailable` |
\| 账户 API 已停用 | 账户的 API 调用被关闭 | 503 | `model_call_failed` | `message` 为 `Model call failed, please try again later.` |
以上错误的响应体结构相同，以 401 为例（`request_id` 每次不同）：
```json
{"error":{"code":"invalid_api_key","message":"invalid or disabled API key","request_id":"...","type":"invalid_api_key"}}
```
`quota_exceeded` 的 `message` 为 `API key quota exceeded (settled usage)`，`model_not_allowed` 的 `message` 为 `model not allowed for this key`。完整错误码见[错误码](/errors)。
## 安全建议
* 不要把 API Key 硬编码或暴露在前端、客户端、移动端代码中，始终从服务端调用。
* 怀疑泄露时，立即在控制台禁用该 key 并创建新 key。
# Claude Code 接入
Source: https://looptoken.vibelab.me/docs/claude-code
> 用原生 Anthropic Messages API 把 Claude Code 接入 LoopToken：环境变量、settings.json、模型选择、验收命令与常见问题
LoopToken 提供与 Anthropic 官方一致的 Messages API（`/v1/messages`、`/v1/messages/count_tokens`），Claude Code 无需任何协议转换，配置 Base URL 和 Key 即可直连。
| 配置项 | 值 |
| -------- | ------------------------------------------------------------------------------------------------------------- |
| Base URL | `https://api.vibelab.me`（不带 `/v1`） |
| Key | 在API Key 管理页创建的 `sk-lt-...`，不要填 Anthropic 官方 `sk-ant-` 密钥 |
| 模型 | `claude-fable-5-1` / `claude-opus-5-5` / `claude-sonnet-5-5` / `claude-haiku-5-5`，见 [Claude 系列](/chat/claude) |
## 配置
### 写入 settings.json
编辑 `~/.claude/settings.json`（已有其他字段则保留，只合并 `env`）：
```json
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.vibelab.me",
"ANTHROPIC_AUTH_TOKEN": "sk-lt-...",
"ANTHROPIC_MODEL": "claude-opus-5-5",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5"
}
}
```
| 变量 | 作用 |
| ----------------------------------------------------------------- | ------------------------------------------------------------------- |
| `ANTHROPIC_BASE_URL` | 请求发往 LoopToken，Claude Code 自己拼接 `/v1/messages` |
| `ANTHROPIC_AUTH_TOKEN` | LoopToken Key，以 `Authorization: Bearer` 发送；只填裸 Key，不要加 `Bearer ` 前缀 |
| `ANTHROPIC_MODEL` | 默认使用的模型 |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` / `_SONNET_MODEL` / `_HAIKU_MODEL` | `/model` 里 `opus` / `sonnet` / `haiku` 别名对应的模型；Haiku 也用于后台小任务 |
也可以用 `ANTHROPIC_API_KEY` 代替 `ANTHROPIC_AUTH_TOKEN`（以 `x-api-key` 发送），但交互模式首次启动需要手动批准一次，推荐用 `ANTHROPIC_AUTH_TOKEN`。
Key 不要写进项目目录下的
`.claude/settings.json`
，该文件通常会提交到仓库。只在本机用时写
`~/.claude/settings.json`
或
`.claude/settings.local.json`
。
### 或使用环境变量
只想临时试用，不改配置文件：
```bash
export ANTHROPIC_BASE_URL="https://api.vibelab.me"
export ANTHROPIC_AUTH_TOKEN="sk-lt-..."
export ANTHROPIC_MODEL="claude-opus-5-5"
claude
```
settings.json 的 `env` 与 shell 环境变量同时存在时，以 settings.json 为准。
### 验收
```bash
claude -p "只回复 LOOP_TOKEN_CLAUDE_OK"
```
能收到回复，并且控制台用量记录里出现对应请求，说明已接通。进入交互模式后执行 `/status`：
* `Anthropic base URL` 一行显示 `https://api.vibelab.me`；
* `Auth token` 一行指向 `ANTHROPIC_AUTH_TOKEN`。
如果显示的是 claude.ai 登录方式，说明配置没有生效，检查 settings.json 路径和 JSON 格式。最后在测试目录执行一次需要工具的任务（如"列出当前目录的文件并总结"），能读文件、执行命令并完成第二轮回复，才算完整接入。
## 切换模型
* **会话内** → `/model claude-sonnet-5-5`，或 `/model opus` / `/model sonnet` / `/model haiku`（按上面三个 `DEFAULT_*` 变量解析）。
* **单次启动** → `claude --model claude-fable-5-1`。
* **子代理** → 设置 `CLAUDE_CODE_SUBAGENT_MODEL`（如 `claude-sonnet-5-5`）。
| 场景 | 建议模型 |
| ---------------- | ------------------- |
| 日常编码、重构、Agent 任务 | `claude-opus-5-5` |
| 更看重速度和成本 | `claude-sonnet-5-5` |
| 最难的推理与长时程任务 | `claude-fable-5-1` |
| 后台小任务、子代理批量读取 | `claude-haiku-5-5` |
## 计费说明
Claude Code 会大量使用 Prompt 缓存：每轮把系统提示词、工具定义和历史写入缓存，之后的轮次按缓存读取价计费，比普通输入便宜很多。用量按输入 / 输出 / 缓存读取 / 缓存写入（5m）/ 缓存写入（1h）五项结算，单价见 [Claude 系列 · 计费](/chat/claude#计费)。
* **预扣** → 每次请求按 `max_tokens` 冻结输出费用，结算后多退少补。Claude Code 的 `max_tokens` 较大，余额太低会直接收到 `402`。
* **`/context`** → 依赖 `/v1/messages/count_tokens`，由 LoopToken 本地估算，数字是近似值，不计费。
## 可选配置
| 变量 | 作用 |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` | 关闭自动更新检查、遥测、错误上报等非必要请求 |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` | 不发送预发布 beta 头与对应字段；遇到 `Unexpected value(s)`、`Extra inputs are not permitted` 时开启（会同时关闭 MCP tool search） |
| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1` | `sk-lt-` 不是 Anthropic 官方 Key 格式，`/fast` 可能显示不可用，开启后跳过该检查的报错 |
## 常见问题
| 现象 | 排查 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `401 authentication_error` | 确认用的是 `sk-lt-` 开头的 LoopToken Key；`ANTHROPIC_AUTH_TOKEN` 里不要带 `Bearer ` 前缀 |
| `/status` 仍显示 claude.ai 登录 | 只设了 Base URL、没设 Key 时会继续用订阅；补上 `ANTHROPIC_AUTH_TOKEN`，必要时执行 `/logout` |
| `404 not_found_error` | 模型名写错，或该 Key 的模型白名单不包含它 |
| `402 billing_error` | 余额不足以覆盖本次预扣，充值后重试 |
| `400 ... prompt is too long` | 上下文超出窗口，Claude Code 会自动压缩；也可手动执行 `/compact` |
| 请求了 `/v1/v1/messages` | Base URL 多写了 `/v1`，改为 `https://api.vibelab.me` |
| 改用 CC Switch | Claude Provider 使用 Anthropic 原生格式（不要选 OpenAI Chat Completions），Base URL 填 `https://api.vibelab.me`，Key 填 `sk-lt-...`，无需开启协议转换代理 |
# Codex 接入
Source: https://looptoken.vibelab.me/docs/codex-ccswitch
> 用 Responses API 把 Codex CLI / Codex App、CC Switch 接入 LoopToken：配置文件、验收命令与常见问题
LoopToken 同时提供 OpenAI Responses API 与 Chat Completions API，两种协议共用同一套 API Key、模型权限、余额、计费与用量记录。
| 客户端 | Base URL | 协议 |
| --------------------------- | --------------------------- | ------------------------------------------------------- |
| Codex CLI / Codex App | `https://api.vibelab.me/v1` | OpenAI Responses API |
| CC Switch 的 Codex Provider | `https://api.vibelab.me/v1` | OpenAI Responses API |
| Claude Code（直连或经 CC Switch） | `https://api.vibelab.me` | Anthropic Messages API，见 [Claude Code 接入](/claude-code) |
## 准备 Key 和模型名
在API Key 管理页创建 `sk-lt-` 开头的 Key，不要填 OpenAI、Anthropic 或其他平台的密钥。用标准端点确认该 Key 可用的模型：
```bash
curl https://api.vibelab.me/v1/models \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
返回的 `data[].id` 就是配置里要填的模型名。是否适合编码、是否支持工具调用取决于模型本身；Codex 建议选 GPT/Codex 系列，并完成下方验收。
## Codex
### 写入 API Key
`~/.codex/auth.json`（已有其他字段则保留，只更新 `OPENAI_API_KEY`）：
```json
{
"OPENAI_API_KEY": "sk-lt-..."
}
```
### 配置 Provider
`~/.codex/config.toml`：
```toml
model_provider = "looptoken"
model = "你的模型名"
preferred_auth_method = "apikey"
model_reasoning_effort = "medium"
# 让 0.166 以下的旧版 Codex 也发送推理参数并回传加密推理内容
model_supports_reasoning_summaries = true
# Codex 每轮发送完整历史，不依赖服务端存储的会话。
disable_response_storage = true
[model_providers.looptoken]
name = "LoopToken"
base_url = "https://api.vibelab.me/v1"
wire_api = "responses"
requires_openai_auth = true
# Codex 0.166 起会从这里拉取模型元数据（推理档位、上下文窗口、Fast 档等）
model_catalog_url = "https://api.vibelab.me/v1/codex/models"
```
重启 Codex 生效。不要配置新版 Codex 已移除的 `wire_api = "chat"`。
不配 `model_catalog_url` 时，Codex 会提示 `Model metadata for ... not found`，按通用元数据运行，不发送推理强度，效果会变差。建议升级到 Codex 0.166 及以上并保留这一行。
### 验收
```bash
codex exec "只回复 LOOP_TOKEN_CODEX_OK"
```
成功会看到模型回复，控制台用量记录里能看到对应请求。编码 Agent 还需要工具调用，再在测试目录执行：
```bash
codex exec "使用 shell 工具执行 pwd，然后告诉我目录名"
```
模型发起工具调用、Codex 在本机执行并完成第二轮回复，才算完整接入成功。
## CC Switch
### 一键导入
在API Key 管理页点击 Key 旁的 **导入 CCS**，CC Switch 会弹出确认框，导入后自动完成：
* Codex Provider（Base URL、Key、默认模型，以及上文 `config.toml` 中的推理设置与 `model_catalog_url`）
* 余额查询：卡片上显示剩余积分，每 30 分钟自动刷新
### 余额查询
LoopToken 提供与 CC Switch 内置「Sub2API」模板兼容的余额接口，手动添加的 Provider 在「配置用量查询」里选 **Sub2API** 模板即可：
```bash
curl https://api.vibelab.me/v1/usage -H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
```json
{"isValid": true, "planName": "LoopToken", "remaining": 1234.5, "unit": "积分"}
```
`remaining` 为账户剩余积分；Key 设置了额度时取账户余额与 Key 剩余额度中较小的值，并额外返回 `quota.limit` / `quota.used`。余额耗尽时 `isValid` 为 `false`。
### Codex Provider（手动添加）
在 CC Switch 切换到 **Codex**，新增自定义 Provider：
| 配置项 | 值 |
| --------------------- | ------------------------------------ |
| 名称 | `LoopToken` |
| API Key | `sk-lt-...` |
| Endpoint / Base URL | `https://api.vibelab.me/v1` |
| Model | `/v1/models` 返回的模型名 |
| API Format / Wire API | `OpenAI Responses API` / `responses` |
保存并启用后重启 Codex。若有"获取模型"按钮，可直接通过 `/v1/models` 读取。
### Claude Code Provider
Claude Code 使用 Anthropic Messages 协议，LoopToken 原生提供 `/v1/messages`，不需要协议转换：在 CC Switch 切换到 **Claude**，新增 Provider，使用 Anthropic 原生格式（不要选 OpenAI Chat Completions，也无需开启代理接管），Base URL 填 `https://api.vibelab.me`，Key 填 `sk-lt-...`，模型填 `claude-*`。完整配置见 [Claude Code 接入](/claude-code)。
## Responses API 支持范围
GPT 系列请求原样转发到 OpenAI Responses 上游，Codex 用到的能力完整可用：
* `input` / `instructions`、文本与工具调用的流式事件
* 推理：`reasoning.effort` / `summary`，`include: ["reasoning.encrypted_content"]` 的加密推理跨轮续接
* 工具：function、custom、namespace（MCP）、tool search、`web_search`
* `prompt_cache_key` 会话缓存（命中部分按缓存价计费，见 [GPT 计费规则](/chat/gpt)）
* `service_tier: "fast"` / `"priority"`（Codex `/fast`），按官方 Fast 价计费
* API Key 模型白名单、余额预扣、结算、渠道重试和请求日志
服务端不保存会话：保持 `disable_response_storage = true`，由客户端发送完整会话历史。非空 `previous_response_id` 返回 `400 invalid_request`，避免出现"看似续接成功、实际丢失上下文"。
## 常见问题
| 现象 | 排查 |
| --------------------------------------- | ---------------------------------------------------------- |
| `401 invalid_api_key` | 确认用的是 LoopToken Key，请求头为 `Authorization: Bearer sk-lt-...` |
| `404 model_not_found` | 使用 `/v1/models` 返回的准确模型名 |
| Codex 请求了 `/v1/chat/completions` | `wire_api` 配错，应为 `responses` |
| `previous_response_id is not supported` | 设置 `disable_response_storage = true`，重启 Codex 并开始新会话 |
| CC Switch 出现 `/v1/v1/...` | Base URL 与自动追加路径重复；普通模式去掉末尾 `/v1`，或改用 Full URL Mode |
| 能聊天但不能改代码 | 所选模型可能没有正确返回 Function tool calls，执行上面的 shell 工具验收 |
# 错误码
Source: https://looptoken.vibelab.me/docs/errors
> 统一错误响应体、错误码总表（HTTP 状态码、触发场景）与重试建议
本页的错误体适用于对话、图像、视频统一协议、Midjourney、音乐、语音、转写接口；各接口特有的 `code` 见其页面的「错误」章节。Kling 原生接口（含 `/v1/videos/avatar` 等旧版路径）和 Seedance 方舟 / 素材库接口沿用官方错误体，见 [Kling 错误](/video/kling#错误)和[方舟接口](/video/seedance-ark)。Claude 的 `/v1/messages` 使用 Anthropic 错误体 `{"type":"error","error":{"type","message"}}`，见 [Claude 错误](/chat/claude#错误)。
请求失败时返回统一 JSON 错误体：
```json
{
"error": {
"message": "human readable message",
"type": "insufficient_credits",
"code": "insufficient_credits",
"request_id": "..."
}
}
```
| 字段 | 说明 |
| --------------- | ----------------------- |
| `message` | 面向人类的描述，仅供调试，不要按内容做逻辑判断 |
| `type` / `code` | 取值始终相同，为下表的 code |
| `request_id` | 本次请求唯一标识，联系支持时请提供 |
## 错误码总表
| code | HTTP | 适用接口 | 触发场景 |
| ---------------------------- | ---- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `invalid_api_key` | 401 | 全部 `/v1/*` | `Authorization` 头缺失/格式错误，或 API Key 无效/已禁用 |
| `invalid_request` | 400 | [Chat](/chat)、[图像生成](/images) | 请求体不合法（JSON 格式错误，或缺失 `model`/`messages` 等必填字段） |
| `invalid_request_error` | 400 | [视频生成](/video) | 请求体不合法（非法 JSON、`callback_url` 非字符串或不满足 https/公网地址要求等） |
| `model_not_allowed` | 403 | [Chat](/chat)、[图像生成](/images) | `model` 不在该 API Key 的白名单内 |
| `quota_exceeded` | 403 | 全部 `/v1/*` 非 GET 请求；[视频生成](/video) | API Key 配额已用尽（`API key quota exceeded (settled usage)`）；或视频生成额度用尽（`video generation quota exceeded`） |
| `ip_not_allowed` | 403 | 全部 `/v1/*` | 客户端 IP 不在该 API Key 的允许列表内，见[鉴权](/authentication) |
| `rate_limit_exceeded` | 429 | 全部 `/v1/*` | 用户或 API Key 请求频率超限 |
| `media_concurrency_exceeded` | 429 | 图像、视频、音乐、语音、转写、Midjourney | 用户或 API Key 的媒体任务并发超限，响应带 `Retry-After: 5` |
| `model_not_found` | 404 | [Chat](/chat)、[图像生成](/images)、[视频生成](/video) | 平台没有该模型 |
| `task_not_found` | 404 | [视频生成](/video) | `task_id` 不存在，或不属于当前账户 |
| `insufficient_credits` | 402 | [Chat](/chat)、[图像生成](/images)、[视频生成](/video) | 账户余额不足以覆盖预扣费用 |
| `upstream_error` | 502 | [Chat](/chat)、[图像生成](/images)、[视频生成](/video) | 上游返回错误或平台重试耗尽；已扣费的场景会退还（见各接口文档） |
| `no_available_channel` | 503 | [Chat](/chat)、[图像生成](/images)、[视频生成](/video) | 该模型当前没有可用渠道 |
| `internal_error` | 500 | 全部 `/v1/*` | 平台内部错误 |
## 重试建议
| 类别 | 做法 |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| 5xx（`upstream_error`、`no_available_channel`、`internal_error`） | 指数退避重试；前两者通常是暂时性的 |
| 429（`rate_limit_exceeded`、`media_concurrency_exceeded`） | 按 `Retry-After`（如有）或指数退避后重试 |
| 4xx | 先按 `message` 修正参数或账户状态再发起，重试不会改变结果（`insufficient_credits` 先充值，`invalid_api_key` 先检查 key） |
# 快速开始
Source: https://looptoken.vibelab.me/docs
> LoopToken 统一 API：一个 Key 调用对话、图像、视频、音乐、语音与转写模型，兼容 OpenAI SDK
LoopToken 用一个 API Key 提供对话、图像、视频、音乐、文字转语音和音频转写能力。对话、图像、语音、转写接口兼容 OpenAI 协议，现有 OpenAI SDK 只需替换 `base_url` 与 `api_key`；视频和音乐生成是异步任务协议（提交 → 轮询）。
| 项 | 值 |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base URL | `https://api.vibelab.me/v1`（例外见下方[接口家族](#接口家族)） |
| 鉴权 | `Authorization: Bearer sk-lt-...` |
| 计费 | 积分制，10 积分 = 1 美元，实时价格见[模型列表](/models) |
| 面向 AI 的文档 | [`/docs/llms.txt`](https://looptoken.vibelab.me/docs/llms.txt)（索引）、[`/docs/llms-full.txt`](https://looptoken.vibelab.me/docs/llms-full.txt)（全文）、每页「复制页面」 |
## 快速开始
### 注册并充值
前往注册页创建账号。充值需联系管理员上账，余额与流水在控制台账单页查看。
### 创建 API Key
在API Key 管理页创建密钥，形如 `sk-lt-...`，创建后可随时查看明文。
### 发起请求
curl
Python
Node.js
```bash
curl https://api.vibelab.me/v1/chat/completions \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [{"role": "user", "content": "你好,介绍一下你自己"}]
}'
```
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.vibelab.me/v1",
api_key="sk-lt-...",
)
resp = client.chat.completions.create(
model="deepseek-v4-flash",
messages=[{"role": "user", "content": "你好,介绍一下你自己"}],
)
print(resp.choices[0].message.content)
```
```ts
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://api.vibelab.me/v1',
apiKey: 'sk-lt-...',
});
const resp = await client.chat.completions.create({
model: 'deepseek-v4-flash',
messages: [{ role: 'user', content: '你好,介绍一下你自己' }],
});
console.log(resp.choices[0].message.content);
```
## 接口家族
不同能力沿用各自上游或行业的原生协议，路径前缀、任务状态和结果字段各不相同。对接前先确认目标模型属于哪一族，再读对应总览页。
| 家族 | 路径前缀 | 同步/异步 | 查询结果 | 终态 | 总览 |
| -------------------- | ---------------------------------------------------------- | -------- | ------------------------------- | ------------------------------------------------ | ------------------------------------ |
| 对话 | `/v1/chat/completions`、`/v1/responses` | 同步 / SSE | - | - | [对话](/chat) |
| Claude（Anthropic 原生） | `/v1/messages`、`/v1/messages/count_tokens` | 同步 / SSE | - | - | [Claude](/chat/claude) |
| 图像 | `/v1/images/generations`、`/v1/images/edits` | 同步 | - | - | [图像](/images) |
| 视频（统一协议） | `/v1/videos/generations` | 异步 | `GET /v1/tasks/{task_id}` | `succeeded` / `failed` | [视频](/video) |
| Kling 原生 | `/text-to-video/*` 等，**无 `/v1`**；旧版能力在 `/v1/videos/*` | 异步 | `GET /tasks` 或各自查询接口 | `succeeded`（旧版 `succeed`）/ `failed` | [Kling](/video/kling) |
| Seedance 方舟原生 | `/api/v3/contents/generations/tasks` | 异步 | `GET .../tasks/{id}` | `succeeded` / `failed` / `expired` / `cancelled` | [方舟](/video/seedance-ark) |
| Seedance 素材库 | `/hub/api/v3/...` | 异步 | `GET .../tasks/{id}` | 同方舟 | [素材库](/video/seedance-native-assets) |
| Midjourney | `/v1/midjourney/*` | 异步 | `GET /v1/midjourney/{task_id}` | `SUCCESS` / `FAILURE` | [Midjourney](/midjourney) |
| 音乐 | `/v1/music/*` | 异步 | `GET /v1/music/tasks/{task_id}` | `completed` / `failed` | [音乐](/audio/suno) |
| 语音、转写 | `/v1/audio/speech`、`/v1/audio/transcriptions` | 同步 | - | - | [语音](/audio/speech) |
所有家族使用同一个 API Key 和同一个域名 `https://api.vibelab.me`；错误体格式以各总览页为准。
## 让 AI 读文档
每个文档页标题下的「复制页面」按钮可把当前页以 Markdown 复制给大模型；下拉菜单支持以 Markdown 查看，或直接在 ChatGPT / Claude 中打开并提问。要让 AI 一次读完全部接口，把 [`llms-full.txt`](https://looptoken.vibelab.me/docs/llms-full.txt) 的地址发给它即可。
## 接口总览
## 账户与排障
# 模型列表
Source: https://looptoken.vibelab.me/docs/models
> 当前可用模型与实时价格
以下列表实时读取平台在售模型与价格(与定价页同源)。模型名即 API 请求中 `model` 字段的取值。
# 音乐生成（Flow Music）
Source: https://looptoken.vibelab.me/docs/audio/flowmusic
> flowmusic（Lyria 3 Pro / Lyria 3.5）：生成音乐、歌词、延伸、片段替换、Cover 改编、词曲分离、音乐视频，异步，用 GET /v1/music/tasks/{task_id} 查询
Flow Music 与 [Suno](/audio/suno) 共用同一套异步任务接口，用请求体中的 `model: "flowmusic"` 区分。每次请求生成一首音乐。所有接口都需要 API Key：`Authorization: Bearer sk-lt-...`，详见[鉴权](/authentication)。
| 项 | 值 |
| ---- | ------------------------------------------------------- |
| 模型 | `flowmusic`（大小写不敏感） |
| 版本 | 默认 Lyria 3 Pro；传 `version: "lyria-3.5"` 使用 Lyria 3.5，同价 |
| 模式 | 异步（提交 → 轮询 [`GET /v1/music/tasks/{task_id}`](#响应)） |
| 计费 | 按操作固定计费，失败自动退款 |
| 媒体保留 | 结果中的音频、视频、分轨文件保留 3 天，请及时转存 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/music/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flowmusic",
"title": "My Song",
"sound_prompt": "upbeat pop music with piano",
"bpm": "120",
"length": 60
}'
```
响应示例：
```json
{
"code": 200,
"data": [
{ "status": "submitted", "task_id": "at_0198f0a0-1111-7777-8888-999999999999" }
]
}
```
`submitted` 只表示任务已受理，用 `task_id` 调用[查询任务](#响应)取结果。
## 模式选择
| 模式 | 入口 | 怎么传参 |
| ---- | ---------------------------------------- | ---------------------------------------- |
| 生成音乐 | `POST /v1/music/generations` | `sound_prompt`、`lyrics` 等，见[请求参数](#请求参数) |
| 其它操作 | `POST /v1/music/generations/{operation}` | 路径后缀选操作，用 `clip_id` 引用源音乐，见[操作列表](#操作列表) |
`*FlowMusic` 路径只属于 flowmusic，省略 `model` 时按路径推断为 `flowmusic`。
## 请求参数
### 生成音乐
平台只校验 JSON 结构，字段取值由上游校验。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | ------- | -- | ----------- | ------------------------------- |
| `model` | string | 是 | - | `flowmusic`（大小写不敏感） |
| `version` | string | 否 | Lyria 3 Pro | `lyria-3.5` 使用 Lyria 3.5 |
| `sound_prompt` | string | 否 | - | 音乐风格或声音描述 |
| `lyrics` | string | 否 | - | 歌词，可先调用 `lyricsFlowMusic` 生成后回填 |
| `title` | string | 否 | - | 标题 |
| `bpm` | string | 否 | - | 每分钟节拍数，必须 ≥ 1 |
| `length` | integer | 否 | - | 生成时长（秒） |
| `seed` | string | 否 | - | 随机种子，用于复现结果 |
### 操作列表
除生成音乐外，其它操作统一为 `POST /v1/music/generations/{operation}`，请求体都需带 `model: "flowmusic"`。价格为积分/次，以[定价页](/pricing)为准。
| `{operation}` | 功能 | 主要参数 | 价格 |
| ------------------------ | ------------------- | ------------------------------------------------------------ | ----- |
| （无） | 生成音乐 | 见上节 | 0.75 |
| `lyricsFlowMusic` | 生成歌词 | `prompt`（≤ 3000 字符） | 0.25 |
| `extendFlowMusic` | 音乐延伸 | `clip_id`、`extend_from_s`、`extend_s`、`instruction`、`version` | 0.75 |
| `replaceFlowMusic` | 片段替换 | `clip_id`、`start_s`、`end_s`、`instruction`、`version` | 0.75 |
| `coverFlowMusic` | Cover 改编 | `clip_id`、`instruction`、`strength`、`version` | 0.75 |
| `stemsFlowMusic` | 词曲分离（返回 zip） | `clip_id` | 0.75 |
| `uploadAudioFlowMusic` | 导入外部音频，换取 `clip_id` | `audio_url`（公网可访问） | 0.125 |
| `downloadAudioFlowMusic` | 下载指定格式音频 | `clip_id`、`format` | 0.25 |
| `videoClipFlowMusic` | 音乐视频渲染 | `clip_id`、`preset`（默认 `simple`） | 0.25 |
延伸、替换、Cover 都可以传 `version: "lyria-3.5"` 使用 Lyria 3.5，价格相同；`title`、`seed` 为可选参数。
### 引用源音乐
延伸、替换、Cover、词曲分离、下载、音乐视频都用 `clip_id` 指定源音乐：取自已成功任务的 `result.music[].clip_id`。导入自己的音频请先调用 `uploadAudioFlowMusic`，完成后从 `result.music[0].clip_id` 取值。
```bash
curl https://api.vibelab.me/v1/music/generations/extendFlowMusic \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flowmusic",
"clip_id": "a41aade4-993e-4d28-b56f-d97e7ef7167c",
"extend_from_s": 30,
"extend_s": 20,
"instruction": "加入更明亮的合成器旋律"
}'
```
只能引用自己账户下已成功任务产出的 `clip_id`，否则返回 `400 invalid_source_reference`。
## 请求示例
最小请求体见[快速开始](#快速开始)（生成音乐）与上节的延伸示例；其它操作把 `{operation}` 换成[操作列表](#操作列表)中的后缀，带上对应参数即可。
## 响应
提交响应见[快速开始](#快速开始)。查询任务：
```json
{
"code": 200,
"data": {
"id": "at_0198f0a0-1111-7777-8888-999999999999",
"status": "completed",
"progress": 100,
"created": 1783413241,
"cost": 0.075,
"credits_cost": 0.75,
"result": {
"music": [
{
"clip_id": "a41aade4-993e-4d28-b56f-d97e7ef7167c",
"title": "My Song",
"duration_seconds": "181.70666667",
"audio_url": "https://...",
"wav_url": "https://..."
}
]
}
}
}
```
| 字段 | 类型 | 说明 |
| --------------------------------- | ------- | ----------------------------------------------------------------------- |
| `data.id` | string | 任务 ID（`at_` 前缀） |
| `data.status` | string | `pending` / `processing` / `completed`（终态）/ `failed`（终态） |
| `data.progress` | integer | 进度 0 到 100，是否完成以 `status` 为准 |
| `data.created` | integer | 创建时间，Unix 秒 |
| `data.credits_cost` / `data.cost` | number | 本次扣费，积分 / 美元（10 积分 = 1 美元），结算后返回 |
| `data.result` | object | 完成后的结果，结构随操作不同（见下） |
| `data.error` | object | 失败时返回：`message`、`type`（`task_failed`）、`code`（`task_failed` 或 `timeout`） |
* 结果结构随操作不同：音乐在 `result.music[]`；歌词在 `result.lyrics[]`；词曲分离返回 `file_url`（zip）；音乐视频返回 `video_url`；下载返回指定格式的 `audio_url`。
* 结果中的媒体地址是限时签名链接，每次查询都会重新签发；文件自任务完成起保留 3 天，过期后对应字段为空字符串。
## 计费
* 提交时按操作价格预扣，任务成功后结算；失败或超时自动退款。
* 实际扣费以终态任务中的 `credits_cost` 和[定价页](/pricing)为准。
## 错误
错误体为 `{"error": {"message": "...", "type": "...", "code": "...", "request_id": "..."}}`（`type` 与 `code` 相同），通用错误码见[错误码](/errors)。本接口常见错误：
| HTTP | code | 触发场景 | 处理 |
| ----- | ---------------------------- | ------------------------------------------ | ------------------------------ |
| `400` | `invalid_request_error` | JSON 不合法、字段类型错误（如 `clip_id` 不是非空字符串） | 按 `message` 修正请求体 |
| `400` | `invalid_source_reference` | `clip_id` 不存在，或不属于当前账户的已成功任务 | 使用自己账户已成功任务产出的 `clip_id` |
| `404` | `not_found` | 操作名不存在，或操作与 `model` 不匹配 | 核对[操作列表](#操作列表)的 `{operation}` |
| `404` | `model_not_found` | `model` 不是 `suno` / `flowmusic`，或该模型没有可售价格 | 核对 `model` |
| `404` | `task_not_found` | 任务不存在或不属于当前账户 | 核对 `task_id` |
| `429` | `media_concurrency_exceeded` | 用户或 API Key 的媒体并发超限（响应带 `Retry-After`） | 稍后重试 |
| `502` | `upstream_error` | 音乐服务暂时不可用 | 指数退避重试，已预扣的费用会退回 |
| `503` | `no_available_channel` | 当前没有可用的音乐生成通道 | 指数退避重试 |
余额不足返回 `402 insufficient_credits`。
## 注意事项
* **用 `clip_id` 引用源音乐** → 只能取自本账户已成功任务的 `result.music[].clip_id`，或 `uploadAudioFlowMusic` 的结果。
* **媒体链接** → 3 天后失效，请及时转存。
# 文字转语音
Source: https://looptoken.vibelab.me/docs/audio/speech
> gpt-4o-mini-tts / tts-1：OpenAI 兼容文字转语音，同步，响应体直接是音频二进制
一次请求直接返回音频二进制内容，适合旁白、播报和语音助手。需要 API Key：`Authorization: Bearer sk-lt-...`，详见[鉴权](/authentication)。
| 项 | 值 |
| -- | ----------------------------------------------------- |
| 模型 | `gpt-4o-mini-tts`（推荐，支持 `instructions` 和扩展音色）、`tts-1` |
| 模式 | 同步，响应体即音频 |
| 计费 | 按输入 Unicode 字符数，价格以[定价页](/pricing)为准 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/audio/speech \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini-tts",
"input": "欢迎使用 LoopToken 文字转语音服务。",
"voice": "coral",
"instructions": "语气热情、亲切，语速稍快",
"response_format": "wav"
}' \
--output speech.wav
```
```python
import os
import requests
response = requests.post(
"https://api.vibelab.me/v1/audio/speech",
headers={"Authorization": f"Bearer {os.environ['LOOPTOKEN_API_KEY']}"},
json={
"model": "gpt-4o-mini-tts",
"input": "欢迎使用 LoopToken 文字转语音服务。",
"voice": "coral",
"instructions": "语气热情、亲切，语速稍快",
"response_format": "wav",
},
)
response.raise_for_status()
with open("speech.wav", "wb") as file:
file.write(response.content)
```
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------------- | ------ | -- | ----- | ------------------------------------------------------------------------------------------------------------------------------- |
| `model` | string | 是 | - | `gpt-4o-mini-tts` 或 `tts-1` |
| `input` | string | 是 | - | 要合成的文字，最多 4096 个 Unicode 字符（按 Unicode 字符统计，不是 UTF-8 字节数） |
| `voice` | string | 是 | - | 两个模型通用：`alloy`、`echo`、`fable`、`onyx`、`nova`、`shimmer`；仅 `gpt-4o-mini-tts`：`ash`、`ballad`、`coral`、`sage`、`verse`、`marin`、`cedar` |
| `instructions` | string | 否 | - | 仅 `gpt-4o-mini-tts`，用自然语言描述语气、情绪、口音或语速风格，最多 4096 个字符；不计入计费字符数。对 `tts-1` 传入会返回参数错误 |
| `response_format` | string | 否 | `wav` | `wav`、`opus`、`aac`、`flac` 或 `pcm` |
| `speed` | number | 否 | `1.0` | 语速，范围 `0.25` 到 `4.0` |
不支持的字段会返回参数错误。
## 响应
成功时返回 HTTP `200` 和音频二进制内容，不返回 JSON。请根据请求格式保存响应：
| `response_format` | 常见 `Content-Type` | 建议扩展名 |
| ----------------- | -------------------------- | ------- |
| `wav` | `audio/wav` | `.wav` |
| `opus` | `audio/opus` | `.opus` |
| `aac` | `audio/aac` | `.aac` |
| `flac` | `audio/flac` | `.flac` |
| `pcm` | `application/octet-stream` | `.pcm` |
## 计费
`gpt-4o-mini-tts` 和 `tts-1` 都按 `input` 的 Unicode 字符数计费（`instructions` 不计费），定价页以每千字符展示。请求开始时按确定的字符数预扣，合成成功后结算；失败时自动退款。实际费率以[定价页](/pricing)为准。
## 错误
错误体为 `{"error": {"message": "...", "type": "...", "code": "...", "request_id": "..."}}`，不会混入音频字节，也不返回内部路由或原始错误。通用错误码见[错误码](/errors)。本接口常见错误：
| HTTP | code | 触发场景 | 处理 |
| ------------- | ---------------------------- | ------------------------------------ | ---------------- |
| `400` / `422` | `invalid_request_error` | JSON、字段、音色、格式、文本长度或语速不合法 | 按 `message` 修正参数 |
| `402` | `insufficient_credits` | 余额不足 | 充值后重试 |
| `404` | `model_not_found` | 模型不存在或当前不可用 | 核对 `model` |
| `429` | `media_concurrency_exceeded` | 用户或 API Key 的媒体并发超限（带 `Retry-After`） | 稍后重试 |
| `502` | `upstream_error` | 音频服务暂时不可用 | 指数退避重试，已预扣费用会退回 |
| `503` | `no_available_channel` | 当前没有可用的音频生成通道 | 指数退避重试 |
# 音乐生成（Suno）
Source: https://looptoken.vibelab.me/docs/audio/suno
> suno（V6 / V6 Wild / V6 Mini）全部音乐操作：生成歌曲、歌词、续写、翻唱、分轨、MIDI、音乐视频等，异步，用 GET /v1/music/tasks/{task_id} 查询
所有 Suno 接口都是异步任务：提交后拿到 `task_id`，再轮询查询接口获取结果。所有接口都需要 API Key：`Authorization: Bearer sk-lt-...`，详见[鉴权](/authentication)。同一套接口也承载 [Flow Music](/audio/flowmusic)（`model: "flowmusic"`）。
| 项 | 值 |
| ---- | -------------------------------------------------- |
| 模型 | `suno`（可省略 `model` 字段） |
| 版本 | `v6`、`v6-wild`、`v6-mini`，或自定义模型 `custom_model_id` |
| 模式 | 异步（提交 → 轮询 [`GET /v1/music/tasks/{task_id}`](#响应)） |
| 轮询间隔 | 首次等待约 3 秒，之后每 5 到 10 秒 |
| 计费 | 按操作固定计费，Max 模式 2 倍；失败自动退款 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/music/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno",
"version": "v6",
"custom": false,
"prompt": "深夜城市 lo-fi 钢琴配雨声"
}'
```
自定义歌词模式：
```bash
curl https://api.vibelab.me/v1/music/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno",
"version": "v6",
"custom": true,
"instrumental": false,
"prompt": "[Verse]\n雨夜霓虹灯下的街道",
"title": "深夜驾驶",
"style": "synthwave, female vocal, cinematic",
"negative_tags": "metal, screaming",
"vocal_gender": "Female",
"style_weight": 0.6,
"weirdness_constraint": 0.3,
"audio_weight": 0.5
}'
```
所有提交接口的响应形状相同（详见[响应](#响应)）：
```json
{
"code": 200,
"data": [
{ "status": "submitted", "task_id": "at_0198f0a0-1111-7777-8888-999999999999" }
]
}
```
`submitted` 只表示任务已受理。不要因为网络超时自动重发收费的 POST 请求；拿到 `task_id` 后用查询接口确认结果。
## 模式选择
| 模式 | 怎么传参 |
| ------- | ---------------------------------------------------------------------------------------- |
| 灵感模式 | `custom: false`，`prompt` 为歌曲描述（≤ 3000 字符） |
| 自定义歌词模式 | `custom: true`，`prompt` 为歌词（≤ 5000 字符），可加 `title`、`style`、`negative_tags`、`persona_id` 等 |
| 自定义模型 | 传 `custom_model_id`，省略 `version` 与 `persona_id` |
| 其它操作 | `POST /v1/music/generations/{operation}`，见[操作列表](#操作列表) |
## 请求参数
### 生成音乐
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------------------------------------------------- | ------- | ----------------------- | ------- | ----------------------------------------------------------------------------- |
| `model` | string | 否 | `suno` | 可省略；写则只能是 `suno`（或 `flowmusic`，见 [Flow Music](/audio/flowmusic)） |
| `version` | string | 与 `custom_model_id` 二选一 | - | `v6` / `v6-wild` / `v6-mini` |
| `custom_model_id` | string | 与 `version` 二选一 | - | 创建自定义模型（`createModel`）返回的 `model_id`；与 `version`、`persona_id` 互斥 |
| `custom` | boolean | 否 | - | `false` 灵感模式（`prompt` 为歌曲描述，最多 3000 字符）；`true` 自定义模式（`prompt` 为歌词，最多 5000 字符） |
| `instrumental` | boolean | 否 | - | 纯音乐；自定义纯音乐可省略 `prompt` |
| `prompt` | string | 视模式 | - | 描述或歌词，见 `custom` |
| `title` | string | 否 | - | 标题，最多 80 字符，仅自定义模式 |
| `style` | string | 否 | - | 风格标签，最多 1000 字符，仅自定义模式 |
| `negative_tags` | string | 否 | - | 排除的风格，仅自定义模式 |
| `auto_lyrics` | boolean | 否 | - | 自动生成歌词，仅自定义模式 |
| `persona_id` | string | 否 | - | 用 Persona（`persona`）复用歌手音色，仅自定义模式 |
| `vocal_gender` | string | 否 | - | `Male` / `Female` |
| `style_weight` / `weirdness_constraint` / `audio_weight` | number | 否 | - | `0` 到 `1`，`0` 是有效值 |
| `variety` | string | 否 | - | 风格变化程度：`off` / `normal` / `high` / `extra` / `max` |
| `max_mode` | boolean | 否 | `false` | Max 模式，需 `custom=true`；按 2 倍计费 |
| `audio_format` | string | 否 | - | `mp3` / `m4a` / `wav` |
| `duration` | integer | 否 | - | 目标时长 `10`–`360` 秒，成品时长不保证完全一致 |
除 `model`、`max_mode`、`task_id`、`task_ids`、`persona_id`、`custom_model_id` 的类型检查外，其余字段由上游校验。
`custom: true` 是自定义歌词模式，`custom_model_id` 是使用已训练的自定义模型，两者不是同一个概念。`variety: "max"` 与 Max 模式相互独立，不会触发 Max 计费。
### 操作列表
除生成音乐外，其它操作统一为 `POST /v1/music/generations/{operation}`。下表价格为积分/次，以[定价页](/pricing)为准。
| `{operation}` | 功能 | 主要参数 | 价格 | Max |
| ----------------- | ---------------------------------------------- | --------------------------------------------------------- | ----- | ---- |
| （无） | 生成音乐 | 见上节 | 0.625 | 1.25 |
| `lyrics` | 生成歌词 | `prompt`、`lyrics_model` | 0.1 | |
| `inspo` | 灵感生成：参考音频生成新歌 | `audio_urls`、`version`、`tags`、`prompt` | 0.85 | 1.7 |
| `sounds` | 音效生成 | `prompt`、`version`、`type`、`bpm`、`key` | 0.12 | |
| `upsampleTags` | 风格标签增强 | `tags` | 0.05 | |
| `uploadTask` | 导入公网音频，产出可被引用的源任务 | `audioFilePath`（只接收这一个字段） | 0.05 | |
| `uploadCover` | 上传音频并翻唱 | `audio_url`、`version`、`custom`、`tags`、`duration_s` | 0.625 | 1.25 |
| `uploadExtend` | 上传音频并延伸 | `audio_url`、`continue_at`、`version`、`prompt`、`tags` | 0.625 | 1.25 |
| `createModel` | 创建自定义模型 | `name`、`audio_urls` | 12 | |
| `extend` | 续写延长 | `task_id`、`audio_index`、`continue_at`、`version`、`prompt` | 0.625 | 1.25 |
| `coverSong` | 风格翻唱 | `task_id`、`audio_index`、`version`、`tags` | 0.625 | 1.25 |
| `remaster` | 母带优化 | `task_id`、`audio_index`、`variation_category` | 0.625 | |
| `stems` | 分轨提取 | `task_id`、`audio_index`、`stem_type` | 1.25 | |
| `stemsAll` | 全量分轨 | `task_id`、`audio_index` | 3 | |
| `addVocals` | 添加人声 | `task_id`、`audio_index`、`version`、`prompt` | 0.625 | 1.25 |
| `addInstrumental` | 添加伴奏 | `task_id`、`audio_index`、`version`、`tags` | 0.625 | 1.25 |
| `addStem` | 添加音轨 | `task_id`、`audio_index`、`version`、`gpt_description` | 0.625 | 1.25 |
| `vox` | 提取人声（已弃用） | `task_id`、`audio_index`、`vocal_start_s`、`vocal_end_s` | 0.05 | |
| `createVoice` | 创建音色 | `audio_url` | 0.2 | |
| `persona` | 创建歌手 Persona | `task_id`、`audio_index`、`name`、`styles` | 0.05 | |
| `replaceMusic` | 段落替换 | `task_id`、`audio_index`、`start_s`、`end_s`、`infill_lyrics` | 0.625 | 1.25 |
| `removeSection` | 删除片段 | `task_id`、`audio_index`、`start_s`、`end_s` | 0.1 | |
| `crop` | 裁剪音频 | `task_id`、`audio_index`、`start_s`、`end_s` | 0.1 | |
| `fadeIn` | 淡入 | `task_id`、`audio_index`、`duration_s` | 0.1 | |
| `fadeOut` | 淡出 | `task_id`、`audio_index`、`duration_s` | 0.1 | |
| `adjustSpeed` | 调整速度 | `task_id`、`audio_index`、`speed`、`keep_pitch` | 0.3 | |
| `concat` | 完整歌曲合成 / 拼接 | `task_id`、`audio_index` | 0.05 | |
| `mashup` | 生成混搭 | `task_ids`、`audio_indexes`、`version`、`prompt` | 0.625 | 1.25 |
| `sample` | 样本转歌曲 | `task_id`、`audio_index`、`start_s`、`end_s`、`prompt` | 0.625 | 1.25 |
| `midi` | 生成 MIDI | `task_id`、`audio_index` | 0.625 | |
| `alignedLyrics` | 歌词时间轴 | `task_id`、`audio_index` | 0.01 | |
| `bpm` | BPM 分析 | `task_id`、`audio_index` | 0.01 | |
| `generateMp4` | 生成音乐视频 | `task_id`、`audio_index` | 0.05 | |
| `download` | 下载为 MP3 / M4A / WAV | `task_id`、`audio_index`、`formats` | 0.02 | |
| `wav` | 下载 WAV（已弃用，等同 `download` + `formats: ["wav"]`） | `task_id`、`audio_index` | 0.02 | |
支持版本选择的编辑操作省略 `version` 时默认使用 `v6`。操作接口里风格字段叫 `tags`、描述字段叫 `gpt_description`、怪异度叫 `weirdness`（生成音乐接口分别是 `style`、`prompt`、`weirdness_constraint`）。不支持某字段的操作请完全省略该字段，不要统一发送 `max_mode: false`。
### 引用源音轨
基于已有作品的操作用 `task_id` + `audio_index` 指定源音轨：
* `task_id`：产出源音轨的本平台任务 ID（`at_` 开头）。上传自己的音频请先调用 `uploadTask`，用它的 `task_id` 作源，`audio_index` 为 `1`。
* `audio_index`：源任务结果 `result.music[]` 中的原始位置，从 `1` 开始，默认 `1`。按实际返回数量处理，不要假设固定为 2 首。
```bash
curl https://api.vibelab.me/v1/music/generations/extend \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task_id": "at_0198f0a0-1111-7777-8888-999999999999",
"audio_index": 1,
"continue_at": 120,
"version": "v6",
"prompt": "[Outro]\n下一段旅途，我们一起走"
}'
```
只能引用自己账户下已成功的任务。不支持 `audio_id`、`music_id` 等旧式 ID 字段，传入会返回 `400`。`mashup` 的多个源任务若无法组合，返回 `400 invalid_source_reference`。
### 自定义模型与 Persona
* `createModel` 完成后读取 `result.model_id`，在支持的操作里作为 `custom_model_id` 使用，同时省略 `version` 和 `persona_id`。创建可能需要数分钟，最长约 20 分钟；创建与后续每次生成分别计费。
* `persona` 完成后读取 `result.persona_id`，在自定义模式下作为 `persona_id` 使用。
`custom_model_id` 与 `persona_id` 只能在创建它们的账户中使用。
## 请求示例
### 完整轮询示例
```python
import os
import time
import requests
BASE_URL = "https://api.vibelab.me"
headers = {"Authorization": f"Bearer {os.environ['LOOPTOKEN_API_KEY']}"}
response = requests.post(
f"{BASE_URL}/v1/music/generations",
headers=headers,
json={"model": "suno", "version": "v6", "custom": False, "prompt": "明亮的电子流行配乐，适合产品发布视频"},
)
response.raise_for_status()
task_id = response.json()["data"][0]["task_id"]
time.sleep(3)
while True:
task = requests.get(f"{BASE_URL}/v1/music/tasks/{task_id}", headers=headers).json()["data"]
if task["status"] in ("completed", "failed"):
break
time.sleep(6)
if task["status"] == "failed":
raise RuntimeError(task["error"])
for track in task["result"]["music"]:
print(track["title"], track["audio_url"])
```
## 响应
提交响应见[快速开始](#快速开始)。查询任务：
```bash
curl https://api.vibelab.me/v1/music/tasks/at_0198f0a0-1111-7777-8888-999999999999 \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
```json
{
"code": 200,
"data": {
"id": "at_0198f0a0-1111-7777-8888-999999999999",
"status": "completed",
"progress": 100,
"created": 1789041600,
"cost": 0.0625,
"credits_cost": 0.625,
"result": {
"music": [
{
"audio_id": "example-track-id",
"title": "沿着灯光",
"lyrics": "[Verse]\n晚风吹过熟悉街道",
"tags": "pop, acoustic",
"duration": 119.8,
"audio_url": "https://example.com/result.mp3",
"image_url": "https://example.com/cover.jpg"
}
]
}
}
}
```
| 字段 | 类型 | 说明 |
| --------------------------------- | ------- | ----------------------------------------------------------------------- |
| `data.id` | string | 任务 ID（`at_` 前缀） |
| `data.status` | string | `pending` / `processing` / `completed`（终态）/ `failed`（终态） |
| `data.progress` | integer | 进度 0 到 100，是否完成以 `status` 为准 |
| `data.created` | integer | 创建时间，Unix 秒 |
| `data.credits_cost` / `data.cost` | number | 本次扣费，积分 / 美元（10 积分 = 1 美元），结算后返回 |
| `data.result` | object | 完成后的结果，结构随操作不同：音乐类在 `result.music[]`，歌词、MIDI、分轨、Persona、自定义模型等各有自己的结构 |
| `data.error` | object | 失败时返回：`message`、`type`（`task_failed`）、`code`（`task_failed` 或 `timeout`） |
* `duration` 是实际时长，允许小数；权重返回值 `0` 是有效值。
* `audio_url` 不保证使用 `.mp3` 后缀，请按返回的实际 URL 播放或下载，并及时转存到自己的存储。
* 结果媒体由平台转存，文件自任务完成起保留 3 天，请及时转存。
* 当前没有取消已提交任务的接口。
## 计费
* 提交时按操作价格预扣，任务成功后结算；失败或超时自动退款。
* Max 模式（`max_mode: true`）按普通价格的 2 倍计费，仅上表中有 Max 价格的操作支持。
* 一次任务返回多首歌曲时仍按一次任务计费。
* 实际扣费以终态任务中的 `credits_cost` 和[定价页](/pricing)为准。
## 错误
错误体为 `{"error": {"message": "...", "type": "...", "code": "...", "request_id": "..."}}`（`type` 与 `code` 相同），通用错误码见[错误码](/errors)。本接口常见错误：
| HTTP | code | 触发场景 | 处理 |
| ----- | ---------------------------- | ------------------------------------------------------------ | ------------------------------------------------ |
| `400` | `invalid_request_error` | JSON 不合法、字段类型错误；传入 `audio_id`、`music_id`、`clip_id` 等旧式 ID 字段 | 按 `message` 修正；引用源音轨改用 `task_id` + `audio_index` |
| `400` | `invalid_source_reference` | 源任务、`persona_id` 或 `custom_model_id` 不存在、未完成、不属于当前账户，或不能组合使用 | 使用自己账户已成功任务产出的引用 |
| `404` | `not_found` | 操作名不存在 | 核对[操作列表](#操作列表) |
| `404` | `model_not_found` | `model` 不是 `suno` / `flowmusic`，或该模型没有可售价格 | 核对 `model` |
| `404` | `task_not_found` | 任务不存在或不属于当前账户 | 核对 `task_id` |
| `429` | `media_concurrency_exceeded` | 用户或 API Key 的媒体并发超限（响应带 `Retry-After`） | 稍后重试 |
| `502` | `upstream_error` | 音乐服务暂时不可用 | 指数退避重试，已预扣的费用会退回 |
| `503` | `no_available_channel` | 当前没有可用的音乐生成通道 | 指数退避重试 |
余额不足返回 `402 insufficient_credits`。
## 注意事项
* **网络超时** → 不要自动重发收费的 POST，先用 `task_id` 查询确认。
* **`custom_model_id`、`persona_id`** → 只能在创建它们的账户中使用。
* **`audio_url`** → 不保证 `.mp3` 后缀，按返回的实际 URL 处理。
# 音频转写
Source: https://looptoken.vibelab.me/docs/audio/transcriptions
> whisper-1：OpenAI 兼容音频转写，同步，multipart 上传，返回文本、时间戳或字幕
接收本地音频文件，同步返回识别文本、详细时间戳或字幕，适合会议记录、采访整理、字幕生成和语音输入。
| 项 | 值 |
| -- | ---------------------------------- |
| 模型 | `whisper-1` |
| 模式 | 同步，multipart/form-data 上传 |
| 计费 | 按音频时长，不足一秒按一秒，价格以[定价页](/pricing)为准 |
请求头：
```http
Authorization: Bearer sk-lt-...
Content-Type: multipart/form-data
```
## 快速开始
```bash
curl https://api.vibelab.me/v1/audio/transcriptions \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-F "file=@meeting.mp3" \
-F "model=whisper-1" \
-F "language=zh" \
-F "response_format=json"
```
```json
{
"text": "这是一段测试音频的转写文本。"
}
```
生成 SRT 字幕：
```bash
curl https://api.vibelab.me/v1/audio/transcriptions \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-F "file=@interview.m4a" \
-F "model=whisper-1" \
-F "language=zh" \
-F "response_format=srt" \
--output interview.srt
```
Python：
```python
import os
import requests
with open("meeting.mp3", "rb") as audio:
response = requests.post(
"https://api.vibelab.me/v1/audio/transcriptions",
headers={"Authorization": f"Bearer {os.environ['LOOPTOKEN_API_KEY']}"},
files={"file": ("meeting.mp3", audio, "audio/mpeg")},
data={
"model": "whisper-1",
"language": "zh",
"response_format": "json",
},
timeout=300,
)
response.raise_for_status()
print(response.json()["text"])
```
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------------- | ------ | -- | ------ | ------------------------------------------------------------------------ |
| `file` | file | 是 | - | 音频文件，只能上传一个，最大 25 MB；扩展名为 `mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm` |
| `model` | string | 是 | - | 当前为 `whisper-1` |
| `language` | string | 否 | - | ISO-639-1 两字母语言代码，如中文 `zh`、英文 `en`、日文 `ja`、韩文 `ko`；显式传入可以减少语言检测歧义并提高处理速度 |
| `prompt` | string | 否 | - | 补充专有名词、上下文或转写风格，处理上限为 224 tokens |
| `response_format` | string | 否 | `json` | `json`、`text`、`srt`、`verbose_json` 或 `vtt` |
| `temperature` | number | 否 | `0` | 采样温度，范围 `0` 到 `1` |
不支持的字段、重复字段、重复文件、空文件、无效语言代码或超出范围的温度会直接返回参数错误。
## 响应
`response_format=json` 返回 HTTP `200` 和精简 JSON（示例见快速开始）。其他格式：
| 格式 | `Content-Type` | 内容 |
| -------------- | ------------------------------------- | ----------------------- |
| `text` | `text/plain; charset=utf-8` | 只包含完整转写文本 |
| `srt` | `application/x-subrip; charset=utf-8` | 带时间范围的 SRT 字幕 |
| `vtt` | `text/vtt; charset=utf-8` | 带 `WEBVTT` 头的 WebVTT 字幕 |
| `verbose_json` | JSON | 转写语言、音频时长和分段时间戳 |
`verbose_json` 示例：
```json
{
"task": "transcribe",
"language": "zh",
"duration": 2.4,
"text": "欢迎使用 LoopToken。",
"segments": [
{
"id": 0,
"start": 0,
"end": 2.4,
"text": "欢迎使用 LoopToken。"
}
]
}
```
响应只包含公开协议字段，不会返回内部路由、原始服务错误或底层实现信息。
## 计费
`whisper-1` 按音频时长计费，不足一秒按一秒计算。
* 请求开始时预扣一分钟额度；识别完成后根据返回的实际音频时长补足或退回差额。
* 余额不足以完成最终结算时，接口返回 `402` 且不会返回转写内容。
* 实际费率以[定价页](/pricing)为准。
## 错误
错误体为 `{"error": {"message": "...", "type": "...", "code": "...", "request_id": "..."}}`，不会混入音频或字幕内容。通用错误码见[错误码](/errors)。示例：
```json
{
"error": {
"message": "file must not exceed 25 MB",
"type": "invalid_request_error",
"code": "invalid_request_error",
"request_id": "019c2a00-1111-7777-8888-999999999999"
}
}
```
本接口常见错误：
| HTTP | code | 触发场景 | 处理 |
| ------------- | ---------------------------- | ------------------------------------ | --------------------- |
| `400` / `422` | `invalid_request_error` | multipart、字段、文件、格式或音频内容不合法 | 按 `message` 修正，不要自动重试 |
| `402` | `insufficient_credits` | 余额不足以预扣或结算 | 充值后重试 |
| `404` | `model_not_found` | 模型不存在或当前不可用 | 核对 `model` |
| `413` | `invalid_request_error` | 请求或文件超过 25 MB 限制 | 压缩或切分音频 |
| `429` | `media_concurrency_exceeded` | 用户或 API Key 的媒体并发超限（带 `Retry-After`） | 稍后重试 |
| `502` | `upstream_error` | 音频服务暂时不可用或返回无效结果 | 指数退避重试 |
| `503` | `no_available_channel` | 当前没有可用的音频转写通道 | 指数退避重试 |
## 注意事项
使用 cURL 或 SDK 时让工具自动生成 multipart boundary，不要手工固定 `Content-Type` 的 boundary。
* 所有失败请求都会释放未结算的预扣额度。
* `502` 和 `503` → 使用指数退避重试；参数错误 → 不要自动重试。
# Claude 系列
Source: https://looptoken.vibelab.me/docs/chat/claude
> Anthropic Claude（claude-fable-5-1 / claude-opus-5-5 / claude-sonnet-5-5 / claude-haiku-5-5），原生 Anthropic Messages API（POST /v1/messages），同步或 SSE 流式，按输入/输出/缓存读取/缓存写入五项计费
Claude 系列走 **Anthropic 原生 Messages API**：请求体、响应体、SSE 事件、请求头与 Anthropic 官方完全一致，平台原样透传，可直接使用 Anthropic 官方 SDK 和 [Claude Code](/claude-code)。
| 项 | 值 |
| -- | ------------------------------------------------------------ |
| 模型 | 见下表（实际可用以[模型列表](/models)为准） |
| 模式 | 同步；`stream: true` 时为 SSE 流式 |
| 计费 | 按 token，输入 / 输出 / 缓存读取 / 缓存写入（5m）/ 缓存写入（1h）五项分别计价，见[计费](#计费) |
| 模型 | 上下文 | 最大输出 | 说明 |
| ------------------- | --- | ---- | ------------------------------- |
| `claude-fable-5-1` | 1M | 128K | 能力最强，适合最高难度推理与长时程 Agent 任务；思考常开 |
| `claude-opus-5-5` | 1M | 128K | Opus 系列最新版，长时程编程与知识工作；思考常开 |
| `claude-sonnet-5-5` | 1M | 128K | 速度与能力兼顾，日常编程、Agent 与企业场景 |
| `claude-haiku-5-5` | 1M | 128K | 最快最经济；输入超过 100K 按长上下文价计费 |
Claude 只能通过
`/v1/messages`
调用。用
`/v1/chat/completions`
或
`/v1/responses`
请求
`claude-*`
模型会返回
`400`
：协议转换会丢失 thinking 签名，缓存写入也无法按实际档位计费。
## 快速开始
curl
Python
Node.js
```bash
curl https://api.vibelab.me/v1/messages \
-H "x-api-key: $LOOPTOKEN_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "用一句话介绍量子计算"}]
}'
```
```python
import anthropic
client = anthropic.Anthropic(
base_url="https://api.vibelab.me", # 不带 /v1，SDK 会自己拼 /v1/messages
api_key="sk-lt-...",
)
msg = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "用一句话介绍量子计算"}],
)
print(msg.content[0].text)
print(msg.usage)
```
```ts
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
baseURL: 'https://api.vibelab.me', // 不带 /v1
apiKey: 'sk-lt-...',
});
const msg = await client.messages.create({
model: 'claude-sonnet-5-5',
max_tokens: 1024,
messages: [{ role: 'user', content: '用一句话介绍量子计算' }],
});
console.log(msg.content);
console.log(msg.usage);
```
```json title="响应"
{
"id": "msg_011CgY7k2HkKZaASX2XaT26Y",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-5-5",
"content": [{"type": "text", "text": "量子计算是利用量子叠加与纠缠进行信息处理的计算范式。"}],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 18,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0},
"output_tokens": 32
}
}
```
## 鉴权与请求头
| 请求头 | 必填 | 说明 |
| ------------------- | --- | -------------------------------------------------------------------------------- |
| `x-api-key` | 二选一 | LoopToken Key（`sk-lt-...`），Anthropic SDK 与 Claude Code 配 `ANTHROPIC_API_KEY` 时使用 |
| `Authorization` | 二选一 | `Bearer sk-lt-...`，Claude Code 配 `ANTHROPIC_AUTH_TOKEN` 时使用；两者都带时以本头为准 |
| `anthropic-version` | 否 | 原样转发，缺省按 `2023-06-01` |
| `anthropic-beta` | 否 | 原样转发，用于启用 Anthropic beta 特性（如 `interleaved-thinking-2025-05-14`） |
| `content-type` | 是 | `application/json` |
URL 上的查询参数（如 Claude Code 发送的 `?beta=true`）也原样转发。不要填 Anthropic 官方的 `sk-ant-` 密钥。
## 请求参数
请求体与 Anthropic 官方 Messages API 一致，平台**不改写任何字段**，只读取下列字段用于路由和预扣：
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------------------------- | ------------ | -- | ------- | ----------------------------------------------------------------------------------------------------- |
| `model` | string | 是 | - | 上表中的模型名 |
| `max_tokens` | int | 是 | - | 最大输出 token；同时决定[预扣](#计费)金额 |
| `messages` | array | 是 | - | 对话消息，`content` 支持字符串或内容块数组（`text` / `image` / `document` / `tool_use` / `tool_result` / `thinking` 等） |
| `stream` | bool | 否 | `false` | `true` 时返回 SSE 流 |
| `system` | string/array | 否 | - | 系统提示词，数组形式可在块上加 `cache_control` |
| `thinking` | object | 否 | 见下 | `{"type":"adaptive"}`；思考深度用 `output_config.effort` 控制 |
| `output_config.effort` | string | 否 | 依模型 | `low` / `medium` / `high` / `xhigh` / `max` |
| `tools` / `tool_choice` | - | 否 | - | 工具调用，见[工具调用](#工具调用) |
| `cache_control` | object | 否 | - | `{"type":"ephemeral"}`（5 分钟）或 `{"type":"ephemeral","ttl":"1h"}`（1 小时），可加在块上或顶层 |
| `stop_sequences` / `metadata` | - | 否 | - | 与官方一致 |
各模型的官方限制同样生效（违反时由上游返回 `400 invalid_request_error`，平台原样透给你）：
* **`claude-fable-5-1` / `claude-opus-5-5`** → 思考不能关闭，`thinking: {"type":"disabled"}` 与 `{"type":"enabled","budget_tokens":N}` 均返回 400，用 `output_config.effort` 调节深度。
* **`claude-sonnet-5-5`** → `{"type":"disabled"}` 返回 400；要关闭思考，发送 `{"type":"between_tools"}`（仅在 effort 为 `high` 及以下时可用）。
* **`claude-fable-5-1` / `claude-opus-5-5` / `claude-sonnet-5-5`** → `tool_choice` 为 `any` 或 `{"type":"tool"}` 时返回 400，请用 `auto` 并在提示词中点名工具。
* **全部模型** → 不支持 assistant 预填（最后一条为 assistant 消息）。
## 请求示例
### 流式
```bash
curl https://api.vibelab.me/v1/messages \
-H "x-api-key: $LOOPTOKEN_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"stream": true,
"messages": [{"role": "user", "content": "写一首关于秋天的短诗"}]
}'
```
SSE 事件与官方一致，按 `message_start` → `content_block_start` / `content_block_delta` / `content_block_stop` → `message_delta` → `message_stop` 的顺序到达，中间可能有 `ping`。平台逐事件原样转发，thinking 签名、`tool_use` 增量都不做改动。
```text title="SSE 片段"
event: message_start
data: {"type":"message_start","message":{"id":"msg_011C...","model":"claude-opus-5-5","usage":{"input_tokens":21,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":1}}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"text_delta","text":"枫叶"}}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":86}}
event: message_stop
data: {"type":"message_stop"}
```
### Prompt 缓存
长系统提示词、工具定义、长文档放在前面并打上 `cache_control`，后续请求命中缓存后按缓存读取价计费：
```json
{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"system": [
{"type": "text", "text": "<很长的系统提示词或文档>", "cache_control": {"type": "ephemeral"}}
],
"messages": [{"role": "user", "content": "根据文档回答：……"}]
}
```
第一次请求：`usage.cache_creation_input_tokens` 记录写入量；5 分钟内（`ttl: "1h"` 时为 1 小时）的后续请求：`usage.cache_read_input_tokens` 记录命中量。前缀里任何一个字节变化都会导致缓存失效。
### 工具调用
```json
{
"model": "claude-sonnet-5-5",
"max_tokens": 2048,
"tools": [{
"name": "get_weather",
"description": "查询城市天气",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"]
}
}],
"messages": [{"role": "user", "content": "巴黎今天天气怎么样？"}]
}
```
响应 `stop_reason` 为 `tool_use` 时，执行工具后把**整个** assistant `content`（包括 `thinking` 块）原样追加到历史，再追加一条 `user` 消息，在其中放入 `tool_result` 块。thinking 块被改动或删掉会导致后续请求报错。
### 统计 token
```bash
curl https://api.vibelab.me/v1/messages/count_tokens \
-H "x-api-key: $LOOPTOKEN_API_KEY" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-5-5", "messages": [{"role": "user", "content": "hello"}]}'
```
```json title="响应"
{"input_tokens": 2}
```
`count_tokens` 由平台**本地估算**，不调用上游、不计费，数值是近似值（不计入图片等 base64 媒体）；实际计费以 `/v1/messages` 返回的 `usage` 为准。
## 响应
与 Anthropic 官方 `Message` 对象一致。计费相关的 `usage` 字段：
| 字段 | 类型 | 说明 |
| ------------------------------------------------ | --- | ------------------------- |
| `usage.input_tokens` | int | 普通输入 token，**不含**缓存部分 |
| `usage.cache_read_input_tokens` | int | 命中缓存的输入 token |
| `usage.cache_creation_input_tokens` | int | 写入缓存的输入 token（5m + 1h 之和） |
| `usage.cache_creation.ephemeral_5m_input_tokens` | int | 其中按 5 分钟 TTL 写入的部分 |
| `usage.cache_creation.ephemeral_1h_input_tokens` | int | 其中按 1 小时 TTL 写入的部分 |
| `usage.output_tokens` | int | 输出 token，含思考 token |
总输入 = `input_tokens` + `cache_read_input_tokens` + `cache_creation_input_tokens`。控制台用量记录里的"输入 token"按总输入显示。
## 计费
按上游返回的 `usage` 五项分别计价：
```text
费用 = input_tokens × 输入价
+ cache_read_input_tokens × 缓存读取价
+ ephemeral_5m_input_tokens × 缓存写入（5m）价
+ ephemeral_1h_input_tokens × 缓存写入（1h）价
+ output_tokens × 输出价
```
单价（美元 / 百万 token，与 Anthropic 官方价一致；10 积分 = 1 美元）：
| 模型 | 档位 | 输入 | 输出 | 缓存读取 | 缓存写入（5m） | 缓存写入（1h） |
| ------------------- | ---------- | ----- | ----- | ----- | -------- | -------- |
| `claude-fable-5-1` | 全部 | $10 | $50 | $0.25 | $12.5 | $20 |
| `claude-opus-5-5` | 全部 | $4 | $20 | $0.20 | $5 | $8 |
| `claude-sonnet-5-5` | 全部 | $2 | $10 | $0.20 | $2.5 | $4 |
| `claude-haiku-5-5` | 总输入 ≤ 100K | $0.10 | $0.50 | $0.01 | $0.125 | $0.20 |
| `claude-haiku-5-5` | 总输入 > 100K | $0.50 | $2.50 | $0.05 | $0.625 | $1.00 |
价格以[定价页](/pricing)为准。
* **预扣** → 请求进入时按估算输入 + `max_tokens`（不超过模型最大输出）的输出价冻结积分，余额不足返回 `402`。`max_tokens` 越大冻结越多，结算后多退少补。
* **结算** → 按上游 `usage` 实扣；上游没有返回 `usage` 时按输入、输出文本估算。
* **长上下文（`claude-haiku-5-5`）** → 按**实际**总输入（含缓存读写）判断，超过 100K 时整个请求的五项都按长上下文价计费。
* **失败** → 上游报错或未产生输出时全额退还预扣。流式已开始输出后中断，按已产生的用量结算。
* **`count_tokens`** → 不计费。
## 错误
本接口的错误体使用 Anthropic 格式，Anthropic SDK 能直接识别：
```json
{
"type": "error",
"error": {"type": "invalid_request_error", "message": "prompt is too long: 1000001 tokens > 1000000 maximum"},
"request_id": "01a18c01-59e8-77df-83a6-cc66e28b5272"
}
```
| HTTP | `error.type` | 触发场景 | 处理 |
| --------- | ----------------------- | ------------------------------------------------------------------------------ | -------------------------------- |
| 400 | `invalid_request_error` | 请求体不合法、违反模型限制、上下文超长（`prompt is too long`），或通过 `/v1/chat/completions` 调用 Claude | 按 `message` 修改请求；超长时压缩上下文 |
| 401 | `authentication_error` | 缺少 Key、Key 无效或已禁用 | 检查 `x-api-key` / `Authorization` |
| 402 | `billing_error` | 余额不足以支付预扣 | 充值或调小 `max_tokens` |
| 403 | `permission_error` | Key 的模型白名单、IP 白名单或配额不允许 | 调整 Key 设置 |
| 404 | `not_found_error` | 模型不存在或未上架 | 使用[模型列表](/models)中的模型名 |
| 429 | `rate_limit_error` | 触发 Key 或账户的 RPM 限制 | 退避后重试 |
| 502 / 503 | `api_error` | 上游全部失败或暂无可用渠道 | 退避后重试 |
| 504 | `timeout_error` | 非流式请求等待上游超时 | 改用 `stream: true` |
通用说明见[错误码](/errors)。
## 注意事项
* **Base URL** → Anthropic SDK 与 Claude Code 填 `https://api.vibelab.me`（不带 `/v1`）。
* **Claude Code** → 配置方法见 [Claude Code 接入](/claude-code)。
* **长输出** → `max_tokens` 较大或开启思考时用 `stream: true`，避免非流式超时。
* **多轮对话** → 历史中的 `thinking` 块必须原样回传，不要删改。
* **缓存** → 缓存按模型隔离；切换模型、改动系统提示词或工具定义都会导致缓存失效，重新写入。
# DeepSeek 系列
Source: https://looptoken.vibelab.me/docs/chat/deepseek
> DeepSeek V4 系列通用模型，OpenAI 兼容，同步或 SSE 流式
响应中如出现推理内容 `reasoning_content`，不要把该字段回传到下一轮 `messages`；只回传最终 `content` 和工具调用消息。
DeepSeek 官方 API 与 OpenAI 格式兼容，通用字段见[接口说明](/chat)。
| 项 | 值 |
| -- | -------------------------------------- |
| 模型 | 见下表 |
| 模式 | 同步或 SSE 流式 |
| 计费 | 按 token，输入与输出分别计价，价格以[定价页](/pricing)为准 |
| 模型 | 类型 | 上下文 | 最大输出 |
| --------------------- | -- | --------: | ------: |
| `deepseek-v4.1-flash` | 通用 | 1,000,000 | 384,000 |
| `deepseek-v4-flash` | 通用 | 1,000,000 | 128,000 |
| `deepseek-v4-pro` | 通用 | 1,000,000 | 128,000 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/chat/completions \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [{"role": "user", "content": "用一句话介绍你自己"}],
"max_tokens": 1024
}'
```
```json title="响应"
{
"id": "chatcmpl_01H...",
"object": "chat.completion",
"created": 1783819200,
"model": "deepseek-v4-flash",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "我是 DeepSeek 开发的 AI 助手……"
},
"finish_reason": "stop"
}],
"usage": {"prompt_tokens": 12, "completion_tokens": 40, "total_tokens": 52}
}
```
## 请求参数
`messages[].role` 为 `system`、`user`、`assistant` 或 `tool`；`messages[].content` 为字符串。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------- | ------------- | -- | ----------------- | ------------------ |
| `model` | string | 是 | - | 上表模型之一 |
| `messages` | array | 是 | - | 对话消息列表 |
| `stream` | boolean | 否 | `false` | 是否 SSE 流式输出 |
| `max_tokens` | integer | 否 | 模型默认 | 最大输出 Token 数 |
| `temperature` | number | 否 | `1` | 采样温度，范围 `[0, 2)` |
| `top_p` | number | 否 | `1` | 核采样阈值，范围 `(0, 1]` |
| `frequency_penalty` | number | 否 | `0` | 频率惩罚，范围 `[-2, 2]` |
| `presence_penalty` | number | 否 | `0` | 存在惩罚，范围 `[-2, 2]` |
| `stop` | string/array | 否 | - | 停止序列 |
| `tools` | array | 否 | - | 函数工具定义 |
| `tool_choice` | string/object | 否 | `auto` | 工具选择策略 |
| `response_format` | object | 否 | `{"type":"text"}` | 可设置 JSON Object 输出 |
## 响应
字段同[接口说明](/chat#响应)，差异：
| 字段 | 类型 | 说明 |
| ------------------------------------- | ----------- | ------------------------------ |
| `choices[].message.content` | string/null | 最终答案 |
| `choices[].message.reasoning_content` | string/null | 推理内容（模型返回时出现） |
| `choices[].message.tool_calls` | array | 工具调用列表 |
| `choices[].finish_reason` | string | `stop`、`length` 或 `tool_calls` |
| `usage.completion_tokens` | integer | 输出 Token 数，包含模型返回的推理 Token |
## 计费
按 token 计费；预扣与结算规则见[接口说明](/chat#计费)。推理 Token 计入输出 Token。
## 错误
本页无特有错误，见[接口说明](/chat#错误)。
# Gemini 系列
Source: https://looptoken.vibelab.me/docs/chat/gemini
> Google Gemini 对话模型（gemini-3.5-flash 等），OpenAI 格式调用，同步或 SSE 流式，gemini-3.1-pro-preview 支持视频输入
调用方式与[接口说明](/chat)一致（OpenAI 格式）。请求体由平台原样转发到上游渠道，参数支持以上游渠道实际行为为准。
| 项 | 值 |
| -- | -------------------------------------- |
| 模型 | 见下表（实际可用以[模型列表](/models)为准） |
| 模式 | 同步或 SSE 流式 |
| 计费 | 按 token，输入与输出分别计价，价格以[定价页](/pricing)为准 |
| 模型 | 上下文 | 最大输出 | 说明 |
| ------------------------ | --- | ---- | --------------------------- |
| `gemini-3.5-flash` | 1M | 64K | Gemini 3.5 Flash，最新一代高性价比模型 |
| `gemini-3.1-pro-preview` | 1M | 64K | Gemini 3.1 Pro 预览版 |
| `gemini-3-pro-preview` | 1M | 64K | Gemini 3 Pro 预览版 |
| `gemini-2.5-pro` | 1M | 64K | Gemini 2.5 Pro |
| `gemini-2.5-flash` | 1M | 64K | Gemini 2.5 Flash |
## 快速开始
curl
Python
```bash
curl https://api.vibelab.me/v1/chat/completions \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.5-flash",
"messages": [{"role": "user", "content": "用一句话介绍量子计算"}]
}'
```
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.vibelab.me/v1",
api_key="sk-lt-...",
)
resp = client.chat.completions.create(
model="gemini-3.5-flash",
messages=[{"role": "user", "content": "用一句话介绍量子计算"}],
)
print(resp.choices[0].message.content)
```
## 请求参数
参数同[接口说明](/chat#请求参数)，差异如下：
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------------------------------------------------------- | ------ | -- | -- | ------------------------------------------------------------------------------------------------------------------ |
| `model`、`messages`、`stream`、`max_tokens`、`temperature`、`top_p` | - | - | - | 常用参数可正常使用 |
| `messages[].content[]`（`type: "video_url"`） | object | 否 | - | 仅 `gemini-3.1-pro-preview`：`video_url.url` 必填，平台转成 `image_url` 块转发；也可直接用 `image_url` 传 `data:video/mp4;base64,...` |
| `logit_bias`、`presence_penalty`、`response_format.json_schema` | - | 否 | - | OpenAI 专属参数，不属于稳定兼容范围 |
## 响应
字段同[接口说明](/chat#响应)。Gemini 2.5/3 系列的内部推理 token 计入输出用量；LoopToken 只承诺标准 `content` 和 `usage`，不承诺透出完整思维链。
## 计费
按 token 计费，规则见[接口说明](/chat#计费)。
## 错误
| HTTP | code | 触发场景 | 处理 |
| ---- | ------------------- | ------------------------------------------------------------------------ | --------------------- |
| 400 | `invalid_request` | `video_url` 块缺少 `video_url.url`（仅 `gemini-3.1-pro-preview`） | 补全 `video_url.url` |
| 400 | `invalid_image_url` | Data URL 不是 base64 或 MIME 非图片（`gemini-3.1-pro-preview` 例外接受 `video/mp4`） | 见[图片内容块](/chat#图片内容块) |
其余错误见[接口说明](/chat#错误)。
# GPT 系列
Source: https://looptoken.vibelab.me/docs/chat/gpt
> OpenAI GPT 系列对话模型（gpt-6.1-* / gpt-6-* / gpt-5.6-* / gpt-5.5 / gpt-5.4），按官方原价计费，支持缓存、长上下文与 Fast 档
GPT 系列对话模型，上游为 OpenAI 官方实现，请求遵循 OpenAI Chat Completions 协议。平台通用规则见[接口说明](/chat)。
| 项 | 值 |
| -- | ------------------------------------------------------------ |
| 模型 | 见下表（实际可用以[模型列表](/models)为准） |
| 模式 | 同步或 SSE 流式 |
| 计费 | 按 token、OpenAI 官方原价，推理 Token 计入输出 token，价格以[定价页](/pricing)为准 |
| 模型 | 上下文 | 说明 |
| --------------- | ----- | ------------- |
| `gpt-6.1-sol` | 1.05M | GPT-6.1 Sol |
| `gpt-6.1-terra` | 1.05M | GPT-6.1 Terra |
| `gpt-6-astra` | 400K | GPT-6 Astra |
| `gpt-6-sol` | 400K | GPT-6 Sol |
| `gpt-6-luna` | 400K | GPT-6 Luna |
| `gpt-5.6-sol` | 400K | GPT-5.6 Sol |
| `gpt-5.6-terra` | 400K | GPT-5.6 Terra |
| `gpt-5.6-luna` | 400K | GPT-5.6 Luna |
| `gpt-5.5` | 1.05M | GPT-5.5 |
| `gpt-5.4` | 400K | GPT-5.4 |
| `gpt-5.4-mini` | 400K | GPT-5.4 Mini |
## 计费规则
与 OpenAI 官方计费口径一致：
* **缓存读取**：命中提示词缓存的输入 token（usage 里的 `cached_tokens`）按缓存价计费，约为输入价的 10%（GPT-6.1 系为 5%）。缓存写入暂按普通输入价计费。
* **长上下文**：单次请求输入超过 272K token 时，整单输入与缓存读取按 2 倍、输出按 1.5 倍计费（适用 GPT-6 / 6.1 / 5.6 / 5.5 / 5.4，`gpt-5.4-mini` 除外）。
* **Fast 档**：请求带 `service_tier: "priority"` 或 `"fast"`（Codex `/fast`）时按官方 Fast 价计费，多数模型为标准价的 2 倍（`gpt-5.5` 为 2.5 倍）。
## 快速开始
curl
Python
Node.js
```bash
curl https://api.vibelab.me/v1/chat/completions \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.4",
"messages": [{"role": "user", "content": "用一句话介绍量子计算"}],
"reasoning_effort": "low",
"max_completion_tokens": 1024
}'
```
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.vibelab.me/v1",
api_key="sk-lt-...",
)
resp = client.chat.completions.create(
model="gpt-5.4",
messages=[{"role": "user", "content": "用一句话介绍量子计算"}],
reasoning_effort="low",
max_completion_tokens=1024,
)
print(resp.choices[0].message.content)
print(resp.usage)
```
```ts
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://api.vibelab.me/v1',
apiKey: 'sk-lt-...',
});
const resp = await client.chat.completions.create({
model: 'gpt-5.4',
messages: [{ role: 'user', content: '用一句话介绍量子计算' }],
reasoning_effort: 'low',
max_completion_tokens: 1024,
});
console.log(resp.choices[0].message.content);
console.log(resp.usage);
```
```json title="响应"
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1783819200,
"model": "gpt-5.4",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "量子计算是利用量子叠加与纠缠进行信息处理的计算范式。"},
"finish_reason": "stop"
}],
"usage": {"prompt_tokens": 18, "completion_tokens": 40, "total_tokens": 58}
}
```
## 请求参数
完全遵循 OpenAI 官方 Chat Completions 协议。平台通用规则（校验链、预扣、流式 usage 注入）见[接口说明](/chat)。上游为 OpenAI 官方实现，以下参数按 OpenAI 官方语义生效：
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------------------------------------------- | ------------- | -- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `model` | string | 是 | - | 上表中的模型名 |
| `messages` | array | 是 | - | 对话消息列表，`content` 支持字符串或多模态内容块数组（见[多模态输入](#多模态输入)） |
| `max_completion_tokens` | int | 否 | - | 生成最大 Token 数（含推理 Token）；`max_tokens` 已被 OpenAI 官方废弃，GPT-5 系列不再接受，请改用本参数。平台预扣估算只读 `max_tokens`，可两者同传 |
| `temperature` | float | 否 | `1` | 采样温度，`[0, 2]`，默认 `1`；GPT-5 系列推理模型仅支持默认值 |
| `top_p` | float | 否 | - | 核采样，`(0, 1]`；GPT-5 系列推理模型仅支持默认值 |
| `reasoning_effort` | string | 否 | `medium` | 推理力度：`minimal` / `low` / `medium`（默认） / `high`，仅 GPT-5 系列支持 |
| `verbosity` | string | 否 | `medium` | 输出详尽度：`low` / `medium`（默认） / `high`，仅 GPT-5 系列支持 |
| `n` | int | 否 | `1` | 生成候选回复数量，默认 `1` |
| `stream` / `stream_options` | bool / object | 否 | - | SSE 流式，平台行为见[接口说明](/chat) |
| `stop` | string/array | 否 | - | 停止序列，最多 4 个；GPT-5 系列推理模型不支持 |
| `frequency_penalty` | float | 否 | `0` | 频率惩罚，`[-2, 2]`，默认 `0` |
| `presence_penalty` | float | 否 | `0` | 存在惩罚，`[-2, 2]`，默认 `0` |
| `logit_bias` | map | 否 | - | token ID → 偏置值（`-100` 到 `100`） |
| `logprobs` / `top_logprobs` | bool / int | 否 | - | 返回对数概率；`top_logprobs` 取值 `0-20`，需 `logprobs: true` |
| `seed` | int | 否 | - | 尽力而为的确定性采样，配合响应中的 `system_fingerprint` 判断复现性 |
| `response_format` | object | 否 | - | `{"type":"text"}` / `{"type":"json_object"}` / `{"type":"json_schema","json_schema":{...}}`（见[结构化输出](#结构化输出)） |
| `tools` / `tool_choice` / `parallel_tool_calls` | - | 否 | - | 工具调用（见[工具调用](#工具调用)） |
| `prediction` | object | 否 | - | 预测输出（Predicted Outputs），加速已知大部分内容的改写场景 |
| `user` | string | 否 | - | 终端用户标识，用于上游滥用检测 |
## 请求示例
### 多模态输入
GPT 系列支持图片输入(视觉理解),`content` 使用内容块数组,图片以 `image_url` 块传入（支持 https URL 或 `data:` base64）:
```json
{
"model": "gpt-5.4",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "这张图里有什么?"},
{"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg", "detail": "auto"}}
]
}
]
}
```
`detail` 可选 `low` / `high` / `auto`(默认),影响图片消耗的输入 token 数。
### 结构化输出
`response_format` 传 `json_schema` 可强约束输出为指定 JSON Schema:
```json
{
"model": "gpt-5.4",
"messages": [{"role": "user", "content": "北京今天多云,25 度"}],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "weather",
"strict": true,
"schema": {
"type": "object",
"properties": {
"city": {"type": "string"},
"temperature": {"type": "number"},
"condition": {"type": "string"}
},
"required": ["city", "temperature", "condition"],
"additionalProperties": false
}
}
}
}
```
### 工具调用
标准 OpenAI Function Calling:`tools` 声明工具,模型返回 `finish_reason: "tool_calls"` 和 `choices[].message.tool_calls`,执行后以 `role: "tool"` 消息回传结果:
```json
{
"model": "gpt-5.4",
"messages": [{"role": "user", "content": "上海现在天气怎么样?"}],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的当前天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"]
}
}
}
],
"tool_choice": "auto"
}
```
## 响应
字段同[接口说明](/chat#响应)。工具调用时 `finish_reason` 为 `tool_calls`，`choices[].message.tool_calls` 为工具调用列表，`content` 可能为 `null`。
## 计费
与[接口说明](/chat#计费)一致：按 token 计费，GPT-5 系列的推理 Token 计入输出 token。
## 错误
本页无特有错误，见[接口说明](/chat#错误)。非 `image/*` 的 Data URL 返回 `400 invalid_image_url`。
## 注意事项
* **传 `max_tokens`** → 上游 GPT-5 系列不再接受，请改用 `max_completion_tokens`；平台预扣估算只读 `max_tokens`，需要精确预扣时可两者同传。
* **`store`、`metadata`、`service_tier` 等账户级参数** → 经中转链路不保证生效，不要依赖。
# 接口说明
Source: https://looptoken.vibelab.me/docs/chat
> POST /v1/chat/completions：除 Claude 外全部对话模型共用的 OpenAI Chat Completions 兼容协议，同步或 SSE 流式，按 token 计费
请求体、响应体与 OpenAI 官方 Chat Completions 一致，支持非流式和流式（SSE）。各系列模型页只写与本页的差异。
| 项 | 值 |
| -- | -------------------------------------------------------------------------------------------------- |
| 模型 | 除 Claude 外的全部对话模型（deepseek、gpt、gemini 等系列；Claude 见 [Claude 系列](/chat/claude)），可用模型见[模型列表](/models) |
| 模式 | 同步；`stream: true` 时为 SSE 流式 |
| 计费 | 按 token，输入与输出分别计价，价格以[定价页](/pricing)为准 |
各系列差异：
| 系列 | 差异 |
| ---------------------- | ------------------------------------------------------------------------ |
| [Claude](/chat/claude) | **不走本协议**，使用 Anthropic 原生 `POST /v1/messages`；用本接口请求 `claude-*` 返回 `400` |
| [GPT](/chat/gpt) | 上游为 OpenAI 官方实现，支持完整 OpenAI 参数集（多模态输入、结构化输出、工具调用等） |
| [Gemini](/chat/gemini) | 部分 OpenAI 参数不属于稳定兼容范围；`gemini-3.1-pro-preview` 支持视频输入 |
## 快速开始
curl
Python
Node.js
```bash
curl https://api.vibelab.me/v1/chat/completions \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [{"role": "user", "content": "什么是人工智能?"}]
}'
```
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.vibelab.me/v1",
api_key="sk-lt-...",
)
stream = client.chat.completions.create(
model="deepseek-v4-flash",
messages=[{"role": "user", "content": "数到5"}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
if chunk.usage:
print("\nusage:", chunk.usage)
```
```ts
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://api.vibelab.me/v1',
apiKey: 'sk-lt-...',
});
const stream = await client.chat.completions.create({
model: 'deepseek-v4-flash',
messages: [{ role: 'user', content: '数到5' }],
stream: true,
});
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta?.content;
if (delta) process.stdout.write(delta);
if (chunk.usage) console.log('\nusage:', chunk.usage);
}
```
上面的 curl 是非流式请求，响应如下：
```json title="非流式响应"
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1779964861,
"model": "deepseek-v4-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "人工智能(AI)是计算机科学的一个分支,致力于创建能够模拟人类智能行为的系统。"
},
"finish_reason": "stop"
}
],
"usage": {"prompt_tokens": 15, "completion_tokens": 42, "total_tokens": 57}
}
```
## 模式选择
| 模式 | 怎么传参 | 说明 |
| ------- | --------------------------- | ------------------------------ |
| 非流式 | 省略 `stream` 或传 `false` | 一次返回完整响应 |
| 流式 | `stream: true`（curl 加 `-N`） | SSE，见[流式响应](#流式响应) |
| 多模态（图片） | `messages[].content` 用内容块数组 | 见[图片内容块](#图片内容块)，各模型支持范围以模型页为准 |
## 请求参数
### 平台处理的字段
以下字段会被平台读取或改写：
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------------- | ------- | -- | ------- | ------------------------------------------------------------------------------------------------------- |
| `model` | string | 是 | - | 缺失或为空 → 400 `invalid_request`；不在该 key 的模型白名单内 → 403 `model_not_allowed`；平台没有该模型 → 404 `model_not_found` |
| `messages` | array | 是 | - | 必须为非空数组；`content` 支持字符串或多模态数组（平台取其中的 `text` 块估算用量）；缺失或不合法 → 400 `invalid_request` |
| `stream` | boolean | 否 | `false` | `true` 时走 SSE 流式响应；传 `null` 或省略都按 `false` 处理 |
| `max_tokens` | integer | 否 | - | 参与请求发起前的费用预扣估算，见[计费](#计费) |
| `stream_options` | object | 否 | - | 仅 `stream: true` 时生效：平台自动注入 `include_usage: true`（与你传入的值合并），流末尾必定返回 usage |
### 透传参数
上游网关已适配，平台原样透传；是否生效、取值边界以所选模型实际行为为准。本表未列出的其他参数同样原样透传，平台不做额外处理。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------------------- | ------------- | -- | -- | ------------------------------------------------------------------- |
| `temperature` | float | 否 | - | 采样温度，取值 `[0, 2)` |
| `top_p` | float | 否 | - | 核采样概率阈值，取值 `(0, 1]` |
| `max_completion_tokens` | int | 否 | - | 生成最大 Token 数（含推理 Token），上游优先于 `max_tokens` 读取；平台预扣估算只读 `max_tokens` |
| `n` | int | 否 | - | 生成候选回复数量 |
| `stop` | array | 否 | - | 停止生成的字符串列表 |
| `seed` | int | 否 | - | 随机种子，提升可复现性 |
| `presence_penalty` | float | 否 | - | 存在惩罚，取值 `[-2, 2]` |
| `tools` | array | 否 | - | 可调用的工具列表 |
| `tool_choice` | string/object | 否 | - | 工具调用策略：`"auto"` / `"none"` 等 |
| `response_format` | object | 否 | - | 输出格式约束，如 `{"type": "json_object"}` |
### messages 结构
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------------- | ------------ | -- | -- | ------------------------------------------------------ |
| `messages[].role` | string | 是 | - | `system` / `developer` / `user` / `assistant` / `tool` |
| `messages[].content` | string/array | 是 | - | 消息文本，或模型支持的多模态内容对象数组 |
| 角色 | 说明 |
| ----------- | -------------------------- |
| `system` | 系统指令，设定模型行为（人格、约束、输出格式） |
| `user` | 用户输入 |
| `assistant` | 模型回复（多轮对话历史） |
| `tool` | 工具执行结果（需配合 `tool_call_id`） |
### 图片内容块
支持视觉理解的模型可在 `user` 消息中使用内容对象数组。各模型支持范围以对应模型文档为准。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------------------------- | ------ | ------------------- | -- | -------------------------- |
| `content[].type` | string | 是 | - | 文本为 `text`，图片为 `image_url` |
| `content[].text` | string | `type=text` 时是 | - | 文本内容 |
| `content[].image_url.url` | string | `type=image_url` 时是 | - | 公网图片 URL 或 Base64 Data URL |
| `content[].image_url.detail` | string | 否 | - | 图片精度：`low`、`high` 或 `auto` |
Base64 图片必须使用 `data:image/...;base64,...` Data URL。`gemini-3.1-pro-preview` 为兼容其视频理解链路，也接受 `data:video/mp4;base64,...`；其他模型把视频、PDF 等非图片 MIME 放入 `image_url` 时，平台在扣费前返回 HTTP 400 `invalid_image_url`。
## 请求示例
多轮对话：
```json
{
"model": "deepseek-v4-flash",
"messages": [
{"role": "system", "content": "你是一个有帮助的 AI 助手"},
{"role": "user", "content": "什么是量子计算?"},
{"role": "assistant", "content": "量子计算是利用量子力学原理进行信息处理的计算方式..."},
{"role": "user", "content": "它和经典计算有什么区别?"}
],
"temperature": 0.7,
"max_tokens": 2048
}
```
## 响应
| 字段 | 类型 | 说明 |
| ------------------------- | ------ | ---------------------------------------------------- |
| `id` | string | 请求唯一标识 |
| `object` | string | 非流式 `"chat.completion"`，流式 `"chat.completion.chunk"` |
| `created` | int64 | 创建时间戳（Unix 秒） |
| `model` | string | 平台尽力改写为你请求时使用的平台模型名 |
| `choices[].index` | int | 选项索引 |
| `choices[].message` | object | 回复消息（非流式）；`role` 固定为 `"assistant"`，`content` 为回复文本 |
| `choices[].delta` | object | 增量消息（流式，字段同 `message`） |
| `choices[].finish_reason` | string | `"stop"` / `"length"` / `"tool_calls"` |
| `usage.prompt_tokens` | int | 输入 Token 数 |
| `usage.completion_tokens` | int | 输出 Token 数 |
| `usage.total_tokens` | int | 总 Token 数 |
### 流式响应
`stream: true` 时为标准 SSE：每个事件以 `data: ` 开头，内容为一个 JSON chunk；末尾以 `data: [DONE]` 结束。平台强制注入 `stream_options.include_usage: true`，最后一个 chunk（`choices` 为空数组）携带完整 `usage`。平台尽力将 `model` 改写为你请求时的平台模型名；个别数据块不含该字段时原样透传。
```text
data: {"id":"chatcmpl-ghi789","object":"chat.completion.chunk","created":1779964861,"model":"deepseek-v4-flash","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
data: {"id":"chatcmpl-ghi789","object":"chat.completion.chunk","created":1779964861,"model":"deepseek-v4-flash","choices":[{"index":0,"delta":{"content":"春"},"finish_reason":null}]}
...
data: {"id":"chatcmpl-ghi789","object":"chat.completion.chunk","created":1779964861,"model":"deepseek-v4-flash","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-ghi789","object":"chat.completion.chunk","created":1779964861,"model":"deepseek-v4-flash","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":86,"total_tokens":98}}
data: [DONE]
```
## 计费
* 按 token 计费，输入（prompt）与输出（completion）分别计价，价格见[定价页](/pricing)。流式与非流式均在响应中返回 `usage`（流式在末尾 chunk）。
* 请求发起前按估算用量预扣：输入按消息文本估算，输出取 `min(模型最大输出, max_tokens)`；未传 `max_tokens` 时受平台冻结上限约束。响应完成后按实际 `usage` 结算，多退少补。
* 上游失败、渠道耗尽时预扣全额退回。
## 错误
错误体为 `{"error": {"message", "type", "code", "request_id"}}`，`type` 与 `code` 相同，完整格式见[错误码](/errors)。
| HTTP | code | 触发场景 | 处理 |
| ---- | ----------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------ |
| 400 | `invalid_request` | 请求体不是合法 JSON，`model` 缺失或为空，`messages` 缺失、不合法或为空数组 | 按 `message`（如 `missing model`、`messages required`）修正请求 |
| 400 | `invalid_image_url` | Data URL 格式不合法或不是图片 MIME（`gemini-3.1-pro-preview` 例外接受 `video/mp4`） | 改用合法的 `data:image/...;base64,...`，见[图片内容块](#图片内容块) |
| 400 | `context_length_exceeded` | 上游判定输入超出模型上下文窗口 | 缩短 `messages` 或换用更长上下文的模型 |
| 400 | 上游 code（缺省 `invalid_request_error`） | 上游返回 400，表示请求本身有问题（违规内容、非法参数值等） | 按 `message` 修改请求，重试不会改变结果 |
| 402 | `insufficient_credits` | 账户余额不足以覆盖预扣费用 | 充值后重试 |
| 403 | `model_not_allowed` | `model` 不在该 API Key 的模型白名单内 | 调整 Key 的模型白名单或换模型 |
| 404 | `model_not_found` | 平台没有该模型 | 对照[模型列表](/models) |
| 502 | `upstream_error` | 上游返回错误，或最多 3 个渠道均失败 | 指数退避重试 |
| 503 | `no_available_channel` | 该模型当前没有可用渠道 | 稍后重试 |
| 504 | `upstream_timeout` | 非流式请求上游 5 分钟内未完成（不换渠道重试）；流式请求上游 1 分钟内未返回响应头且各渠道均超时 | 长输出改用流式 |
更多错误码见[错误码](/errors)。
## 注意事项
* **请求体超过 128 MiB** → 读取被截断，按非法 JSON 返回 400 `invalid_request`。
* **同时传 `max_tokens` 和 `max_completion_tokens`** → 上游优先读 `max_completion_tokens`，平台预扣只读 `max_tokens`。
* **流式请求首字节写出后上游失败** → 不再换渠道重试。
* **响应中的 `model`** → 平台改写为你请求的模型名，不暴露上游模型名。
# GPT Image 2.6
Source: https://looptoken.vibelab.me/docs/images/gpt-image-2-6
> gpt-image-2.6-flare / gpt-image-2.6-sunburst 文生图、图生图、局部重绘，同步，按 token 计费
| 项 | 值 |
| -- | ----------------------------------------------------------- |
| 模型 | `gpt-image-2.6-flare`、`gpt-image-2.6-sunburst`（OpenAI 官方线路） |
| 能力 | 文生图、图生图、局部重绘，同一接口 |
| 模式 | 同步，返回 OpenAI Images 格式 |
| 计费 | **按 token 收费**，价格以[定价页](/pricing)为准 |
两个规格的参数、比例与像素映射、响应格式、错误码与 [GPT Image 2 Official](/images/gpt-image-2-official) 完全一致（`prompt`、`n`、`size`、`resolution`、`quality`、`background`、`output_format`、`output_compression`、`moderation`、`image_urls`、`mask_url`），本页只列差异。
## 规格区别
| 模型 | 特点 |
| ------------------------ | ----------------- |
| `gpt-image-2.6-flare` | 更快，单张约 6 秒 |
| `gpt-image-2.6-sunburst` | 质量更高，多次编辑之间的一致性更好 |
## 新增参数 `complexity`
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | ------ | -- | ------ | --------------------------------------------------------------- |
| `complexity` | string | 否 | `high` | `none` / `low` / `medium` / `high` / `xhigh` / `max`，取值非法返回 400 |
`complexity` 只对 2.6 两个模型生效；`gpt-image-2-official` 传入会返回 400。`quality` 仍只接受 `auto` / `low` / `medium` / `high`，`n` 取 1-4。
```bash
curl https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-flare",
"prompt": "星空下的古老城堡",
"size": "16:9",
"resolution": "2k",
"quality": "high",
"complexity": "high"
}'
```
## 计费
按文本输入、图片输入、图片输出三类 token 分别计价，规则与 [GPT Image 2 Official](/images/gpt-image-2-official#计费) 相同。默认 `complexity=high` 下实测单张输出 token（两个规格相同）：
| 分辨率 / 质量 | 输出 token |
| --------------------- | -------: |
| 1K / `low` | 约 824 |
| 1K / `medium` | 约 1449 |
| 1K / `high` | 约 1758 |
| 1K / `auto` | 约 5795 |
| 2K / `high` | 约 3569 |
| 4K（3840x2160）/ `high` | 约 3337 |
`quality=auto` 的输出 token 比 `high` 还多，想控制费用请显式指定 `quality`。`complexity` 越高费用可能越高。提交时按所选档位的上限冻结额度（`auto` 冻结额度最高），出图后按实际 token 结算并退还差额。
# GPT Image 2 Official
Source: https://looptoken.vibelab.me/docs/images/gpt-image-2-official
> gpt-image-2-official 文生图、图生图、局部重绘，同步，按 token 计费
| 项 | 值 |
| ---- | ---------------------------------------------------------------------------------------------- |
| 模型 | `gpt-image-2-official`（OpenAI 官方线路） |
| 能力 | 文生图、图生图、局部重绘，同一接口 |
| 规格 | 1K / 2K / 4K 三档分辨率、15 种比例、单次最多 4 张、最多 16 张参考图 |
| 模式 | 同步，返回 OpenAI Images 格式 |
| 计费 | **按 token 收费**（[GPT Image 系列](/images/gpt-image)其他版本按成功图片张数收费），价格以[定价页](/pricing)为准，见[计费](#计费) |
| 媒体保留 | `data[].url` 为临时地址，请及时转存 |
同一句提示词，1K 低质量约 200 个输出 token，4K 高质量约 13000 个，两者价差近 70 倍。选档位前先看[计费](#计费)。
## 快速开始
```bash
curl https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-official",
"prompt": "星空下的古老城堡",
"size": "16:9",
"resolution": "2k",
"quality": "high",
"n": 1
}'
```
```json
{
"created": 1788012156,
"data": [{ "url": "https://cdn.example.com/image.png" }]
}
```
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------------- | --------- | -- | ------- | -------------------------------------------------- |
| `model` | string | 是 | - | 固定 `gpt-image-2-official` |
| `prompt` | string | 是 | - | 支持中英文 |
| `n` | integer | 否 | `1` | 1-4，纯数字不加引号 |
| `size` | string | 否 | `1:1` | `auto`、15 种比例之一，或 `<宽>x<高>` 像素串 |
| `resolution` | string | 否 | `1k` | `1k` / `2k` / `4k` |
| `quality` | string | 否 | `auto` | `auto` / `low` / `medium` / `high`，`auto` 接近 `low` |
| `background` | string | 否 | `auto` | `auto` / `opaque` / `transparent` |
| `output_format` | string | 否 | `png` | `png` / `jpeg` / `webp` |
| `output_compression` | integer | 否 | - | 0-100，仅对 `jpeg`、`webp` 生效 |
| `moderation` | string | 否 | `auto` | `auto` / `low` |
| `image_urls` | string\[] | 否 | - | 参考图，最多 16 张，单张不超过 20MB、合计不超过 256MB，须公网可直接访问 |
| `mask_url` | string | 否 | - | 局部重绘遮罩，必须与 `image_urls` 一起用 |
| `nsfw_check` | boolean | 否 | `false` | 提交前对提示词和参考图做一次内容审核，会增加一点延迟 |
### 参数细则
* **`prompt`**：中英文都可以，描述越具体结果越稳。为空或只有空白字符会返回 400，不会产生任何费用。
* **`n`**：1 到 4。每张图各自消耗输出 token，`n=4` 的费用就是单张的四倍。必须写纯数字 `4`；写成字符串 `"4"` 会被当作没传，静默按 1 张出图。
* **`size`**：三种写法。`auto` 由服务端按提示词和参考图挑比例，挑不出时用 `1:1`；下表 15 种比例之一；或直接给 `1881x836` 这样的像素串（原样转给上游，最终尺寸以返回图片为准）。其他值返回 400。
* **`resolution`**：`1k` 以 1024 为基准、`2k` 以 2048、`4k` 以 3840。三档都支持全部 15 种比例。
* **`quality`**：`auto` 实际接近 `low`。档位同时决定画质和费用——`4k` + `high` 单张约 13000 输出 token，是 `1k` + `low` 的近 70 倍。
* **`background`**：`transparent` 时输出带 Alpha 通道，且 `output_format` 只能是 `png` 或 `webp`，配 `jpeg` 返回 400。`opaque` 强制不透明，`auto` 由模型判断。
* **`output_format`**：`png` 保真且支持透明，`jpeg` 文件最小但没有 Alpha 通道，`webp` 兼顾体积和透明。
* **`output_compression`**：0 到 100，数值越小压得越狠、文件越小。只对 `jpeg` 和 `webp` 生效，传给 `png` 无效果。超出范围返回 400。
* **`moderation`**：`low` 比默认的 `auto` 宽松。这是模型侧的生成审核强度，和 `nsfw_check` 是两回事。
* **`image_urls`**：最多 16 张，单张 20MB、合计 256MB 以内。必须是公网能直接下载的稳定地址——带签名有效期的临时链接过期后会导致任务失败。超过 16 张返回 400。
* **`mask_url`**：局部重绘用，白色（不透明）区域保留、透明区域重绘。**遮罩图必须带 Alpha 通道，且尺寸与第一张参考图完全一致**，否则上游拒单。单独传 `mask_url` 而不传 `image_urls` 会返回 400。
* **`nsfw_check`**：置 `true` 时先用审核模型过一遍提示词和参考图，命中违规直接拒绝。默认 `false`，不发这次审核请求，省一点延迟和成本。
以下情况平台本地就会返回 400，不会提交上游、不产生费用：提示词为空、`n` 越界、`resolution` 或 `quality` 不在枚举内、`size` 既不是合法比例也不是像素串、参考图超过 16 张、`mask_url` 缺少 `image_urls`、透明背景配 `jpeg`、`output_compression` 越界、`moderation` 取值非法。本模型只在 `/v1/images/generations` 上提供，走 `/v1/images/edits` 会被拒。
### 比例与实际像素
| `size` | `1k` | `2k` | `4k` |
| -------------- | --------: | --------: | --------: |
| `1:1` / `auto` | 1024x1024 | 2048x2048 | 2880x2880 |
| `3:2` | 1536x1024 | 2048x1360 | 3520x2336 |
| `2:3` | 1024x1536 | 1360x2048 | 2336x3520 |
| `4:3` | 1024x768 | 2048x1536 | 3312x2480 |
| `3:4` | 768x1024 | 1536x2048 | 2480x3312 |
| `5:4` | 1280x1024 | 2560x2048 | 3216x2576 |
| `4:5` | 1024x1280 | 2048x2560 | 2576x3216 |
| `16:9` | 1536x864 | 2048x1152 | 3840x2160 |
| `9:16` | 864x1536 | 1152x2048 | 2160x3840 |
| `2:1` | 2048x1024 | 2688x1344 | 3840x1920 |
| `1:2` | 1024x2048 | 1344x2688 | 1920x3840 |
| `3:1` | 1536x512 | 3072x1024 | 3840x1280 |
| `1:3` | 512x1536 | 1024x3072 | 1280x3840 |
| `21:9` | 2016x864 | 2688x1152 | 3840x1648 |
| `9:21` | 864x2016 | 1152x2688 | 1648x3840 |
部分档位会按 16 的倍数和像素上限做近似映射，客户端应以返回图片的真实尺寸为准。
## 请求示例
### 透明背景贴纸
```bash
curl https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-official",
"prompt": "橘猫贴纸，全身，粗白描边，扁平矢量风格，完全透明背景",
"size": "1:1",
"resolution": "1k",
"quality": "medium",
"background": "transparent",
"output_format": "png"
}'
```
### 图生图与局部重绘
参考图放 `image_urls`，加 `mask_url` 就变成局部重绘，只改遮罩覆盖的区域。
```bash
curl https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-official",
"prompt": "把背景换成沙漠日落",
"size": "1:1",
"quality": "medium",
"image_urls": ["https://your-cdn.com/photo.png"],
"mask_url": "https://your-cdn.com/mask.png"
}'
```
## 响应
同步返回 OpenAI Images 格式，图片在 `data[].url`（见[快速开始](#快速开始)）。
| 字段 | 类型 | 说明 |
| ------------ | ------- | ------------------------------- |
| `created` | integer | Unix 秒级时间戳 |
| `data[].url` | string | 图片临时下载地址，格式由 `output_format` 决定 |
## 计费
按三类 token 分别计价，单价见[定价页](/pricing)：
* **文本输入**：提示词，通常只有几十个 token，可忽略。
* **图片输入**：每张参考图约 1000 个 token（随图片尺寸增加）。它比文本输入贵，因此按 1.6 倍折算成文本输入当量后再按输入单价结算。
* **图片输出**：主要成本。实测单张 1K/`low` 约 196 个、2K/`medium` 约 1413 个、4K/`high` 约 13342 个。
一次调用扣多少，等于三项相加。**提交时的冻结额度按所选档位的上限估算，出图后按实际 token 重新结算并退还差额**，所以下单瞬间看到的冻结金额通常高于最终扣费。
`n` 大于 1 时，输出 token 随张数成倍增长；请求失败不产生图片输出费用。
## 错误
以下均为平台本地校验，返回 `400 invalid_request`，不提交上游、不产生费用（`message` 为英文原文）：
| HTTP | code | 触发场景 | 处理 |
| ---- | ----------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------- |
| 400 | `invalid_request` | `prompt is required` | 提示词不能为空或仅空白 |
| 400 | `invalid_request` | `gpt-image-2-official supports n between 1 and 4` | `n` 取 `1`–`4` |
| 400 | `invalid_request` | `unsupported quality/background/output_format/moderation/resolution/size "..." for gpt-image-2-official` | 使用[请求参数](#请求参数)中列出的枚举 |
| 400 | `invalid_request` | `size must be an aspect ratio or widthxheight` | `size` 用 `auto`、比例或 `<宽>x<高>` |
| 400 | `invalid_request` | `gpt-image-2-official accepts at most 16 reference images` | 参考图不超过 16 张 |
| 400 | `invalid_request` | `mask_url requires image_urls` | 传 `mask_url` 时必须同时传 `image_urls` |
| 400 | `invalid_request` | `transparent background requires output_format png or webp` | 透明背景不要配 `jpeg` |
| 400 | `invalid_request` | `output_compression must be between 0 and 100` | 取 `0`–`100` |
| 400 | `invalid_request` | `gpt-image-2-official is only available on /v1/images/generations` | 改用 `/v1/images/generations` |
其余错误见[图片生成总览](/images#错误)。
## 注意事项
4K 加 `quality=high` 单张耗时通常超过 100 秒，请把客户端超时设到 5 分钟以上。
* **`n` 写成字符串 `"4"`** → 会被当作没传，静默按 1 张出图；必须写纯数字。
* **`mask_url` 遮罩图无 Alpha 通道或尺寸与第一张参考图不一致** → 上游拒单。
* **`image_urls` 使用带签名有效期的临时链接** → 过期后任务失败，须用公网稳定地址。
* **本模型走 `/v1/images/edits`** → 被拒，只在 `/v1/images/generations` 提供。
# GPT Image 系列
Source: https://looptoken.vibelab.me/docs/images/gpt-image
> gpt-image-2、gpt-image-2-lite、gpt-image-2-ext、gpt-image-2.5-ext 同步文生图与编辑，按成功图片数计费
GPT Image 系列同步文生图与编辑，返回 OpenAI Images 格式。当前公开接口不包含 GPT Image 1 和 1.5。公共协议见[图片生成总览](/images)。
| 项 | 值 |
| ---- | ---------------------------------------------------------------------- |
| 模型 | `gpt-image-2`、`gpt-image-2-lite`、`gpt-image-2-ext`、`gpt-image-2.5-ext` |
| 模式 | 同步，返回 OpenAI Images 格式 |
| 计费 | 按成功图片数和分辨率档位，价格以[定价页](/pricing)为准，见[计费](#计费) |
| 媒体保留 | `data[].url` 为临时地址，请及时转存；`data[].b64_json` 由调用方保存 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-lite",
"prompt": "极简科技产品海报，白色背景",
"size": "3:2",
"resolution": "2k",
"n": 1
}'
```
```json
{
"created": 1788012156,
"data": [{"b64_json": "iVBORw0KGgo..."}],
"size": "2048x1152",
"model": "gpt-image-2-lite"
}
```
`gpt-image-2-lite` 固定使用 `data[].b64_json`，`output_format` 为 `png`，顶层 `size` 是最终像素尺寸（例如 `2048x1152`）。
## 模式选择
| 模型 | 能力 | 说明 |
| ---------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `gpt-image-2` / `gpt-image-2-lite` | 文生图、参考图生成 | 1K、2K、4K 三档；`gpt-image-2-lite` 按所选比例和分辨率输出 PNG；`gpt-image-2-lite` 只在 `/v1/images/generations` 提供，`n` 为 1–10 |
| `gpt-image-2-ext` | 文生图、单图编辑 | 通过外部 OpenAI Images 兼容线路；每次固定 1 张；编辑走 `/v1/images/edits`（multipart，单数 `image` 字段） |
| `gpt-image-2.5-ext` | 文生图、参考图生成 | 只支持 `/v1/images/generations`（参考图通过 `image_urls` 传入）；`n` 必须为 `1`；不支持 `/v1/images/edits`；输出与 `gpt-image-2-lite` 一致 |
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------------- | --------- | -- | ------- | -------------------------------------------------------------------------------- |
| `model` | string | 是 | - | `gpt-image-2` / `gpt-image-2-lite` / `gpt-image-2-ext` / `gpt-image-2.5-ext` |
| `prompt` | string | 是 | - | 提示词 |
| `n` | integer | 否 | `1` | 图片数量；`gpt-image-2-lite` 为 `1`–`10`；`gpt-image-2-ext`、`gpt-image-2.5-ext` 固定为 `1` |
| `size` | string | 否 | `1:1` | 支持 `auto` 及常见横竖宽高比 |
| `resolution` | string | 否 | `1k` | `1k` / `2k` / `4k` |
| `image_urls` | string\[] | 否 | - | 参考图，元素须为非空字符串（`gpt-image-2-lite`、`gpt-image-2.5-ext` 校验） |
| `version` | string | 否 | `flare` | 仅 `gpt-image-2.5-ext`：规格，`flare` / `sunburst` |
| `quality`、`output_format` | string | 否 | - | 仅 `gpt-image-2-ext` 使用，见[请求示例](#请求示例) |
### 最终像素尺寸
`gpt-image-2-lite` 与 `gpt-image-2.5-ext` 支持的最终像素尺寸如下：
| `size` | `1k` | `2k` | `4k` |
| -------------- | --------: | --------: | --------: |
| `1:1` / `auto` | 1024x1024 | 2048x2048 | 2880x2880 |
| `3:2` | 1536x1024 | 2048x1360 | 3520x2336 |
| `2:3` | 1024x1536 | 1360x2048 | 2336x3520 |
| `4:3` | 1024x768 | 2048x1536 | 3312x2480 |
| `3:4` | 768x1024 | 1536x2048 | 2480x3312 |
| `5:4` | 1280x1024 | 2560x2048 | 3216x2576 |
| `4:5` | 1024x1280 | 2048x2560 | 2576x3216 |
| `16:9` | 1536x864 | 2048x1152 | 3840x2160 |
| `9:16` | 864x1536 | 1152x2048 | 2160x3840 |
| `2:1` | 2048x1024 | 2688x1344 | 3840x1920 |
| `1:2` | 1024x2048 | 1344x2688 | 1920x3840 |
| `3:1` | 1536x512 | 3072x1024 | 3840x1280 |
| `1:3` | 512x1536 | 1024x3072 | 1280x3840 |
| `21:9` | 2016x864 | 2688x1152 | 3840x1648 |
| `9:21` | 864x2016 | 1152x2688 | 1648x3840 |
## 请求示例
### GPT Image 2 Ext 文生图
JSON 请求，公共参数与其他 GPT Image 2 版本一致。平台调用外部线路时，把 `size` 宽高比和 `resolution` 档位转换为上表中的明确像素尺寸，例如 `16:9` + `2k` 转换为 `2048x1152`。已经使用 `<宽>x<高>` 的 `size` 原样转发。
```bash
curl https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-ext",
"prompt": "极简科技产品海报，白色背景",
"size": "16:9",
"resolution": "2k",
"quality": "low",
"output_format": "png",
"n": 1
}'
```
### GPT Image 2 Ext 单图编辑
发送到 `POST /v1/images/edits`，`Content-Type` 由 curl 自动生成。仅支持一个单数 `image` 文件字段；`image[]` 和多图编辑不属于公开契约。
```bash
curl https://api.vibelab.me/v1/images/edits \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-F "model=gpt-image-2-ext" \
-F "prompt=把红色方块改成蓝色，保留构图和背景" \
-F "image=@./input.png" \
-F "size=1536x1024" \
-F "quality=low" \
-F "n=1"
```
### GPT Image 2.5 Ext 文生图
JSON 文生图请求，可通过 `image_urls` 传入参考图，`n` 固定为 `1`。`version` 选择规格：`flare`（默认）或 `sunburst`，两种规格价格相同；传入其他值返回 400。`size` 与 `resolution` 取值见上方尺寸表。响应为同步 OpenAI Images 格式：`data[].b64_json` 为 PNG，顶层 `size` 是最终像素尺寸，`model` 为 `gpt-image-2.5-ext`。
```bash
curl https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5-ext",
"prompt": "极简科技产品海报，白色背景",
"size": "16:9",
"resolution": "2k",
"version": "sunburst",
"n": 1
}'
```
## 响应
OpenAI Images 格式的 `data[]`：`gpt-image-2-lite`、`gpt-image-2.5-ext` 固定返回 `data[].b64_json`（PNG），顶层 `size` 为最终像素尺寸；`gpt-image-2-ext` 返回 `data[].url` 或 `data[].b64_json`，`gpt-image-2` 同为 `data[]`。必须按返回图片的真实 MIME 类型和像素尺寸处理，见[图片生成总览](/images#响应)。
## 计费
按成功图片数和分辨率档位计价，价格见[定价页](/pricing)。
* `gpt-image-2-ext` 的销售价格固定为线上 `gpt-image-2` 对应档位的 8 折。LoopToken 按成功图片数结算，不使用外部线路返回的 `usage` token 字段（可能全部为 `0`）。
* `gpt-image-2.5-ext`：`flare` 与 `sunburst` 同价。
| `gpt-image-2.5-ext` 分辨率 | 价格（积分/张） |
| ----------------------- | -------: |
| `1k` | 0.10625 |
| `2k` | 0.175 |
| `4k` | 0.2625 |
## 错误
| HTTP | code | 触发场景 | 处理 |
| ---- | ----------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| 400 | `invalid_request` | `gpt-image-2-lite` / `gpt-image-2.5-ext` 请求了 `/v1/images/edits`（`... is only available on /v1/images/generations`） | 改用 `/v1/images/generations` |
| 400 | `invalid_request` | `prompt required`（`gpt-image-2-lite` / `gpt-image-2.5-ext` 提示词为空） | 填写提示词 |
| 400 | `invalid_request` | `n must be between 1 and 10 for gpt-image-2-lite` | `n` 取 `1`–`10` |
| 400 | `invalid_request` | `gpt-image-2.5-ext only supports n=1` / `gpt-image-2-ext only supports n=1` | `n` 传 `1` |
| 400 | `invalid_request` | `version must be flare or sunburst for gpt-image-2.5-ext` | `version` 取 `flare` 或 `sunburst` |
| 400 | `invalid_request` | `unsupported size "..." for ...` / `unsupported resolution "..." for ...` | 使用[尺寸表](#最终像素尺寸)内的比例与档位 |
| 400 | `invalid_request` | `image_urls must be an array of strings` / `image_urls cannot contain empty values` | 传非空字符串数组 |
| 400 | `invalid_request` | `gpt-image-2-ext edits require multipart/form-data`；`multipart/form-data is only supported for gpt-image-2-ext edits` | `gpt-image-2-ext` 编辑用 multipart，其余模型用 JSON |
| 400 | `invalid_request` | `gpt-image-2-ext edits require exactly one image` / `gpt-image-2-ext edits require the singular image field` | 只传一个单数 `image` 文件字段 |
其余错误见[图片生成总览](/images#错误)。
## 注意事项
`gpt-image-2-ext` 只承诺当前已验证的部分兼容能力。外部线路可能只保持自定义尺寸的宽高比，且可能忽略 JPEG、WebP 和压缩率参数。客户端必须按返回文件的真实 MIME 类型和像素尺寸处理，不能根据请求参数推断结果格式或尺寸。
* **`gpt-image-2-ext` 当前实测可靠的输出是 `1536x1024` PNG** → 仍须读取实际返回图片。
* **`quality=low` 会被线路接受，但响应不回显实际上游质量档位** → 不要依赖响应判断质量档位。
* **`gpt-image-2-ext` 编辑使用 `image[]` 或多图** → 不属于公开契约，只用单数 `image`。
# Grok Imagine
Source: https://looptoken.vibelab.me/docs/images/grok-imagine
> grok-imagine-1.5 文生图与 grok-imagine-1.5-edit 图片编辑，同步，返回 OpenAI Images 格式
Grok Imagine 文生图与图片编辑，两个模型各自只在一个端点提供。公共协议见[图片生成总览](/images)。
| 项 | 值 |
| ---- | ------------------------------------------------------------------------------------------------ |
| 模型 | `grok-imagine-1.5`（文生图，`/v1/images/generations`）/ `grok-imagine-1.5-edit`（编辑，`/v1/images/edits`） |
| 模式 | 同步，返回 OpenAI Images 格式 |
| 计费 | 按成功图片数，价格以[定价页](/pricing)为准 |
| 媒体保留 | 结果 URL 为临时地址，请及时转存 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-1.5",
"prompt": "一只坐在阳光窗台上的橘猫，油画风格",
"size": "1:1",
"n": 1
}'
```
```json
{"created": 1719820800, "data": [{"url": "https://..."}]}
```
## 模式选择
| 模式 | 模型 | 端点 | 怎么传参 |
| ---- | ----------------------- | ------------------------ | -------------------------------- |
| 文生图 | `grok-imagine-1.5` | `/v1/images/generations` | 顶层 `prompt` |
| 图片编辑 | `grok-imagine-1.5-edit` | `/v1/images/edits` | 顶层 `prompt` + `image_urls`（至少一张） |
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | --------- | ---- | --- | -------------------------------------------- |
| `model` | string | 是 | - | `grok-imagine-1.5` 或 `grok-imagine-1.5-edit` |
| `prompt` | string | 是 | - | 提示词 / 编辑指令 |
| `size` | string | 否 | - | `1:1`、`16:9`、`9:16`、`3:2`、`2:3` |
| `n` | integer | 否 | `1` | 输出张数 |
| `image_urls` | string\[] | 编辑必填 | - | 参考图 URL，仅 `grok-imagine-1.5-edit` 使用，至少一张 |
## 请求示例
### 文生图
```json
{
"model": "grok-imagine-1.5",
"prompt": "一只坐在阳光窗台上的橘猫，油画风格",
"size": "1:1",
"n": 1
}
```
### 图片编辑
```bash
curl https://api.vibelab.me/v1/images/edits \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-1.5-edit",
"prompt": "将背景改为纯白摄影棚",
"image_urls": ["https://example.com/input.png"],
"n": 1
}'
```
## 响应
OpenAI Images 格式，图片在 `data[].url`，见[图片生成总览](/images#响应)。
## 计费
按成功图片数计费，请求前按 `n` 预扣，失败退款，规则见[图片生成总览](/images#计费)。
## 错误
| HTTP | code | 触发场景 | 处理 |
| ---- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| 400 | `invalid_request` | `grok-imagine-1.5-edit` 请求了 `/v1/images/generations`，或 `grok-imagine-1.5` 请求了 `/v1/images/edits`（`message` 为 `invalid image generation request`） | 按上表选择端点 |
其余错误见[图片生成总览](/images#错误)。
## 注意事项
* **编辑模型走 `/v1/images/generations`（或文生图模型走 `/v1/images/edits`）** → 400。
# 图片生成
Source: https://looptoken.vibelab.me/docs/images
> POST /v1/images/generations 与 /v1/images/edits：全部图片模型共用的同步接口，各模型请求协议与响应格式差异、选型对照
两个端点均为同步：请求会等待生成完成后返回，无需创建任务或轮询。不同模型使用不同请求协议与响应结构，必须按模型解析，不能假设所有图片接口都返回同一种响应体。
| 项 | 值 |
| ---- | ------------------------------------------------------------------------------------------------------------------- |
| 模型 | 见[模型选型](#模型选型)，可用模型以[模型列表](/models)为准 |
| 模式 | 同步（单次请求等待生成完成，无任务 ID，无轮询） |
| 端点 | `POST /v1/images/generations`（文生图、参考图生成/编辑）；`POST /v1/images/edits`（`gpt-image-2-ext` 单图编辑、`grok-imagine-1.5-edit`） |
| 鉴权 | `Authorization: Bearer `，完整规则见[身份认证](/authentication) |
| 计费 | 按识别到的输出张数（`gpt-image-2-official`、`gpt-image-2.6-*` 按 token），价格以[定价页](/pricing)为准 |
| 媒体保留 | 响应中的图片 URL 为临时地址，请及时转存，见[注意事项](#注意事项) |
## 快速开始
```bash
curl https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "Doubao-seedream-4.5", "prompt": "白底上的蓝色圆形图标"}'
```
```json
{"created": 1719820800, "data": [{"url": "https://..."}]}
```
响应格式因模型而异，见[响应](#响应)。API Key 应只保存在服务端。请求头统一为：
```http
Authorization: Bearer
Content-Type: application/json
```
## 模式选择
### `POST /v1/images/generations`
此端点承载文生图与参考图生成/编辑，可用参数由模型决定。
| 模型 | 用途 | 请求提示词与图片 | 生成参数 | 成功响应中的图片 |
| ------------------------------------------------ | ------------ | ---------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------ |
| `Doubao-seedream-4.0` | 文生图、参考图生成 | 顶层 `prompt`；参考图使用顶层 `image` | 顶层图片参数 | `data[].url` 或 `data[].b64_json` |
| `Doubao-seedream-4.5` | 文生图、参考图生成 | 顶层 `prompt`；参考图使用顶层 `image` | 顶层图片参数 | `data[].url` 或 `data[].b64_json` |
| `Doubao-Seedream-5.0-lite` | 文生图、参考图生成 | 顶层 `prompt`；参考图使用顶层 `image` | 顶层图片参数 | `data[].url` 或 `data[].b64_json` |
| `doubao-seedream-5.0-pro` | 文生图、参考图生成 | 顶层 `prompt`；参考图使用 `image_urls` | `size`、`resolution` | `data[].url` 或 `data[].b64_json` |
| `wan2.7-image` | 文生图、编辑、序列生成 | 顶层 `prompt`；参考图使用 `image_urls` | `n`、`size`、`resolution` | `data[].url` 或 `data[].b64_json` |
| `wan2.7-image-pro` | 文生图、编辑、序列生成 | 顶层 `prompt`；参考图使用 `image_urls` | `n`、`size`、`resolution` | `data[].url` 或 `data[].b64_json` |
| `gpt-image-2` / `gpt-image-2-lite` | 文生图、参考图 | 顶层 `prompt`；参考图使用 `image_urls` | `n`、`size`、`resolution` | `data[]`（`gpt-image-2-lite` 为 `data[].b64_json`） |
| `gpt-image-2-ext` | 文生图 | 顶层 `prompt` | `n=1`、`size`、`quality` | `data[].url` 或 `data[].b64_json` |
| `gpt-image-2.5-ext` | 文生图、参考图 | 顶层 `prompt` | `n=1`、`size`、`resolution`、`version` | `data[].b64_json` |
| `gpt-image-2-official` | 文生图、图生图、局部重绘 | 顶层 `prompt`；参考图使用 `image_urls`，遮罩使用 `mask_url` | `n`（1-4）、`size`、`resolution`、`quality`、`background`、`output_format` | `data[].url` |
| `gpt-image-2.6-flare` / `gpt-image-2.6-sunburst` | 文生图、图生图、局部重绘 | 顶层 `prompt`；参考图使用 `image_urls`，遮罩使用 `mask_url` | `n`（1-4）、`size`、`resolution`、`quality`、`complexity` | `data[].url` |
| `nano-banana-2.1` | 文生图、参考图 | 顶层 `prompt`；参考图使用 `image_urls` | `n`（1-4）、`size`、`resolution` | `data[].url` |
| `nano-banana-2.1-ext` | 文生图、参考图 | 顶层 `prompt`；参考图使用 `image_urls` | `n=1`、`size`、`resolution` | `data[].url` |
Seedream 的 `data[]` 返回 URL 还是 Base64 取决于请求的响应格式与模型线路。
详见 [Seedream](/images/seedream) 与 [Wan](/images/wan)。
### `POST /v1/images/edits`
此端点用于 `gpt-image-2-ext` 单图编辑，使用 multipart 表单。
| 模型 | 参考图 | 输出数量 | 尺寸 | 成功响应中的图片 |
| ----------------- | ----------------: | ------ | ------------------------------- | -------------------------------- |
| `gpt-image-2-ext` | 1 张，单数 `image` 字段 | 固定 1 张 | 支持比例 + 分辨率档位并转换为明确宽高；必须读取实际返回尺寸 | `data[].url` 或 `data[].b64_json` |
完整请求结构与示例见 [GPT Image](/images/gpt-image)。
### 模型选型
| 需求 | 模型 | 详情 |
| ---------------------------- | ------------------------------------------------------ | ---------------------------------------------------- |
| 文生图、参考图、组图（OpenAI Images 响应） | Seedream 系列 | [Seedream](/images/seedream) |
| 文生图、编辑、序列生成（扁平协议） | `wan2.7-image` / `wan2.7-image-pro` | [Wan](/images/wan) |
| 按张计费的 GPT Image | `gpt-image-2` / `-lite` / `-ext` / `gpt-image-2.5-ext` | [GPT Image](/images/gpt-image) |
| 按 token 计费、透明背景、局部重绘 | `gpt-image-2-official` | [GPT Image 2 Official](/images/gpt-image-2-official) |
| 按 token 计费、`complexity` 可调 | `gpt-image-2.6-flare` / `gpt-image-2.6-sunburst` | [GPT Image 2.6](/images/gpt-image-2-6) |
| Nano Banana 系列 | `nano-banana` 等 | [Nano Banana](/images/nano-banana) |
| Grok Imagine | `grok-imagine-1.5` / `-edit` | [Grok Imagine](/images/grok-imagine) |
| 快速文生图 | `z-image-turbo` | [其他图片模型](/images/other-models) |
### 请求结构
全部图片模型都使用顶层字段：`model` 与 `prompt` 为主要输入，参考图和生成选项位于请求体顶层。GPT Image、Nano Banana、Grok Imagine 和其他 OpenAI Images 扩展模型的具体请求和响应以 [GPT Image](/images/gpt-image)、[Nano Banana](/images/nano-banana)、[Grok Imagine](/images/grok-imagine) 和 [其他图片模型](/images/other-models) 页面为准。
## 请求参数
公共规则（各模型的完整字段见模型页）：
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | --------- | -- | ---- | ------------------------------------------------------------ |
| `model` | string | 是 | - | 缺失或为空 → 400 `invalid_request`；不在 Key 白名单 → 403；平台没有该模型 → 404 |
| `n` | integer | 否 | `1` | 输出张数；预扣按此值，省略或非正数按 1 |
| `size` | string | 否 | 模型默认 | 尺寸；取值因模型而异 |
| `resolution` | string | 否 | 模型默认 | 分辨率档位（`1k` / `2k` / `4k` 等），仅部分模型使用 |
| `image_urls` | string\[] | 否 | - | 参考图（扁平协议模型），数量上限因模型而异 |
* 请求体最多读取前 20 MiB，超出会被截断，通常因 JSON 不完整返回 400 `invalid_request`。
* 除上述平台读取的字段外，其余字段原样转发给模型服务校验，越界通常表现为 `502 upstream_error`。
* 仅 `gpt-image-2-ext` 的 `/v1/images/edits` 使用 `multipart/form-data`（单数 `image` 文件字段），其余模型一律 JSON。
## 响应
| 响应族 | 模型 | 图片位置 | 说明 |
| ------------- | ------------------------------------------------------------------- | -------------------------------- | ------------------------------ |
| OpenAI Images | Seedream、Wan 2.7、GPT Image、Nano Banana、Grok Imagine、`z-image-turbo` | `data[].url` 或 `data[].b64_json` | 返回 URL 还是 Base64 因模型而异，以各模型页为准 |
* 成功响应体由模型服务透传，平台不向响应体注入请求 ID；请求 ID 位于响应头 `X-Request-Id`，排查时请一并保存。
* 响应中的 `usage` 是模型服务用量，不是 credit 金额。
## 计费
图片按平台识别到的输出张数计费，不同模型单价见[定价页](/pricing)。
* 请求前按模型、数量和尺寸预扣；成功后按可识别的实际图片数结算。
* 2xx 响应结构无法识别图片数时，按本地解析的提交数量结算。
* 模型服务非 2xx、没有可处理资源或重试耗尽，全额退款。
* 响应中的 `usage` 是模型服务用量，不是 credit 金额。
* 失败与退款规则以[错误码](/errors)为准。
## 错误
错误体为统一信封（`type` 与 `code` 相同），不应依赖具体 `message` 文案编写分支：
```json
{
"error": {
"type": "invalid_request",
"code": "invalid_request",
"message": "invalid image generation request",
"request_id": "req_..."
}
}
```
| HTTP | code | 触发场景 | 处理 |
| ---- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| 400 | `invalid_request` | 请求体不是合法 JSON、`model` 缺失或为空；模型与端点不匹配（如 `gpt-image-2-lite`、`gpt-image-2.5-ext`、`gpt-image-2-official`、`gpt-image-2.6-*` 只在 `/v1/images/generations` 提供；`grok-imagine-1.5-edit` 只在 `/v1/images/edits` 提供）；各模型的参数校验失败（见模型页） | 按 `message` 修正请求，重试不会改变结果 |
| 400 | 上游 code | 模型服务返回 400 且带可识别的错误码时透传该 code | 按 `message` 修改请求 |
| 401 | `invalid_api_key` | API Key 缺失或无效 | 检查 Key |
| 402 | `insufficient_credits` | 余额不足以预扣本次请求 | 充值后重试 |
| 403 | `model_not_allowed` | Key 的模型白名单不允许该模型 | 调整白名单 |
| 404 | `model_not_found` | 未知模型名 | 对照[模型列表](/models) |
| 429 | `media_concurrency_exceeded` | 用户或 Key 的媒体并发超限，响应头带 `Retry-After: 5` | 等待后重试 |
| 500 | `internal_error` | 计费、定价或请求构建异常 | 稍后重试 |
| 502 | `upstream_error` | 模型服务拒绝参数、素材或内容，或生成失败（模型服务错误不透出） | 视为暂时不可完成，带抖动退避重试；已预扣部分全额退款 |
| 503 | `no_available_channel` | 当前没有可处理该模型的服务资源；也可能在可重试失败后返回 | 稍后重试，已预扣部分全额退款 |
保留 `request_id` 便于排查，完整说明见[错误码](/errors)。
## 注意事项
* **响应中的图片 URL** → 临时地址，收到成功响应后应尽快下载并保存到自己的持久存储；当前公开契约不承诺精确有效时长。
* **`data[].b64_json`** → 由调用方解码并保存。
* **不同模型的响应体** → 结构不同，必须按模型解析，不能假设所有图片接口返回同一种响应体。
# Nano Banana 系列
Source: https://looptoken.vibelab.me/docs/images/nano-banana
> nano-banana、nano-banana-pro、nano-banana-2、nano-banana-2-lite、nano-banana-2.1 图片生成与参考图编辑，同步返回 OpenAI Images 格式
接口同步等待图片完成并返回 OpenAI Images 响应。参考图编辑只需增加 `image_urls`。公共协议见[图片生成总览](/images)。
| 项 | 值 |
| ---- | ------------------------------------------------------------------------------------------------------------ |
| 模型 | `nano-banana`、`nano-banana-pro`、`nano-banana-2`、`nano-banana-2-lite`、`nano-banana-2.1`、`nano-banana-2.1-ext` |
| 模式 | 同步，返回 OpenAI Images 格式 |
| 计费 | 按成功图片数和 `resolution` 档位，价格以[定价页](/pricing)为准 |
| 媒体保留 | 结果 URL 为临时地址，请及时转存 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-2",
"prompt": "雨夜里的霓虹街道，电影感",
"size": "16:9",
"resolution": "2K",
"n": 1
}'
```
```json
{"created": 1719820800, "data": [{"url": "https://..."}]}
```
## 模式选择
| 模式 | 怎么传参 |
| ----- | ------------------------------------------ |
| 文生图 | 只传 `prompt` |
| 参考图编辑 | 增加 `image_urls`（公网 HTTP(S) URL 或 Data URL） |
## 请求参数
### 模型
| 模型 | 分辨率 | 参考图 | 特点 |
| --------------------- | ------------------- | ---------------------: | ---------------- |
| `nano-banana` | 1K | 最多 14 张，单张 ≤ 10MB | 快速生成与编辑 |
| `nano-banana-pro` | 1K / 2K / 4K | 最多 14 张，单张 ≤ 30MB | 高质量输出，1K 与 2K 同价 |
| `nano-banana-2` | 0.5K / 1K / 2K / 4K | 最多 14 张，单张 ≤ 10MB | 支持搜索增强和极端宽高比 |
| `nano-banana-2-lite` | 仅 1K | 最多 14 张 | 低成本批量生成 |
| `nano-banana-2.1` | 1K / 2K / 4K | 支持，单张 ≤ 20MB | 单次最多 4 张，支持极端宽高比 |
| `nano-banana-2.1-ext` | 1K / 2K / 4K | 支持，单张 ≤ 20MB、合计 ≤ 50MB | 单次 1 张，支持极端宽高比 |
### 参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------------- | --------- | -- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model` | string | 是 | - | 上表模型名 |
| `prompt` | string | 是 | - | 图片描述或编辑指令；`nano-banana` 最长 1000 字符 |
| `size` | string | 否 | `auto` | 宽高比：`auto`、`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`；Nano Banana 2、2.1 系列另支持 `1:4`、`4:1`、`1:8`、`8:1`。`auto` 时文生图由模型在 `1:1` 或 `16:9` 中选择，图生图跟随参考图比例 |
| `resolution` | string | 否 | `1K` | 模型支持的分辨率档位，大小写均可 |
| `n` | integer | 否 | `1` | Lite、`nano-banana-2.1` 最多 4；`nano-banana-2.1-ext` 只能为 1 |
| `image_urls` | string\[] | 否 | - | 参考图，支持公网 HTTP(S) URL 或 `data:image/png;base64,...` 形式的 Data URL；格式 PNG / JPEG / WEBP |
| `google_search` | boolean | 否 | - | 仅 Nano Banana 2 系列，启用文本搜索增强 |
| `google_image_search` | boolean | 否 | - | 仅 Nano Banana 2 系列，启用图片搜索增强 |
### 输出尺寸参考
Nano Banana 2.1 系列各宽高比的输出像素（实际以返回图片为准）：
| 宽高比 | 1K | 2K | 4K |
| ---- | --------- | --------- | --------- |
| 1:1 | 1024×1024 | 2048×2048 | 4096×4096 |
| 2:3 | 848×1264 | 1696×2528 | 3392×5056 |
| 3:2 | 1264×848 | 2528×1696 | 5056×3392 |
| 3:4 | 896×1200 | 1792×2400 | 3584×4800 |
| 4:3 | 1200×896 | 2400×1792 | 4800×3584 |
| 4:5 | 928×1152 | 1856×2304 | 3712×4608 |
| 5:4 | 1152×928 | 2304×1856 | 4608×3712 |
| 9:16 | 768×1376 | 1536×2752 | 3072×5504 |
| 16:9 | 1376×768 | 2752×1536 | 5504×3072 |
| 21:9 | 1584×672 | 3168×1344 | 6336×2688 |
## 响应
OpenAI Images 格式，图片在 `data[].url`，见[图片生成总览](/images#响应)。
## 计费
按成功图片数和 `resolution` 档位计费，价格见[定价页](/pricing)。请求前按 `n` 预扣，失败退款，规则见[图片生成总览](/images#计费)。
## 错误
以下为本页模型的本地参数校验，均返回 `400 invalid_request`（仅 `nano-banana-2.1`、`nano-banana-2.1-ext` 适用）：
| HTTP | code | 触发场景 | 处理 |
| ---- | ----------------- | ----------------------------------------------------------------------------- | --------------------------- |
| 400 | `invalid_request` | ` is only available on /v1/images/generations` | 改用 `/v1/images/generations` |
| 400 | `invalid_request` | ` supports n up to N`（`nano-banana-2.1` 为 4，`nano-banana-2.1-ext` 为 1） | 降低 `n` |
| 400 | `invalid_request` | ` does not support official_fallback` | 删除 `official_fallback` 字段 |
| 400 | `invalid_request` | ` resolution must be one of 1K, 2K, 4K`（大小写不敏感） | 使用支持的档位，或省略 |
其余错误见[图片生成总览](/images#错误)。
## 注意事项
* **Lite 固定按 1K 生成** → 传入其他分辨率不会提升输出清晰度。
* **`nano-banana-2.1`、`nano-banana-2.1-ext` 不传 `resolution`** → 按 1K 生成，按默认档计费。
* **`nano-banana-pro`、`nano-banana` 传 `1:4`、`4:1`、`1:8`、`8:1`** → 任务失败并全额退还积分。
* **参考图需公网可访问** → 下载失败或超出大小限制时任务失败并全额退还积分。
# 其他图片模型
Source: https://looptoken.vibelab.me/docs/images/other-models
> z-image-turbo：快速文生图，每次固定一张，同步，返回 OpenAI Images 格式
`z-image-turbo` 快速文生图。公共协议见[图片生成总览](/images)。
| 项 | 值 |
| ---- | --------------------------- |
| 模型 | `z-image-turbo` |
| 模式 | 同步，返回 OpenAI Images 格式 |
| 计费 | 按成功图片数，价格以[定价页](/pricing)为准 |
| 媒体保留 | 结果 URL 为临时地址，请及时转存 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "z-image-turbo",
"prompt": "中国山水画风格的未来城市",
"size": "16:9",
"resolution": "2K",
"prompt_extend": true
}'
```
```json
{"created": 1719820800, "data": [{"url": "https://..."}]}
```
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------- | -- | --- | ---------------------- |
| `model` | string | 是 | - | `z-image-turbo` |
| `prompt` | string | 是 | - | 提示词 |
| `size` | string | 否 | - | 宽高比，如 `16:9` |
| `resolution` | string | 否 | - | `1K` / `2K` |
| `prompt_extend` | boolean | 否 | - | 是否启用提示词扩写 |
| `n` | integer | 否 | `1` | 平台固定按 1 张处理，传其他值也不会多出图 |
## 响应
OpenAI Images 格式，图片在 `data[].url`，见[图片生成总览](/images#响应)。
## 计费
按成功图片数计费，每次固定一张，规则见[图片生成总览](/images#计费)。
## 错误
本页无特有错误，见[图片生成总览](/images#错误)。
# Seedream 系列
Source: https://looptoken.vibelab.me/docs/images/seedream
> Doubao-seedream-4.0 / 4.5、Doubao-Seedream-5.0-lite、doubao-seedream-5.0-pro：文生图、参考图生图与组图，同步，响应为 OpenAI Images data[]
| 项 | 值 |
| ---- | -------------------------------------------------------------------------------------------------------- |
| 模型 | `Doubao-seedream-4.0` / `Doubao-seedream-4.5` / `Doubao-Seedream-5.0-lite`（另有 `doubao-seedream-5.0-pro`） |
| 端点 | `POST /v1/images/generations` |
| 模式 | 同步；成功响应使用 `data[]` |
| 请求层级 | 参数位于 JSON 顶层，必填 `model` 和顶层 `prompt` |
| 计费 | 按图片，价格以[定价页](/pricing)为准，见[计费](#计费) |
| 媒体保留 | `data[].url` 为临时下载地址，请及时转存 |
三个模型的端点、请求层级和响应族一致，因此集中在一页说明。
## 快速开始
```bash
curl https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "Doubao-seedream-4.0", "prompt": "白底上的蓝色圆形图标"}'
```
```json
{
"created": 1719820800,
"data": [{"url": "https://example.com/generated/01.jpeg", "size": "2048x2048"}],
"usage": {"generated_images": 1, "output_tokens": 16384, "total_tokens": 16384}
}
```
## 模式选择
| 模式 | 怎么传参 |
| ----- | --------------------------------------------------------------------------------------------- |
| 文生图 | 只传 `prompt` |
| 参考图生图 | `image` 传 1–14 张参考图（URL 或 Base64 Data URL）；`doubao-seedream-5.0-pro` 改用 `image_urls` |
| 组图生成 | `sequential_image_generation: "auto"`，用 `sequential_image_generation_options.max_images` 控制上限 |
### 版本能力矩阵
| 能力 | `Doubao-seedream-4.0` | `Doubao-seedream-4.5` | `Doubao-Seedream-5.0-lite` |
| ------- | --------------------- | --------------------- | -------------------------- |
| 文生图 | 支持 | 支持 | 支持 |
| 参考图生图 | 支持，最多 14 张 | 支持，最多 14 张 | 支持，最多 14 张 |
| 组图生成 | 支持，最多 15 张输出 | 支持，最多 15 张输出 | 支持，最多 15 张输出 |
| 可配置输出格式 | 不支持，JPEG | 不支持，JPEG | `jpeg` 或 `png` |
| 尺寸档位 | `1K` / `2K` / `4K` | `2K` / `4K` | `2K` / `3K` / `4K` |
| 提示词优化 | `standard` / `fast` | 仅 `standard` | 仅 `standard` |
### Seedream 5.0 Pro
`doubao-seedream-5.0-pro` 使用同一 generations 端点的扁平扩展格式：参考图放在 `image_urls`，分辨率放在 `resolution`，每次只生成一张。它支持 1K / 2K 和 jpeg / png，最多使用 10 张参考图；首张参考图包含在基础价格中，更多参考图可能产生额外费用。
```json
{
"model": "doubao-seedream-5.0-pro",
"prompt": "高级产品摄影，柔和侧光",
"size": "1:1",
"resolution": "2K",
"image_urls": ["https://example.com/reference.jpg"],
"output_format": "jpeg",
"watermark": false
}
```
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------------------------------------ | ------------------ | -- | --------------------- | -------------------------------------------------------------------------------------------- |
| `model` | string | 是 | - | 使用上表中的精确模型名 |
| `prompt` | string | 是 | - | 中英文提示词；建议不超过 300 个汉字或 600 个英文单词 |
| `image` | string 或 string\[] | 否 | - | 一张或最多 14 张参考图，URL 或 Base64 Data URL；用于保持主体、编辑和多图融合（`doubao-seedream-5.0-pro` 用 `image_urls`） |
| `size` | string | 否 | `2048x2048` | `<宽>x<高>` 或模型支持的档位，规则见下文尺寸表 |
| `response_format` | string | 否 | `url` | `url` 或 `b64_json` |
| `output_format` | string | 否 | `jpeg` | `jpeg` 或 `png`；仅 5.0 Lite，4.0/4.5 不得传入 |
| `watermark` | boolean | 否 | `true` | 设为 `false` 可关闭右下角水印 |
| `optimize_prompt_options` | object | 否 | `{"mode":"standard"}` | `mode` 为 `standard`；只有 4.0 支持 `fast` |
| `sequential_image_generation` | string | 否 | `disabled` | `disabled`（单图）或 `auto`（由模型决定是否返回组图） |
| `sequential_image_generation_options.max_images` | integer | 否 | `15` | `1`–`15`，仅在组图模式生效 |
| `image_urls` | string\[] | 否 | - | 仅 `doubao-seedream-5.0-pro`：参考图 |
| `resolution` | string | 否 | `2K` | 仅 `doubao-seedream-5.0-pro`：`1K` / `2K`，与 `size`（填比例）配合 |
### 参考图约束
每张参考图支持 JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC 或 HEIF，大小不超过 30 MB，宽高都大于 14 px，总像素不超过 36,000,000，宽高比为 1:16 至 16:1。URL 必须能被服务端直接访问；Base64 必须使用 `data:image/;base64,`，其中格式名小写。
单图模式最多输入 14 张参考图并输出 1 张。组图模式满足“参考图数量 + 最终输出数量不超过 15”：无参考图最多输出 15 张，一张参考图最多输出 14 张。
### Seedream 4.0 尺寸表
显式尺寸总像素为 921,600 至 16,777,216，宽高比为 1:16 至 16:1。
| 档位 | 1:1 | 4:3 | 16:9 | 3:2 | 21:9 |
| ---- | ----------- | ----------- | ----------- | ----------- | ----------- |
| `1K` | `1024x1024` | `1152x864` | `1280x720` | `1248x832` | `1512x648` |
| `2K` | `2048x2048` | `2304x1728` | `2848x1600` | `2496x1664` | `3136x1344` |
| `4K` | `4096x4096` | `4704x3520` | `5504x3040` | `4992x3328` | 不提供推荐值 |
竖图使用对应宽高互换值。
### Seedream 4.5 尺寸表
显式尺寸总像素为 3,686,400 至 16,777,216，宽高比为 1:16 至 16:1。
| 档位 | 1:1 | 4:3 | 16:9 | 3:2 | 21:9 |
| ---- | ----------- | ----------- | ----------- | ----------- | ----------- |
| `2K` | `2048x2048` | `2304x1728` | `2848x1600` | `2496x1664` | `3136x1344` |
| `4K` | `4096x4096` | `4704x3520` | `5504x3040` | `4992x3328` | `6240x2656` |
竖图使用对应宽高互换值。
### Seedream 5.0 Lite 尺寸表
显式尺寸总像素为 3,686,400 至 16,777,216，宽高比为 1:16 至 16:1。
| 档位 | 1:1 | 4:3 | 16:9 | 3:2 | 21:9 |
| ---- | ----------- | ----------- | ----------- | ----------- | ----------- |
| `2K` | `2048x2048` | `2304x1728` | `2848x1600` | `2496x1664` | `3136x1344` |
| `3K` | `3072x3072` | `3456x2592` | `4096x2304` | `3744x2496` | `4704x2016` |
| `4K` | `4096x4096` | `4704x3520` | `5504x3040` | `4992x3328` | 不提供推荐值 |
竖图使用对应宽高互换值。档位由模型结合 `prompt` 中的用途和比例描述选择实际尺寸；需要精确尺寸时传 `<宽>x<高>`。
## 请求示例
最小请求：
```json
{
"model": "Doubao-seedream-4.0",
"prompt": "白底上的蓝色圆形图标"
}
```
5.0 Lite 完整请求和 PNG 输出：
```json
{
"model": "Doubao-Seedream-5.0-lite",
"prompt": "现代美术馆的中文活动海报，标题为‘夏日新展’，3:4 竖版，文字清晰",
"size": "2592x3456",
"response_format": "url",
"output_format": "png",
"watermark": false,
"optimize_prompt_options": {"mode": "standard"},
"sequential_image_generation": "disabled"
}
```
多参考图融合与编辑：
```json
{
"model": "Doubao-seedream-4.5",
"prompt": "保留第一张图的人物与第二张图的服装，将背景改为雨夜街道",
"image": [
"https://example.com/person.jpg",
"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB..."
],
"size": "2K"
}
```
最多生成 4 张关联组图：
```json
{
"model": "Doubao-seedream-4.0",
"prompt": "四格连续故事：机器人种下一颗种子，发芽，开花，迎来蝴蝶",
"size": "1K",
"sequential_image_generation": "auto",
"sequential_image_generation_options": {"max_images": 4}
}
```
Base64 返回：
```json
{
"model": "Doubao-seedream-4.5",
"prompt": "透明玻璃杯中的柠檬水，产品摄影",
"size": "2048x2048",
"response_format": "b64_json"
}
```
### 代码示例
curl
Python
Node.js
```bash
# 依赖：curl、jq、openssl、file
response_file=$(mktemp)
curl --fail-with-body https://api.vibelab.me/v1/images/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"Doubao-seedream-4.5","prompt":"白底上的蓝色圆形图标","size":"2048x2048","response_format":"url"}' \
> "$response_file"
index=0
while IFS=$'\t' read -r kind value; do
index=$((index + 1))
if [ "$kind" = error ]; then
echo "item $index failed: $value" >&2
continue
fi
temporary=$(mktemp)
if [ "$kind" = url ]; then
curl --fail --location "$value" --output "$temporary"
else
printf '%s' "$value" | openssl base64 -d -A > "$temporary"
fi
case "$(file --brief --mime-type "$temporary")" in
image/png) extension=.png ;;
image/jpeg) extension=.jpg ;;
*) extension=.bin ;;
esac
mv "$temporary" "seedream-${index}${extension}"
done < <(jq -r '.data[] | if .error then ["error", (.error | tostring)] elif .url then ["url", .url] else ["b64", .b64_json] end | @tsv' "$response_file")
rm -f "$response_file"
```
```python
import base64
import json
import os
import urllib.error
import urllib.request
request = urllib.request.Request(
"https://api.vibelab.me/v1/images/generations",
data=json.dumps({
"model": "Doubao-seedream-4.5",
"prompt": "白底上的蓝色圆形图标",
"response_format": "url",
}).encode(),
headers={"Authorization": f"Bearer {os.environ['LOOPTOKEN_API_KEY']}", "Content-Type": "application/json"},
)
try:
with urllib.request.urlopen(request) as response:
body = json.load(response)
except urllib.error.HTTPError as error:
raise SystemExit(error.read().decode()) from error
for index, item in enumerate(body["data"], 1):
if "error" in item:
print(index, item["error"])
elif item.get("url"):
print(index, item["url"])
else:
raw = base64.b64decode(item["b64_json"])
extension = ".png" if raw.startswith(b"\x89PNG") else ".jpg"
open(f"seedream-{index}{extension}", "wb").write(raw)
```
```ts
import { writeFile } from 'node:fs/promises';
const response = await fetch('https://api.vibelab.me/v1/images/generations', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.LOOPTOKEN_API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
model: 'Doubao-Seedream-5.0-lite',
prompt: '白底上的蓝色圆形图标',
response_format: 'b64_json',
output_format: 'png',
}),
});
const body = await response.json();
if (!response.ok) throw new Error(JSON.stringify(body));
for (const [index, item] of body.data.entries()) {
if (item.error) console.error(index + 1, item.error);
else if (item.url) console.log(index + 1, item.url);
else {
const bytes = Buffer.from(item.b64_json, 'base64');
const extension = bytes.subarray(0, 4).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47])) ? 'png' : 'jpg';
await writeFile(`seedream-${index + 1}.${extension}`, bytes);
}
}
```
## 响应
非流式成功响应会原样透传。`data[]` 的顺序就是模型返回顺序；组图中单张审核失败时可出现 `error` 项，其他图片仍可能继续生成。模型服务异常可能终止后续图片。
URL 响应：
```json
{
"created": 1719820800,
"data": [
{"url": "https://example.com/generated/01.jpeg", "size": "2048x2048"}
],
"usage": {
"generated_images": 1,
"output_tokens": 16384,
"total_tokens": 16384
}
}
```
Base64 响应：
```json
{
"created": 1719820800,
"data": [
{"b64_json": "/9j/4AAQSkZJRgABAQ...", "size": "2048x2048"}
],
"usage": {"generated_images": 1, "output_tokens": 16384, "total_tokens": 16384}
}
```
| 字段 | 说明 |
| -------------------------------------- | ---------------------------------------------------------- |
| `created` | Unix 秒级时间戳 |
| `data[].url` | `response_format=url` 时返回的临时下载地址；请及时持久化 |
| `data[].b64_json` | `response_format=b64_json` 时返回的纯 Base64 字符串，不含 Data URL 前缀 |
| `data[].size` | 实际输出的 `<宽>x<高>` |
| `data[].error.code` / `message` | 单张失败信息 |
| `usage.generated_images` | 成功图片数，不含失败项 |
| `usage.output_tokens` / `total_tokens` | 图像输出用量 |
## 计费
* 三个模型均按图片计费，价格见[定价页](/pricing)。
* 请求提交时按正整数顶层 `n` 预扣，未传或非正数按 1。
* OpenAI 风格响应按 `data[]` 长度结算：只要 `data[]` 非空，`Count` 就等于数组项数，即使某项只有 `error`，或 URL/Base64 都为空，也会计入长度。
* 只有 2xx 响应的 `data[]` 缺失、为空或无法识别并得到 `Count=0` 时，才按提交数量结算；这里的提交数量是上述本地解析值。
* 模型服务非 2xx、没有可用服务资源或所有重试失败会全额退款。
* 不要用 `usage.generated_images` 推断 LoopToken 的最终扣费张数；`usage` 是模型服务用量，不是计费金额。
## 错误
错误体为统一信封（见[图片生成总览](/images#错误)）。本页特有或需注意的情形：
| HTTP | code | 触发场景 | 处理 |
| ---- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| 400 | `invalid_request` | 请求体不是合法 JSON，或 `model` 缺失（`invalid image generation request`） | 修正请求体 |
| 400 | `invalid_request` | 请求经 apimart 渠道转换时：`use either image or image_urls`、`image must be a URL or an array of URLs`、`image must contain at least one URL`、`image cannot contain empty URLs`、`invalid Seedream pixel size`、`size and resolution disagree`、`unsupported size for `、`unsupported resolution for ` | 按[请求参数](#请求参数)修正参考图与尺寸 |
| 502 | `upstream_error` | 模型服务拒绝参数、素材或内容；模型服务的非 2xx 错误不会原样暴露 | 有限退避重试；参数问题先修正 |
| 503 | `no_available_channel` | 当前没有可用服务资源；也可能出现在一次可重试失败之后 | 稍后重试 |
| 500 | `internal_error` | 计费、定价或请求构建异常 | 稍后重试 |
LoopToken 本地错误示例：
```json
{
"error": {
"message": "unknown model: example-model",
"type": "model_not_found",
"code": "model_not_found",
"request_id": "req_example"
}
}
```
成功 JSON 原样透传，LoopToken 不向响应体注入请求 ID；请求 ID 位于 `X-Request-Id` 响应头。
## 注意事项
* **传 `n`** → 不是 Seedream 官方的输出数量控制：LoopToken 读取正整数 `n` 仅用于预扣，组图上限使用 `sequential_image_generation_options.max_images`，不要混用。
* **`doubao-seedream-5.0-pro` 传 `n`、`response_format`** → 平台转发时忽略，固定生成一张并返回 URL。
* **4.0 / 4.5 传 `output_format`** → 仅 5.0 Lite 可传，4.0/4.5 不得传入。
* **`stream`** → 是模型服务能力，但尚无 LoopToken 实测结果，不属于本页稳定接口。
* **`seed`** → 没有当前官方接口证据，请勿依赖。
* **5.0 Lite 联网搜索工具** → 不在当前稳定兼容范围。
# Wan 图片系列
Source: https://looptoken.vibelab.me/docs/images/wan
> wan2.7-image / wan2.7-image-pro：扁平协议，支持文生图、编辑、参考图与序列生成，同步，响应为 OpenAI Images data[]
| 项 | 值 |
| ---- | --------------------------------------------------------- |
| 模型 | `wan2.7-image` / `wan2.7-image-pro` |
| 端点 | `POST /v1/images/generations` |
| 模式 | 同步；响应为 OpenAI Images 格式（`data[].url` 或 `data[].b64_json`） |
| 能力 | 文生图、编辑、参考图与序列生成 |
| 计费 | 按成功图片数，价格以[定价页](/pricing)为准，见[计费](#计费) |
| 媒体保留 | 结果图片 URL 为临时 URL，请立即下载并持久化 |
```text
POST https://api.vibelab.me/v1/images/generations
Authorization: Bearer
Content-Type: application/json
```
## 快速开始
```json
{
"model": "wan2.7-image-pro",
"prompt": "四季中的同一只橘猫，连续分镜",
"size": "2K",
"enable_sequential": true,
"n": 4
}
```
## 请求参数
`wan2.7-image` 和 `wan2.7-image-pro` 使用扁平扩展格式：顶层 `prompt`，参考图用 `image_urls`，其余选项也放在顶层。常用字段包括 `prompt`、`image_urls`、`n`、`size` / `resolution`、`negative_prompt`、`watermark`、`seed`、`thinking_mode` 和 `enable_sequential`。
| 模型 | 最高分辨率 |
| ------------------ | ----------------- |
| `wan2.7-image` | 2K |
| `wan2.7-image-pro` | 文生图 4K；编辑与序列生成 2K |
## 响应
响应为 OpenAI Images 格式（`data[].url` 或 `data[].b64_json`），见[图片生成总览](/images#响应)。图片 URL 是临时地址，请立即下载并持久化。
## 计费
* 按成功图片数计费，分辨率和宽高比不改变单张价格，价格见[定价页](/pricing)。
* 模型服务终止性非 2xx、网络失败、没有可用服务资源或重试耗尽，全额退款。
* `usage` 只表示模型服务用量，不是 credit 金额。
## 错误
错误体为统一信封（见[图片生成总览](/images#错误)）。本页特有或需注意的情形：
| HTTP | code | 触发场景 | 处理 |
| ---- | ---------------------- | ------------------------------------------------------------------- | -------------------------- |
| 400 | `invalid_request` | 请求体无法读取、JSON 截断或格式错误、`model` 缺失（`invalid image generation request`） | 修正请求体 |
| 502 | `upstream_error` | 参考图、尺寸、输出数量或安全策略校验失败，素材无效、内容拒绝或生成失败；模型服务错误码不保留 | 视为暂时不可完成，带抖动有限退避重试；参数问题先修正 |
| 503 | `no_available_channel` | 当前没有可处理请求的服务资源；一次可重试失败后若也无法继续处理，同一次请求也可能最终返回 503 | 带抖动有限退避重试 |
| 500 | `internal_error` | 计费或请求构建异常 | 稍后重试 |
502（`code: "upstream_error"`）与 503（`code: "no_available_channel"`）都会退款。成功的 2xx 响应原样返回，LoopToken 请求 ID 只位于 `X-Request-Id` 响应头。
## 注意事项
* **请求体大小** → 后端最多读取请求体前 20 MiB，超出后通常因 JSON 被截断返回 `invalid_request`。
* **图片 URL 为临时地址** → 立即下载并持久化。
# 操作详解
Source: https://looptoken.vibelab.me/docs/midjourney/actions
> Midjourney 16 个操作的端点、字段与父任务要求，含 blend/upscale/pan/zoom/inpaint/video
除 `imagine`/`blend`/`describe`/`edits`/`video` 外，以下操作都需要引用一个父任务（`task_id`），对父任务状态有明确要求。
* 父任务状态不满足要求 → 400 `invalid_request_error`。
* 父任务不存在或不属于当前账户 → 404 `task_not_found`。
全部端点鉴权、任务对象与状态见[接口说明](/midjourney)；价格以[定价页](/pricing)为准。
## 操作一览
| 操作 | 端点后缀 | 父任务要求 |
| ---------------------------------- | ----------------- | --------------------------- |
| [imagine](#imagine) | （无）或 `/imagine` | 无 |
| [blend](#blend) | `/blend` | 无 |
| [describe](#describe) | `/describe` | 无 |
| [edits](#edits) | `/edits` | 无 |
| [upscale](#upscale) | `/upscale` | `SUCCESS` |
| [variation](#variation) | `/variation` | `SUCCESS` |
| [high\_variation](#high_variation) | `/high-variation` | `SUCCESS`，通常是 upscale 单图 |
| [low\_variation](#low_variation) | `/low-variation` | `SUCCESS`，通常是 upscale 单图 |
| [reroll](#reroll) | `/reroll` | `SUCCESS`，四宫格 |
| [pan](#pan) | `/pan` | `SUCCESS`，upscale 单图 |
| [zoom](#zoom) | `/zoom` | `SUCCESS` |
| [inpaint](#inpaint) | `/inpaint` | `SUCCESS` |
| [modal](#modal) | `/modal` | `MODAL` |
| [remix\_strong](#remix_strong) | `/remix-strong` | `SUCCESS`，v8.1/v8.2 imagine |
| [remix\_subtle](#remix_subtle) | `/remix-subtle` | `SUCCESS`，v8.1/v8.2 imagine |
| [video](#video) | `/video` | 无（可选引用 `SUCCESS` imagine） |
端点前缀均为 `POST /v1/midjourney/generations`。
## imagine
生成入口，不需要父任务。完整字段（`prompt`/`speed`/`image_urls` 及结构化参数）见[接口说明](/midjourney#请求参数)。
## blend
将 2-4 张图片混合生成一组新的四宫格候选图。不需要父任务。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | -------------- | -- | -------- | ----------------------------------------------------------- |
| `image_urls` | array\ | 是 | - | 2-4 张图片 URL，单图 ≤ 12 MiB；少于 2 张或多于 4 张 → 400 |
| `dimensions` | string | 否 | `SQUARE` | 三档比例：`SQUARE`（1:1）/`PORTRAIT`（2:3）/`LANDSCAPE`（3:2） |
| `size` | string | 否 | - | 自由比例 `w:h`（如 `"16:9"`）；**同时传时 `size` 覆盖 `dimensions`** |
| `speed` | string | 否 | `relax` | `relax`/`fast`/`turbo` |
```bash
curl https://api.vibelab.me/v1/midjourney/generations/blend \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image_urls": ["https://example.com/a.png", "https://example.com/b.png"],
"speed": "fast"
}'
```
## describe
对图片反推提示词。不需要父任务。终态响应只有 `description` 字段，不返回任何媒体字段。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | -------------- | -- | ------- | -------------------------------- |
| `image_urls` | array\ | 是 | - | 至少 1 张图片 URL，多传只取第一张；单图 ≤ 12 MiB |
| `speed` | string | 否 | `relax` | `relax`/`fast`/`turbo` |
```bash
curl https://api.vibelab.me/v1/midjourney/generations/describe \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image_urls": ["https://example.com/a.png"]}'
```
* 上游通常 1-3 秒出结果，但**仍然是异步任务**：照常轮询到 `SUCCESS` 再取值，提交响应里没有文字。
* `description` 是四条带 `1️⃣2️⃣3️⃣4️⃣` 前缀、用 `\n` 分隔的候选提示词，每条自带 `--ar`/`--v` 之类的参数，可以直接作为 `imagine` 的 `prompt`。
## edits
图像编辑。不需要父任务。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | -------------- | -- | ------- | ---------------------- |
| `prompt` | string | 是 | - | 编辑指令 |
| `image_urls` | array\ | 是 | - | 待编辑的图片 URL，单图 ≤ 12 MiB |
| `speed` | string | 否 | `relax` | `relax`/`fast`/`turbo` |
[接口说明](/midjourney#结构化参数)里那组结构化参数（`size`/`version`/`stylize`/`raw` 等）在这里同样生效。
`edits` 与"`imagine` 带垫图"的区别：`edits` 是**改写这张图**（换背景、改风格、改内容），`imagine` 带 `image_urls` 是**参考这张图另画一张**。要保住原图主体就用 `edits`。
```bash
curl https://api.vibelab.me/v1/midjourney/generations/edits \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "把背景换成雪山",
"image_urls": ["https://example.com/a.png"]
}'
```
## upscale
对四宫格中的某一张图放大出图。**父任务要求：`SUCCESS`**。结果为单张图（`image_urls` 一个元素，无 `grid_image_url`）。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------- | ---- | -- | --------------------------------------------------- |
| `task_id` | string | 是 | - | 产出四宫格的父任务 ID |
| `index` | integer | 语义必填 | - | 选中的格位，`1`-`4`；决定操作四宫格中的哪张图。平台本层不强校验该字段，遗漏或非法值由上游判定 |
| `custom_id` | string | 否 | - | 取自父任务 `buttons` 中对应按钮的 `customId`；传了它就不按 `index` 匹配 |
```bash
curl https://api.vibelab.me/v1/midjourney/generations/upscale \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"task_id": "mj_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "index": 1}'
```
普通 `upscale` 是**从四宫格里切一张出来**，不做真实放大，所以毫秒级就 `SUCCESS`，也几乎不会失败。真正消耗算力的是上一步的 `imagine`。
### HD upscale（真实 2 倍放大）
执行真实放大，输出 2 倍高清单图，约 60-120 秒完成。拿到单图之后还要继续 `zoom`/`inpaint` 时，建议改走 HD upscale，后续精细操作更稳。用法：不传 `index`，改传对应版本的放大命令 `custom_id`。
| `customId` 命令 | 适用的 imagine 版本 |
| --------------------------------------------------- | -------------- |
| `upsample_v5_2x` / `upsample_v5_4x` | v5 |
| `upsample_v6_2x_subtle` / `upsample_v6_2x_creative` | v6 / v6.1 |
| `upsample_v7_2x_subtle` / `upsample_v7_2x_creative` | v7 |
```bash
curl https://api.vibelab.me/v1/midjourney/generations/upscale \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task_id": "mj_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"custom_id": "MJ::JOB::upsample_v7_2x_subtle::1::"
}'
```
HD upscale 与普通 upscale **同价**。但它救不了 `pan`，见 [pan](#pan)。
## variation
基于四宫格中的某一张图生成一组新的变体候选图（弱变体，等价 V1-V4）。**父任务要求：`SUCCESS`**。字段与 [upscale](#upscale) 一致（`task_id` + `index`，可用 `custom_id` 覆盖）。结果为新的四宫格（`grid_image_url` + `image_urls` 四个元素）。
`variation` 作用在**四宫格**上；`high_variation`/`low_variation` 作用在 **upscale 后的单图**上。三者不是强度递进的同一个东西，不要混用。
## high\_variation
强变化变体（"Vary Strong"），改动幅度大，构图和风格都可能变。字段与 [variation](#variation) 一致。**父任务要求：`SUCCESS`**，且父任务通常应是 [upscale](#upscale) 产出的单图任务。
不传 `custom_id` 时仍需传 `index`（`1`-`4`），尽管按钮匹配本身不使用它。
## low\_variation
弱变化变体（"Vary Subtle"），行为与 [variation](#variation) 完全一致，只是独立端点、独立计费 key。字段相同，**父任务要求：`SUCCESS`**，父任务通常应是 upscale 后的单图。
新接入直接用 `variation` 即可，这个端点是为命名对称保留的。
## reroll
用同一 prompt 重新生成一组四宫格候选图（等价 🔄 按钮）。整格重抽，**不需要 `index`**。**父任务要求：`SUCCESS`**。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------ | -- | -- | --------------------------------- |
| `task_id` | string | 是 | - | 父任务 ID |
| `custom_id` | string | 否 | - | 取自父任务 `buttons` 中对应按钮的 `customId` |
* 只能对 `imagine`（或 reroll 自身产出）的四宫格 reroll。已经做过 `upscale`/`variation`/`pan` 的任务不能 reroll。
* 父任务的 prompt、版本与结构化参数都会被继承，只有种子不同，所以出图不一样但风格一致。
## pan
向指定方向"接图"扩展画面：原图留在边缘，新方向补全内容。可以连续 pan 拼全景。**父任务要求：`SUCCESS`，且必须是 [upscale](#upscale) 产出的单图任务**；直接传四宫格会被上游拒绝（`This action requires an upscaled task...`）。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------- | -- | -- | ------------------------------------------------------------------- |
| `task_id` | string | 是 | - | 父任务 ID（upscale 后的单图） |
| `direction` | string | 是 | - | `left`/`right`/`up`/`down`；传了 `custom_id` 时可省 |
| `custom_id` | string | 否 | - | 直接指定 pan 按钮的 `customId`（`pan_left`/`pan_right`/`pan_up`/`pan_down`） |
| `index` | integer | 否 | - | `1`-`4`，选父任务第几张 |
```bash
curl https://api.vibelab.me/v1/midjourney/generations/pan \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"task_id": "mj_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "direction": "right"}'
```
**版本限制**：`pan` 只在 v6/v6.1/v7/v8.1/v8.2/niji6 上有效，v5.2 及更早会直接 `FAILURE`。用 HD upscale 产出的高清单图做 pan 一样会被拒，这是 Midjourney 对 pan 本身的限制，换放大方式解决不了。
## zoom
缩小视角（拉远扩图）：原图保留，向外补背景。**父任务要求：`SUCCESS`**。
引用方式有两种，按上游当时的行为择一，自动匹配失败时回落到第一种：
* **传 `custom_id`（经真实调用验证可用）**：`task_id` 指向产出四宫格的**原始** `imagine`（或 `blend`/`zoom` 等同样产出四宫格的）任务，`custom_id` 取自该任务响应 `buttons` 里的 `customId`。
* **让上游自动匹配**：`task_id` 指向 upscale 后的单图任务，用 `zoom_ratio` 选档，不传 `custom_id`。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | ------- | -- | --- | -------------------------------------------------------- |
| `task_id` | string | 是 | - | 见上方两种引用方式 |
| `custom_id` | string | 否 | - | 对应按钮的 `customId`（Midjourney 原生字符串，如 `MJ::Outpaint::...`） |
| `zoom_ratio` | number | 否 | - | 小于 `2` 匹配 `Zoom Out 1.5x`；未传或 `>= 2` 匹配 `Zoom Out 2x` |
| `index` | integer | 否 | `1` | `1`-`4` |
`zoom` 直接出图，**不进 `MODAL`**，只有 `inpaint` 需要两步。
```bash
curl https://api.vibelab.me/v1/midjourney/generations/zoom \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task_id": "mj_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"custom_id": "MJ::Outpaint::1::"
}'
```
## inpaint
局部重绘分两步提交：先 `inpaint` 提交重绘区域与新提示词，任务进入 `MODAL` 态；再调用 [modal](#modal) 确认继续，任务转回 `IN_PROGRESS` 并最终产出结果。**`inpaint` 提交免费，真正的计费发生在 `modal` 步骤**（见[计费](/midjourney#计费)）。
**父任务要求：`SUCCESS`**；与 [zoom](#zoom) 一样必须引用原始产出四宫格的任务并传对应的 `custom_id`。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------ | -- | -- | ----------------------------------------------------- |
| `task_id` | string | 是 | - | 原始产出四宫格的任务 ID |
| `custom_id` | string | 是 | - | 取自父任务 `buttons` 中对应按钮的 `customId`（`MJ::Inpaint::...`） |
| `mask_url` | string | 见下 | - | 蒙版图片 URL；**透明区域 = 需要重绘的区域** |
| `prompt` | string | 见下 | - | 重绘区域的新提示词 |
**`mask_url` 和 `prompt` 放哪一步**：实测走通的是在 `inpaint` 这步带上（上表写法）。上游文档另有一种口径：`inpaint` 只传 `task_id`（服务端自动匹配 `Vary (Region)` 按钮），把 `mask_url` + `prompt` 留到 `modal` 那步提交。两种都会到达上游，拿不准就先按上表来，失败了再把这两个字段挪到 `modal`。
蒙版要求：PNG 透明背景（也接受 `data:image/png;base64,...`），建议与父图同分辨率，≤ 12 MiB，URL 必须公网可达（内网地址会被 SSRF 拦截）。
```bash
curl https://api.vibelab.me/v1/midjourney/generations/inpaint \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task_id": "mj_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"custom_id": "MJ::Inpaint::1::",
"mask_url": "https://example.com/mask.png",
"prompt": "add a hat"
}'
# => 202,任务随后进入 MODAL 态
```
轮询 `GET /v1/midjourney/{task_id}`，直到 `status` 变为 `MODAL` 再进行第二步。
**`MODAL` 态有时限**：约 30 分钟内未提交 `modal`，任务会被取消并退款（平台本地兜底上限为任务创建后 35 分钟）。不要把 `MODAL` 当成失败重试，它是等你补参的正常中间态。
## modal
`inpaint` 的第二步。**父任务要求：`MODAL`**（而非 `SUCCESS`）。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------ | -- | -- | ------------------------------------------------ |
| `task_id` | string | 是 | - | 处于 `MODAL` 态的父任务 ID（即上一步 `inpaint` 的 `task_id`） |
| `custom_id` | string | 否 | - | 视上游需要传递 |
| `prompt` | string | 否 | - | 重绘提示词；留空继承父任务 prompt。若 `inpaint` 那步没传，在这里补 |
| `mask_url` | string | 否 | - | 蒙版 URL。**有蒙版走局部重绘，没有则走外扩**。若 `inpaint` 那步没传，在这里补 |
`speed` 不用在这步传：计费档位按 `inpaint` 提交时锁定的速度算，这步传了也不生效。
```bash
curl https://api.vibelab.me/v1/midjourney/generations/modal \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"task_id": "mj_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}'
# => 202,复用同一 task_id;继续轮询直到 SUCCESS
```
* `modal` 提交成功后，继续用同一个 `task_id` 轮询，最终 `SUCCESS` 时返回新的四宫格（`grid_image_url` + `image_urls` 四个元素）。
* 对同一 `task_id` 重复提交 `modal`（重复计费请求）→ 409 `invalid_request_error`。
## remix\_strong
v8 操作面板的"重塑"：把父图重新生成一遍，可以换 prompt。强幅度，构图和风格都可能变。**父任务要求：`SUCCESS`，且必须是 v8.1 / v8.2 的 imagine 任务**；v7/v6 的父图会被拒，那些版本请改用 [variation](#variation) / [high\_variation](#high_variation)。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------- | -- | -- | --------------------------------- |
| `task_id` | string | 是 | - | 父任务 ID（v8.1/v8.2 imagine） |
| `index` | integer | 是 | - | 选父图第几张做重塑，`1`-`4` |
| `custom_id` | string | 否 | - | 取自父任务 `buttons` 中对应按钮的 `customId` |
| `prompt` | string | 否 | - | 重塑用的新提示词；留空继承父图 prompt |
v8 面板去掉了 U1-U4 / zoom / outpaint / inpaint。对应替代：选图变化用 variation 系列，重塑用本端点，重抽用 [reroll](#reroll)。
## remix\_subtle
弱幅度重塑，保持主体与色调。字段与 [remix\_strong](#remix_strong) 一致，同样**仅 v8.1 / v8.2 父图可用**。
## video
图生视频，约 5 秒。**必须给首帧**：`task_id` 或 `image_urls` 二选一，两个都不给或都给都是 400。不支持纯文生视频。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | -------------- | --- | ----------------- | ------------------------------------------------ |
| `task_id` | string | 二选一 | - | 引用的父任务 ID（`SUCCESS` 的 imagine），用它的图作首帧 |
| `image_urls` | array\ | 二选一 | - | 直接给首帧图 URL（1 张，≤ 12 MiB） |
| `index` | integer | 否 | - | 配合 `task_id`，选四宫格第几张作首帧（`0`-`3`） |
| `prompt` | string | 否 | - | 镜头运动/动作描述；留空继承父任务 prompt |
| `end_url` | string | 否 | - | 结束帧 URL。传了它，`video_type` 会自动升级成对应的 `start_end_*` |
| `video_type` | string | 否 | `vid_1.1_i2v_480` | 见下表 |
| `animate_mode` | string | 否 | `manual` | `manual`/`auto`；`auto` 必须同时给 `task_id` + `index` |
| `motion` | string | 否 | `high` | `low`/`high`，运动幅度，**不影响计费** |
| `batch_size` | integer | 否 | `1` | `1`/`2`/`4`；**计费 = 单价 × `batch_size`** |
`video_type` 只接受这四个值：
| 值 | 分辨率 | 说明 | 计费档 |
| --------------------------- | ---- | ---------------------- | ------ |
| `vid_1.1_i2v_480` | 480p | 默认 | 480p 档 |
| `vid_1.1_i2v_720` | 720p | | 720p 档 |
| `vid_1.1_i2v_start_end_480` | 480p | 起止帧（传 `end_url` 时自动升级） | 480p 档 |
| `vid_1.1_i2v_start_end_720` | 720p | 起止帧 | 720p 档 |
* `video` 固定走 FAST 通道，**没有 speed 维度**：传 `speed` 不改变价格也不改变排队。
* `SUCCESS` 后 `video_urls` 的元素个数等于 `batch_size`。
```bash
curl https://api.vibelab.me/v1/midjourney/generations/video \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task_id": "mj_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"index": 1,
"batch_size": 1
}'
# => 202;SUCCESS 后返回 video_urls
```
起止帧过渡（给了 `end_url`，不用手动改 `video_type`）：
```bash
curl https://api.vibelab.me/v1/midjourney/generations/video \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "日出平滑过渡到日落",
"image_urls": ["https://example.com/sunrise.jpg"],
"end_url": "https://example.com/sunset.jpg",
"video_type": "vid_1.1_i2v_720"
}'
```
## 错误
各操作共用的错误（`400` 参数或父任务状态不符、`404 task_not_found`、`409` 重复 `modal`、`422` 内容审核等）见[接口说明的错误](/midjourney#错误)。
# 接口说明
Source: https://looptoken.vibelab.me/docs/midjourney
> midjourney：异步任务协议，提交 imagine 与 16 种二次操作，用 GET /v1/midjourney/{task_id} 轮询，状态 SUCCESS / FAILURE
Midjourney 是围绕"生成 → 查询 → 对结果做二次操作"的异步任务协议。鉴权方式与其他接口一致，见[鉴权](/authentication)。本页是协议总览，各操作的字段与父任务要求见[操作详解](/midjourney/actions)。
| 项 | 值 |
| ---- | ----------------------------------------------------------------------------------------------- |
| 模型 | `midjourney` |
| 模式 | 异步：提交返回 `202` 和 `task_id` → 轮询 [`GET /v1/midjourney/{task_id}`](#响应) → 终态 `SUCCESS` 或 `FAILURE` |
| 中间态 | 部分操作先进入 `MODAL`，需再提交一次才能继续 |
| 计费 | 按操作与 `speed` 档位，失败全额退款（见[计费](#计费)），价格以[定价页](/pricing)为准 |
| 媒体保留 | 图片 90 天、视频 72 小时（见[结果有效期](#结果有效期)） |
## 模式选择
按目标选择操作：
```text
imagine(生成)
└─ SUCCESS → 四宫格 grid_image_url + buttons
├─ upscale / variation / high_variation / low_variation(引用 index 或 buttons 中的 custom_id)
├─ reroll / pan / zoom(引用 buttons 中的 custom_id)
├─ remix_strong / remix_subtle
├─ inpaint → MODAL → modal(局部重绘,两步流程)
└─ video(把某一张结果做成视频)
```
只有\*\*原始 imagine（或 blend/zoom/reroll 等同样产出新一组四宫格候选图的任务）\*\*的查询响应才带 `buttons` 数组；`upscale`/`variation` 等选中单张图的结果不带 `buttons`。用 `custom_id` 引用二次操作时，必须从产出该四宫格的那个任务的响应里取，不能从 `upscale` 之类的下游结果里取。
全部 16 个操作端点的字段、父任务要求与示例见[操作详解](/midjourney/actions)。
## 快速开始
两个路径等价。
```bash
curl https://api.vibelab.me/v1/midjourney/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "a cat in a spacesuit --ar 16:9"}'
```
提交成功返回 `202`，`data[0].task_id` 即后续轮询用的任务 ID：
```json
{"code": 200, "data": [{"task_id": "mj_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "submitted"}]}
```
轮询：
```bash
curl https://api.vibelab.me/v1/midjourney/mj_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
字段见[响应](#响应)。
## 请求参数
### imagine 基础参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | -------------- | -- | ------- | ----------------------------------------------------------------------- |
| `prompt` | string | 是 | - | 生成提示词；传统 Midjourney `--` 参数（如 `--ar 16:9`）可以直接写在 `prompt` 文本里，已通过真实调用验证 |
| `speed` | string | 否 | `relax` | `relax` / `fast` / `turbo`；决定排队优先级与计费档位，见"计费" |
| `image_urls` | array\ | 否 | - | 参考图 URL（图生图/风格参考等），数量与效果取决于具体用法；单图 ≤ 12 MiB |
| `nsfw_check` | boolean | 否 | `false` | `true` 时在提交生成前先对提示词与输入图做内容审核，拦截更早，但增加一次审核开销与延迟 |
| `metadata` | object | 否 | - | 自定义元数据，随任务保存并原样返回，便于业务侧串联自己的订单/会话 ID |
### 结构化参数
作为 `--` 前缀写法的等价 JSON 字段透传给上游。平台本身不校验取值范围，非法值由上游处理。仅在 `prompt` 文本内联写 `--ar` 经过真实调用验证；以下结构化字段建议优先用于替代对应的 `--` 写法，与 `prompt` 内联写法冲突时以上游实际行为为准。
| 参数 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------------- |
| `size` | string | 画面比例（宽:高），如 `"1:1"`、`"16:9"`、`"9:16"`、`"4:3"`、`"3:4"` |
| `version` | string | 模型版本，如 `"6.1"`、`"7"`，见下方"版本与 Niji" |
| `niji` | boolean | `true` 时使用 Niji（动漫风格）模型而非标准模型 |
| `quality` | string | 渲染质量/细节程度档位 |
| `stylize` | integer | 风格化强度，范围 `0`-`1000`，默认 `100` |
| `chaos` | integer | 结果多样性/随机程度，范围 `0`-`100`，默认 `0` |
| `weird` | integer | 怪异度，范围 `0`-`3000`，默认 `0` |
| `tile` | boolean | `true` 时生成可无缝平铺的图案 |
| `seed` | integer | 随机种子，用于复现同一结果 |
| `negative_prompt` | string | 反向提示词，描述需要避免出现的内容 |
| `style` | string | 风格档位，如 `"raw"`；与 `raw` 布尔字段是**两个不同的 flag**（`--style raw` 与 `--raw`） |
| `iw` | number | 参考图权重（image weight），范围 `0`-`3`，影响 `image_urls` 相对文本提示词的影响力 |
| `cref` | string | 角色参考图 URL，用于保持角色形象一致 |
| `cw` | integer | 角色参考权重，范围 `0`-`100` |
| `sref` | string | 风格参考图 URL |
| `sw` | integer | 风格参考权重，范围 `0`-`1000` |
| `dref` | string | 深度参考图 URL |
| `dw` | integer | 深度参考权重，范围 `0`-`100` |
| `repeat` | integer | 重复生成次数，范围 `2`-`40`；**每一次重复都单独计费** |
| `raw` | boolean | 原始风格（`--raw`），减少 Midjourney 的后期加工；v5.1 起支持 |
| `draft` | boolean | 草图模式（`--draft`），更快、清晰度更低；v7 起支持 |
| `hd` | boolean | 高清模式（`--hd`），仅 v8.1/v8.2；未同时传 `version` 时上游会自动补 `--v 8.1` |
| `stop` | integer | 在指定进度提前停止，范围 `10`-`100`，仅 v5-v6.1 与 niji 5-6 |
| `extra` | string | 逃生口：原样追加到 prompt 末尾，用于本表尚未覆盖的新 `--` flag |
### 版本与 Niji
* `version` 传主版本号字符串。当前上游可用：`"8.2"`、`"8.1"`、`"7"`、`"6.1"`、`"5.2"`、`"5.1"`。
* 用 Niji（动漫模型）：传 `niji: true` 加 `version: "7"` 或 `"6"`，上游会归一化为 Niji 7 / Niji 6。不要只传 `niji: true` 而不给版本。
* 版本会影响哪些操作可用：`pan` 只在 v6/v6.1/v7/v8.1/v8.2/niji6 上有效，`remix_strong`/`remix_subtle` 只在 v8.1/v8.2 上有效。详见[操作详解](/midjourney/actions)。
* 版本不影响价格，各版本同档同价。
## 请求示例
### Niji 竖图
```json
{"prompt": "anime girl in a moonlit garden", "niji": true, "version": "7", "size": "9:16"}
```
## 响应
`task_id` 为提交响应中的值（`mj_` 前缀 + UUID）。任务不存在、或不属于当前 API Key 所在账户 → 404 `task_not_found`。查询响应直接是任务对象，不套 `{"code", "data"}` 外壳。
### 状态机
| 状态 | 含义 |
| ------------- | -------------------------------------------------------------------------------------------- |
| `SUBMITTED` | 已提交，排队中 |
| `IN_PROGRESS` | 生成中 |
| `MODAL` | 需要客户端补充信息才能继续（目前仅 `inpaint` 会进入此态），调用 [modal](/midjourney/actions#modal) 提交后转回 `IN_PROGRESS` |
| `SUCCESS` | 已完成 |
| `FAILURE` | 失败 |
响应示例（`SUCCESS`，四宫格）：
```json
{
"id": "mj_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"action": "IMAGINE",
"status": "SUCCESS",
"progress": "100%",
"prompt": "a cat in a spacesuit --ar 16:9",
"created_at": 1789041600,
"completed_at": 1789041660,
"credits_charged": 0.58552,
"grid_image_url": "https://...",
"image_urls": ["https://...", "https://...", "https://...", "https://..."],
"buttons": [{"customId": "MJ::JOB::upsample::1::..."}]
}
```
### 任务对象字段
所有状态都包含：
| 字段 | 类型 | 说明 |
| ------------ | ------- | ---------------------------------------- |
| `id` | string | `mj_` 前缀 + UUID |
| `action` | string | 大写下划线形式的操作名，如 `IMAGINE`、`HIGH_VARIATION` |
| `status` | string | 见状态机 |
| `progress` | string | 形如 `"56%"` 的进度 |
| `prompt` | string | 提交时使用的提示词 |
| `created_at` | integer | 任务创建时间，Unix 秒 |
进入终态后追加：
| 字段 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------------------------------- |
| `completed_at` | integer | 任务结束时间，Unix 秒 |
| `credits_charged` | number | 本次实际扣费（积分） |
| `buttons` | array | 可用于后续二次操作的按钮列表（`customId` 为 Midjourney 原生字符串，直接透传）；仅原始 imagine 类（产出新一组四宫格候选图的）任务才有此字段 |
`SUCCESS` 时，按操作类型追加以下之一：
| 操作 | 追加字段 |
| --------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `describe` | 仅 `description`（反推的提示词文本），不返回任何媒体字段 |
| 产出新一组四宫格的操作：`imagine`/`blend`/`zoom`/`reroll`/`pan`/`variation` 系列/`remix` 系列/`inpaint→modal` 的最终结果 | `grid_image_url`（四宫格预览图）+ `image_urls`（数组，四张单图） |
| 产出单张图的操作（如 `upscale`） | 仅 `image_urls`（数组，一张） |
| `video` | 仅 `video_urls`（数组） |
`FAILURE` 时追加：
| 字段 | 类型 | 说明 |
| ------------- | ------ | ------ |
| `fail_reason` | string | 失败原因文案 |
### 结果有效期
生成结果会被平台转存到自有对象存储并签发可直接访问的 URL（`grid_image_url`/`image_urls`/`video_urls`），不依赖上游链接的时效：
| 类型 | 有效期 |
| -- | --------------- |
| 图片 | 任务完成后 90 天内可访问 |
| 视频 | 任务完成后 72 小时内可访问 |
响应中不返回单独的过期时间字段，请在拿到 `SUCCESS` 结果后尽快下载并自行转存，不要长期依赖返回的链接。
## 计费
单位为积分（credits）。
| 操作 | relax | fast | turbo |
| --------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------- | ----- |
| `imagine` | 0.58552 | 0.71552 | 1.3 |
| 其余全部操作（`blend`/`describe`/`edits`/`upscale`/`variation`/`high_variation`/`low_variation`/`reroll`/`pan`/`zoom`/`remix_strong`/`remix_subtle`） | 0.71552 | 0.71552 | 1.3 |
| `inpaint` | 0（免费提交） | 0 | 0 |
| `modal` | 1.43104 | 1.43104 | 2.6 |
| `video`（480p 档） | 2.6（与 speed 无关） | 2.6 | 2.6 |
| `video`（720p 档） | 5.2（与 speed 无关） | 5.2 | 5.2 |
* `inpaint` 单独提交不计费，真正的局部重绘发生在随后的 `modal` 步骤，`modal` 档位已包含 `inpaint`+`modal` 两步的合计成本。
* `video` 的最终扣费 = 表中单价 × `batch_size`（可选 `1`/`2`/`4`）。`batch_size: 4` 就是实扣 4 份：720p 批量 4 段一次要 20.8 积分，比 480p 单段的 2.6 贵 8 倍。只要一段就传 `1`。
* `video_type` 含 `720` 时走 720p 档，其余走 480p 档。
* `repeat`（2-40）同样按次数倍增扣费，与 `batch_size` 是两个独立的乘数。
* 任务失败（`FAILURE`）自动全额退款，退款与终态判定同步完成，无需额外操作。
* 以上价格以[定价页](/pricing)和任务终态中的 `credits_charged` 为准。
## 注意事项
**`upscale` 不是放大。** 它是从四宫格里把第 N 张切出来，本地合成、毫秒返回、几乎不会失败，真正烧算力的是上一步 `imagine`。要真正的 2 倍高清图，走 [HD upscale](/midjourney/actions#upscale)（60-120 秒的真实放大）。两者同价。
**`MODAL` 不是失败。** 它是 `inpaint` 之后等你补参数的正常中间态，轮询到它就去调 `modal`，不要重试 `inpaint`。**约 30 分钟内不补参，任务会被自动取消并退款**（平台本地兜底上限为任务创建后 35 分钟）。
* **`variation` 和 `high_variation` 不是"弱一点/强一点"的同一个操作** → `variation` 作用在四宫格上（等价 V1-V4），`high_variation`/`low_variation` 作用在 upscale 之后的单图上；父任务给错，上游会拒。
* **`inpaint` 免费不等于局部重绘免费** → `inpaint` 那步是 0，但上游对 inpaint 和 modal 分别计费两次，两步的钱一起算在 `modal` 档里（1.43104，正好是单步的两倍）。走完一轮局部重绘的成本和做两次普通操作一样。
* **`video` 的 `batch_size` 是实打实的乘数** → 传 `4` 就扣 4 份；出片只要一段就传 `1`，比稿才用 4。
* **`speed` 对 `video` 无效** → `video` 固定走 FAST 通道，传 `relax` 或 `turbo` 既不改价也不改排队；`speed` 只对生图类操作生效。
* **`--raw` 和 `style: "raw"` 是两个不同的 flag** → 前者对应 `raw: true`，后者对应 `style: "raw"`，想要哪个效果就传哪个，不要互相替代。
* **`pan` 挑版本** → 只在 v6/v6.1/v7/v8.1/v8.2/niji6 上有效，v5.2 及更早直接 `FAILURE`；它只吃 upscale 后的单图，连 HD upscale 的高清单图也被拒，这是 Midjourney 自身的限制。
## 错误
错误体与[错误码](/errors)相同：`{"error": {"message", "type", "code", "request_id"}}`（`type` 与 `code` 相同）。本接口常见错误：
| HTTP | code | 触发场景 | 处理 |
| ----- | ---------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `400` | `invalid_request_error` | 请求体不合法（缺少必填字段、`speed`/`batch_size` 不在允许枚举、`pan` 缺少合法 `direction`、需要父任务的操作缺少或传错 `task_id`、父任务状态不满足要求） | 按 `message` 修正；父任务要求见[操作详解](/midjourney/actions) |
| `402` | `insufficient_credits` | 账户余额不足以覆盖预扣费用 | 充值后重试 |
| `404` | `not_found_error` | 操作端点后缀不存在 | 核对[操作详解](/midjourney/actions)的端点 |
| `404` | `task_not_found` | 提交时引用的父任务不存在或不属于当前账户；或查询时 `task_id` 不存在/不属于当前账户 | 核对 `task_id`（`mj_` 前缀 + UUID） |
| `404` | `model_not_found` | `midjourney` 没有可售价格 | 联系支持 |
| `409` | `invalid_request_error` | 对同一 `task_id` 重复提交 `modal`（重复计费冲突），或父任务状态在校验后发生变化 | 不要重复提交，改为轮询 |
| `422` | `invalid_request_error` | 内容审核拒绝（`message` 为 `content moderation rejected`） | 修改提示词或图片 |
| `429` | `media_concurrency_exceeded` | 用户或 API Key 的媒体并发超限（带 `Retry-After`） | 稍后重试 |
| `502` | `upstream_error` | 上游提交失败且重试耗尽 | 指数退避重试，预扣费用会退回 |
| `503` | `no_available_channel` | 该模型当前没有可用渠道 | 指数退避重试 |
上游返回的其它 4xx 会按原状态码返回，`code` 为 `invalid_request_error`、`message` 为 `upstream request failed`。
# Grok Imagine 1.5 Video
Source: https://looptoken.vibelab.me/docs/video/grok-video
> grok-imagine-1.5-video：文生/图生视频，6–30 秒、480p/720p，异步，按秒计费，用 GET /v1/tasks/{task_id} 查询
Grok Imagine 通过 `/v1` 统一异步视频接口调用。提交、轮询、任务对象与错误见[接口说明](/video)。
| 项 | 值 |
| ---- | ------------------------------------- |
| 模型 | `grok-imagine-1.5-video` |
| 模式 | 异步（提交 → 轮询 `GET /v1/tasks/{task_id}`） |
| 计费 | 按实际生成秒数，`480p` 与 `720p` 同价，见[计费](#计费) |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时 |
时长 `6-30` 秒（默认 `6`），质量档位 `480p`、`720p`（默认 `480p`）。
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-1.5-video",
"prompt": "一架纸飞机缓缓滑过安静的工作室，光线柔和",
"quality": "480p",
"duration": 6
}'
```
提交成功返回 HTTP `202` 和任务对象：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "grok-imagine-1.5-video",
"status": "pending",
"created_at": 1772942400,
"duration": 6,
"resolution": "480p"
}
```
查询任务：
```bash
curl https://api.vibelab.me/v1/tasks/vt_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
## 模式选择
| 模式 | 怎么传参 |
| ---- | ----------------- |
| 文生视频 | 只传 `prompt` 与控制字段 |
| 图生视频 | 加 `image_urls` |
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | --------- | -- | ------ | ---------------------------- |
| `model` | string | 是 | - | 固定为 `grok-imagine-1.5-video` |
| `prompt` | string | 是 | - | 视频内容描述 |
| `quality` | string | 否 | `480p` | `480p` 或 `720p` |
| `duration` | integer | 否 | `6` | `6`–`30` 秒 |
| `image_urls` | string\[] | 否 | - | 图生视频参考图 URL，最多 `7` 张，必须公网可访问 |
| `callback_url` | string | 否 | - | 任务到达终态后的 HTTPS 回调地址 |
## 请求示例
图生视频：
```json
{
"model": "grok-imagine-1.5-video",
"prompt": "画面中的纸飞机缓缓起飞",
"quality": "720p",
"duration": 10,
"image_urls": ["https://example.com/plane.jpg"]
}
```
## 响应
用 `GET /v1/tasks/{task_id}` 查询，状态依次为 `pending` → `running` → `succeeded` / `failed`（终态）。
| 字段 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------------------- |
| `status` | string | `pending`、`running`、`succeeded`、`failed` |
| `video_url` | string | 视频下载地址，仅 `succeeded` 返回，尽快转存 |
| `expires_at` | integer | `video_url` 失效时间，Unix 秒 |
| `credits_charged` | number | 本次实际扣费（积分） |
| `error` | object | 仅 `failed` 返回：`{"code": "timeout" \| "upstream_error", "message": "..."}` |
完整任务对象字段与示例见[接口说明](/video#任务对象字段)。
## 计费
`grok-imagine-1.5-video` 按实际生成时长（秒）计费，`480p` 与 `720p` 同价，约 `0.096` 积分/秒。提交时按请求 `duration` 预扣，任务结束后按实际时长结算，多退少补；失败全额退回。精确价格与实时变动以[定价页](/pricing)为准。
## 错误
通用错误见[接口说明](/video#错误)。本模型提交时的参数校验返回 `400 invalid_request_error`：
| `message` | 处理 |
| ----------------------------------- | --------------------------- |
| `quality must be one of 480p/720p` | `quality` 传 `480p` 或 `720p` |
| `duration must be between 6 and 30` | 时长传 `6`–`30` |
## 注意事项
* **顶层 `resolution`** → 不参与档位选择（预扣与校验只读 `quality`），用 `quality` 选择质量档位。
# 接口说明
Source: https://looptoken.vibelab.me/docs/video
> 视频生成 /v1 统一异步协议：POST /v1/videos/generations 提交，GET /v1/tasks/{task_id} 轮询任务对象，支持 callback_url 回调
视频生成耗时通常数十秒到数分钟，接口采用**平台自定义的异步两步协议**，不是 OpenAI 官方接口。本页是所有使用 `/v1` 的视频模型的公共协议，各模型页只写差异。
| 项 | 值 |
| ---- | ------------------------------------------------------------------------------------------ |
| 模型 | 见[模型系列](#模型系列)，`model` 字段传平台模型 ID |
| 模式 | 异步（`POST /v1/videos/generations` 提交 → 轮询 `GET /v1/tasks/{task_id}`，或用 `callback_url` 接收回调） |
| 计费 | 提交时预扣，终态按实际结果多退少补，失败退回，见[计费](#计费) |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时，见[响应](#响应) |
[Seedance 方舟原生接口](/video/seedance-ark)使用 `/api/v3/contents/generations/tasks`，提供创建、单任务查询和本地任务列表。[Seedance 方舟原生素材库版](/video/seedance-native-assets)是独立模式，使用 `/hub/api/v3/contents/generations/tasks`，提供 v3 视频接口、素材库和真人认证。快手可灵 3.0 系列使用与官方一致的原生接口，见 [Kling 3.0原生接口](/video/kling)。本页描述 `/v1` 协议。
## 快速开始
| 步骤 | 说明 |
| ------ | -------------------------------------------------------------------------- |
| 1. 提交 | `POST /v1/videos/generations`，立即返回 `202` 和任务对象（`status: pending`） |
| 2. 轮询 | `GET /v1/tasks/{task_id}`，建议间隔 5-10 秒，直到 `status` 为 `succeeded` 或 `failed` |
| 3. 取结果 | `succeeded` 读 `video_url`；`failed` 读 `error` |
请求头：`Authorization: Bearer $LOOPTOKEN_API_KEY`、`Content-Type: application/json`。请求体上限 10 MiB（不是素材文件大小限制）。
curl
Python
Node.js
```bash
# 1. 提交任务
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-0-fast-260128",
"content": [{"type": "text", "text": "海边日落,海浪拍打礁石 --duration 5 --resolution 720p"}]
}'
# => 202 {"task_id":"vt_...","status":"pending","progress":0,...}
# 2. 用返回的 task_id 轮询,间隔建议 5-10 秒
curl https://api.vibelab.me/v1/tasks/vt_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
```python
import time
import requests
BASE_URL = "https://api.vibelab.me"
API_KEY = "sk-lt-..."
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
# 1. 提交任务
resp = requests.post(
f"{BASE_URL}/v1/videos/generations",
headers=headers,
json={
"model": "doubao-seedance-2-0-fast-260128",
"content": [{"type": "text", "text": "海边日落,海浪拍打礁石 --duration 5 --resolution 720p"}],
},
)
resp.raise_for_status()
task = resp.json()
task_id = task["task_id"]
print("submitted:", task_id, task["status"])
# 2. 轮询直到终态(最长等 15 分钟)
deadline = time.monotonic() + 15 * 60
while True:
if time.monotonic() > deadline:
raise TimeoutError(f"task {task_id} not finished within 15 minutes")
time.sleep(8)
resp = requests.get(f"{BASE_URL}/v1/tasks/{task_id}", headers=headers)
resp.raise_for_status()
task = resp.json()
print("status:", task["status"])
if task["status"] == "succeeded":
print("video_url:", task["video_url"])
print("expires_at:", task["expires_at"])
break
if task["status"] == "failed":
print("error:", task["error"])
break
```
```ts
const BASE_URL = 'https://api.vibelab.me';
const API_KEY = 'sk-lt-...';
const headers = {
Authorization: `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
};
async function requestJSON(url, init) {
const resp = await fetch(url, init);
if (!resp.ok) {
throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
}
return resp.json();
}
async function main() {
// 1. 提交任务
let task = await requestJSON(`${BASE_URL}/v1/videos/generations`, {
method: 'POST',
headers,
body: JSON.stringify({
model: 'doubao-seedance-2-0-fast-260128',
content: [{ type: 'text', text: '海边日落,海浪拍打礁石 --duration 5 --resolution 720p' }],
}),
});
const taskId = task.task_id;
console.log('submitted:', taskId, task.status);
// 2. 轮询直到终态(最长等 15 分钟)
const deadline = Date.now() + 15 * 60 * 1000;
while (true) {
if (Date.now() > deadline) {
throw new Error(`task ${taskId} not finished within 15 minutes`);
}
await new Promise((r) => setTimeout(r, 8000));
task = await requestJSON(`${BASE_URL}/v1/tasks/${taskId}`, { headers });
console.log('status:', task.status);
if (task.status === 'succeeded') {
console.log('video_url:', task.video_url);
console.log('expires_at:', task.expires_at);
break;
}
if (task.status === 'failed') {
console.log('error:', task.error);
break;
}
}
}
main();
```
## 模式选择
### 模型系列
使用 `/v1` 的视频模型共用本页的异步协议与任务对象，但**提交请求体的形状和参数规则因系列而异**。不能把一个系列的参数规则套用到另一个系列。
| 系列 | 请求体形状 | 当前模型 |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [主流视频模型](/video/mainstream) | 统一扁平字段：`prompt`、`duration`、`resolution`、`mode`、`audio`、`aspect_ratio`、`image_urls`、`first_frame_image` | `sora-2`、`sora-2-pro`、`veo3.1-fast`、`veo3.1-quality`、`veo3.1-lite`、`MiniMax-Hailuo-2.3`、`minimax-h3` |
| [Seedance 系列](/video/seedance) | 方舟风格：顶层参数 + `content` 多模态数组 | `doubao-seedance-2-5-cloud`、`seedance-2-5-max`、`seedance-2-5-hig`、`seedance-2-0-hig`、`seedance-2-5-duo`、`seedance-2-0-duo`、`seedance-2-0-fast-duo`、`seedance-2-0-mini-duo`、`doubao-seedance-2-0-260128`、`doubao-seedance-2-0-fast-260128`、`doubao-seedance-2-0-mini-260615`、`seedance-2.5-c`、`seedance-2.5-c1`、`seedance-2.5-c2`、`seedance-2.5-c7`、`seedance-2.0-c` |
| [Wan 视频系列](/video/wan) | DashScope 风格：`input.prompt`/`input.media` + `parameters` | `wan3.0-video`、`wan3.0-video-prime` |
| [Grok Imagine Video](/video/grok-video) | 统一扁平字段：`prompt`、`quality`、`duration`、`image_urls` | `grok-imagine-1.5-video` |
| [SkyReels V4](/video/skyreels) | 统一扁平字段：`prompt`、`resolution`、`duration`、`image_urls`、`ref_images`、`ref_videos` | `skyreels-v4-fast`、`skyreels-v4-std` |
| [Pixverse v6](/video/pixverse) | 统一扁平字段：`prompt`、`resolution`、`duration`、`image_urls`、`audio` | `pixverse-v6` |
| [Vidu Q3 系列](/video/vidu) | 统一扁平字段：`prompt`、`resolution`、`duration`、`image_urls` | `viduq3`、`viduq3-mix`、`viduq3-pro`、`viduq3-turbo` |
| [Omni Flash 系列](/video/omni-flash) | 统一扁平字段：`prompt`、`resolution`/`duration`（`omni-flash-ext`）；`gemini-omni-flash-preview` 仅需 `prompt` | `omni-flash-ext`、`gemini-omni-flash-preview` |
### 选型对照
本表只列非 Seedance 系列的模型，Seedance 见[Seedance 系列](/video/seedance)。
| 模型 | 输入 | 时长 | 分辨率 / 档位 | 计费方式 |
| ------------------------------------------------- | ---------------- | --------------------------- | -------------------------------------------- | ----------------------- |
| `sora-2` | 文生、图生（1 张） | `4`/`8`/`12`/`16`/`20` 秒 | `720p` | 见[定价页](/pricing) |
| `sora-2-pro` | 文生、图生（1 张） | `4`/`8`/`12`/`16`/`20` 秒 | `720p`/`1024p`/`1080p` | 见[定价页](/pricing) |
| `veo3.1-fast`/`veo3.1-quality`/`veo3.1-lite` | 文生、图生 | 固定 `8` 秒 | `720p`/`1080p`/`4k` | 见[定价页](/pricing) |
| `MiniMax-Hailuo-2.3` | 文生、首帧图生 | `6`/`10` 秒 | `768p`/`1080p` | 见[定价页](/pricing) |
| `minimax-h3` | 文生、首尾帧、多模态参考 | `4-15` 秒 | `768P`/`2K` | 按秒 + 参考图/参考视频 |
| `wan3.0-video`、`wan3.0-video-prime` | 文生/首尾帧/参考生成/视频编辑 | 秒数 | `480P`/`720P`/`1080P` | 按计费时长 × 档位（带参考视频时含输入视频） |
| `grok-imagine-1.5-video` | 文生、图生 | `6-30` 秒 | `480p`/`720p`（`quality`） | 按秒 |
| `skyreels-v4-fast`/`std` | 文生、首尾帧、参考图/参考视频 | `3-15` 秒 | `480p`/`720p`/`1080p` | 按秒 × 档位 |
| `pixverse-v6` | 文生、首尾帧、多参考图 | `1-15` 秒 | `360p`/`540p`/`720p`/`1080p` | 按秒 × 档位，`audio` 加价 |
| `viduq3`/`viduq3-mix`/`viduq3-pro`/`viduq3-turbo` | 多参考图 / 文生、图生、首尾帧 | `1-16` 秒（`viduq3` 为 `3-16`） | `540p`/`720p`/`1080p`（`viduq3-mix` 无 `540p`） | 按秒 × 档位 |
| `omni-flash-ext` | 文生、参考视频驱动 | `4`/`6`/`8`/`10` 秒 | `720p`/`1080p`/`4k` | 按条 |
| `gemini-omni-flash-preview` | 文生、图生、视频编辑、续作 | 由模型决定（约 `3`–`10` 秒） | 固定 `720p` | 按条 |
## 请求参数
请求体为 JSON。`model` 和 `callback_url` 是公共字段；生成输入与控制字段必须按所选模型系列填写。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | ------ | -- | -- | --------------------------------------- |
| `model` | string | 是 | - | 平台模型 ID；平台没有该模型 → 404 `model_not_found` |
| `callback_url` | string | 否 | - | 任务到达终态时由 LoopToken 投递的回调地址；见[回调](#回调) |
提交成功返回 `202`，响应体为任务对象（此时处于 `pending` 状态）。
### 主流模型扁平字段
[主流视频模型](/video/mainstream)使用顶层扁平字段：`prompt`、`duration`、`resolution`、`mode`、`audio`、`aspect_ratio`、`image_urls`、`first_frame_image`。平台会按所选主流模型解析这些字段，而不是把它们视为未处理的附加字段。字段必须符合具体模型的能力范围，详见各模型页面。
主流模型的预扣计费只读取模型默认值和顶层 `duration` / `resolution` / `mode` / `audio`：
* `content` 中的旧式文本指令以及 `parameters` 中的嵌套字段不参与时长或质量档位计算。
* 未传对应顶层字段时直接使用该模型默认值。
* `aspect_ratio`、`image_urls` 与 `first_frame_image` 作为生成输入按模型能力处理，不参与时长或质量档位的默认值计算。
### 其他系列字段
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------------- | ------- | --- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `content` | array | 视系列 | - | 方舟风格系列（Seedance）的输入：`[{"type":"text","text":"<提示词>"}]`；`text` 内可写 `--duration <秒>`、`--resolution <720p\|1080p>` 指令来指定时长与分辨率 |
| `input` | object | 视系列 | - | DashScope 风格系列（Wan）的输入：`prompt`、`media` 等，详见系列页 |
| `parameters.duration` | integer | 否 | `5` | 显式指定时长（秒）；参与预扣计算 |
| `parameters.size` | string | 否 | `720p` 档 | 形如 `"宽*高"`，长边 ≥1440 记为 1080p 计费档，否则记为 720p 档；参与预扣计算 |
这些系列的预扣参数取舍规则：
* `content` 里的 `--duration`/`--resolution` 指令与 `parameters.duration`/`parameters.size` **整体二选一**。
* 请求体中只要出现 `parameters` 键，平台就只从 `parameters` 内读取 `duration`/`size`/`resolution`，`text` 里的指令整体忽略（不做字段级回退）。`parameters` 中缺失的子字段按默认值 5 秒 / 720p 处理。
* 例：`parameters` 只传 `{"duration": 10}`、`text` 里写了 `--resolution 1080p`，实际按 10 秒 / **720p** 计。
* `parameters.resolution` 识别 `480P`/`720P`/`1080P`（不区分大小写）；其他取值按 720p 档预扣。
* 这份参数只用于提交时的预扣费计算，任务结束后按实际结果多退少补（终态 `duration`/`resolution` 的覆盖规则见下文任务对象字段）。
## 响应
提交成功返回 `202` 和任务对象（见下文[任务对象字段](#任务对象字段)）。取结果用提交返回的 `task_id` 查询。
### 查询任务
用提交返回的 `task_id`（格式 `vt_` 前缀 + UUID）调用 `GET /v1/tasks/{task_id}`。任务不存在、或不属于当前 API Key 所在账户 → 404 `task_not_found`。
#### 任务状态
| `status` | 含义 | 处理 |
| ----------- | ----- | ------------------ |
| `pending` | 排队中 | 继续轮询 |
| `running` | 生成中 | 继续轮询 |
| `succeeded` | 终态，成功 | 读 `video_url`，尽快转存 |
| `failed` | 终态，失败 | 读 `error` |
轮询时用 `status` 判断是否结束，`progress` 只用来展示进度条。**只有部分模型的上游会回报真实进度**，其余模型在整个生成过程中都是 `0`，直到终态跳到 `100`——不要用 `progress` 是否变化来判断任务是否卡住。当前会回报真实进度的是 `seedance-2-5-max`、`seedance-2-5-hig`、`seedance-2-0-hig`。
#### 任务对象字段
所有状态都包含：
| 字段 | 类型 | 说明 |
| ------------ | -------------- | ----------------------------------------------------------------------------------------------------------- |
| `task_id` | string | `vt_` 前缀 + UUID |
| `model` | string | 提交时使用的平台模型名 |
| `status` | string | `pending` / `running` / `succeeded` / `failed` |
| `progress` | integer | 任务进度百分比，`0`-`100`；进入终态（含 `failed`）一律为 `100` |
| `created_at` | integer | 任务创建时间，Unix 秒 |
| `duration` | integer/number | 时长（秒）；默认为提交时预扣计算出的值，任务结束后如果上游返回了实际时长会被覆盖 |
| `resolution` | string | 所选模型支持的公开档位之一：`720p` / `768p` / `1024p` / `1080p` / `4k`；并非每个模型都支持全部档位。默认为提交时计算出的档位，任务结束后如果返回了可识别的实际分辨率会被覆盖 |
进入终态（`succeeded`/`failed`）后追加：
| 字段 | 类型 | 说明 |
| ----------------- | ------- | --------------------------------------------------------------------------------- |
| `completed_at` | integer | 任务结束时间，Unix 秒 |
| `usage` | object | 上游返回的用量信息，视上游而定可能包含 `duration`、`SR`（分辨率短边）、`ratio`（画面比例，如 `"16:9"`）等子字段，缺失的子字段不出现 |
| `ratio` | string | 画面比例（如 `"16:9"`），仅上游返回了该信息时出现 |
| `credits_charged` | number | 本次实际扣费（credit） |
`succeeded` 额外追加：
| 字段 | 类型 | 说明 |
| ------------ | ------- | ------------------------ |
| `video_url` | string | 视频下载直链 |
| `expires_at` | integer | `video_url` 的失效时间，Unix 秒 |
`failed` 额外追加：
| 字段 | 类型 | 说明 |
| ------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `error` | object | `{"code": "...", "message": "..."}`；`code` 取值 `timeout`（平台侧轮询超时）或 `upstream_error`（上游生成失败，不透出上游原始错误码） |
`video_url` 有时效，过期后字段不再返回（链接本身也会失效）。有效期上限为任务完成后 72 小时，具体时长取决于平台内部转存状态，某些情况下会短至完成后 24 小时。请在拿到 `succeeded` 结果后尽快下载转存，不要缓存链接长期使用。
## 回调
提交时可传 `callback_url`，任务到达终态时由 LoopToken 投递。
* 仅接受 `https`，且不能解析到内网/回环/链路本地等非公网地址，否则 → 400 `invalid_request_error`。
* 回调地址不得包含凭据，也不要在其中携带长期密钥。
* 回调内容与任务查询结果保持一致。
* 即使使用回调，也必须保留任务查询作为兜底，回调投递不能替代轮询。
* 不要提交 `webhook` 或供应商回调字段，统一使用 `callback_url`。
## 计费
视频模型的计费方式因模型而异：部分按秒计费，部分按单次任务固定价格计费，具体金额还可能取决于分辨率或质量档位。
* 提交时先按请求参数预扣，任务结束后按实际结果结算，多退少补。
* `credits_charged` 为本次实际扣费金额。
* 提交同步失败会释放预扣；异步生成失败会退回预扣，失败任务不收取最终生成费用。
* 最终价格以[定价页](/pricing)为准，实时价格见[模型列表](/models)。
## 错误
| HTTP | code | 触发场景 | 处理 |
| ---- | ---------------------------- | --------------------------------------------------------------------------------- | ----------------------- |
| 400 | `invalid_request_error` | 请求体不是合法 JSON，或 `callback_url` 不是字符串/不满足 https 与公网地址要求；各系列另有参数范围校验，`message` 为具体原因 | 按 `message` 修正请求 |
| 401 | `invalid_api_key` | 缺少、无效或已吊销的 API Key | 检查 Key |
| 402 | `insufficient_credits` | 账户余额不足以覆盖预扣费用 | 充值或降低时长、分辨率 |
| 403 | `model_not_allowed` | 当前 Key 或分组无权调用该模型 | 检查 Key 的模型白名单与分组权限 |
| 403 | `access_denied` | 该 Key 只能使用原生视频接口（Seedance 方舟原生、Kling） | 改用对应原生接口 |
| 403 | `quota_exceeded` | 账号视频生成总量已达上限 | 联系管理员 |
| 404 | `model_not_found` | 提交时，平台没有该模型，或参数组合（时长、分辨率等）没有对应的售价档位 | 使用模型列表中的精确 ID，调整参数 |
| 404 | `task_not_found` | 查询时，`task_id` 不存在或不属于当前账户 | 使用提交响应中的 `task_id` |
| 422 | `invalid_request_error` | 输入内容未通过安全检查 | 修改输入内容 |
| 429 | `media_concurrency_exceeded` | 用户或 API Key 的媒体任务并发超限，响应带 `Retry-After: 5` | 按 `Retry-After` 稍后重试 |
| 500 | `internal_error` | 平台内部处理失败 | 保存请求时间和 request ID，联系支持 |
| 502 | `upstream_error` | 上游提交失败且重试耗尽 | 短暂等待后有限次数重试 |
| 503 | `model_unavailable` | 模型已被暂停服务 | 稍后重试或改用其他模型 |
| 503 | `no_available_channel` | 该模型当前没有可用渠道 | 指数退避后重试，不要高频重复提交 |
上游对该次请求返回 400 且没有更多候选渠道时，平台按上游的 400 回复（`code` 取上游公开错误码，缺省 `invalid_request_error`），不会包装成 502。
参数或素材类问题不保证在提交阶段发现，也可能在 `202` 之后表现为异步 `failed`。客户端必须同时处理同步 HTTP 错误和异步任务错误，不要解析失败文案编写业务逻辑，按 HTTP 状态、`error.code` 和任务状态分支处理。响应头 `X-Request-Id` 可用于问题排查。完整错误响应体格式与更多错误码见[错误码](/errors)。
## 注意事项
* **只有 `seedance-2-5-max`、`seedance-2-5-hig`、`seedance-2-0-hig` 回报真实 `progress`** → 其余模型生成中恒为 `0`，用 `status` 判断是否结束。
* **请求体 `parameters` 键存在** → 方舟风格系列的预扣只读 `parameters`，`content` 里的 `--duration`/`--resolution` 整体忽略。
* **使用 `callback_url`** → 仍须保留轮询兜底。
* **`video_url`** → 任务完成后尽快转存，不要长期缓存链接。
# 主流视频模型
Source: https://looptoken.vibelab.me/docs/video/mainstream
> sora-2、veo3.1、MiniMax-Hailuo-2.3、minimax-h3 的统一扁平字段视频接口，文生/图生，异步，用 GET /v1/tasks/{task_id} 查询
OpenAI、Google 与 MiniMax 视频模型共用统一扁平请求格式，文生视频和图生视频走同一接口。提交、轮询、任务对象、回调与错误见[接口说明](/video)。
本页覆盖的 Sora 2、Veo 3.1、MiniMax Hailuo 2.3 系列当前暂未开放调用。字段说明仅供接入预览，实际可用状态以[模型列表](/models)为准。
| 项 | 值 |
| ---- | ---------------------------------------------------------------------------------------------------- |
| 模型 | `sora-2`、`sora-2-pro`、`veo3.1-fast`、`veo3.1-quality`、`veo3.1-lite`、`MiniMax-Hailuo-2.3`、`minimax-h3` |
| 模式 | 异步（提交 → 轮询 `GET /v1/tasks/{task_id}`） |
| 计费 | 按模型、时长、质量档位计算，先预扣后结算，见[计费](#计费) |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时，见[接口说明](/video#响应) |
## 模型与能力
每个系列的完整字段和示例见详情页：
| 系列 | 详情页 | 模型 |
| ------------------ | ---------------------------------------------- | -------------------------------------------- |
| Sora 2 | [Sora 2](/video/sora2) | `sora-2`、`sora-2-pro` |
| Veo 3.1 | [Veo 3.1](/video/veo31) | `veo3.1-fast`、`veo3.1-quality`、`veo3.1-lite` |
| MiniMax Hailuo 2.3 | [MiniMax Hailuo 2.3](/video/minimax-hailuo-23) | `MiniMax-Hailuo-2.3` |
| H3 | [H3 视频生成](/video/minimax-h3) | `minimax-h3` |
### OpenAI
| 模型 | 时长 | 分辨率 | 省略控制字段时 | 图片输入 |
| ------------ | ------------------------ | ---------------------- | ------------ | --------------------- |
| `sora-2` | `4`、`8`、`12`、`16`、`20` 秒 | 仅 `720p` | `4` 秒、`720p` | 可通过 `image_urls` 提交图片 |
| `sora-2-pro` | `4`、`8`、`12`、`16`、`20` 秒 | `720p`、`1024p`、`1080p` | `4` 秒、`720p` | 可通过 `image_urls` 提交图片 |
### Google
| 模型 | 时长 | 分辨率 | 省略控制字段时 | 图片输入 |
| ---------------- | -------- | ------------------- | ------------ | --------------------- |
| `veo3.1-fast` | 固定 `8` 秒 | `720p`、`1080p`、`4k` | `8` 秒、`720p` | 可通过 `image_urls` 提交图片 |
| `veo3.1-quality` | 固定 `8` 秒 | `720p`、`1080p`、`4k` | `8` 秒、`720p` | 可通过 `image_urls` 提交图片 |
| `veo3.1-lite` | 固定 `8` 秒 | `720p`、`1080p`、`4k` | `8` 秒、`720p` | 可通过 `image_urls` 提交图片 |
### MiniMax
| 模型 | 时长 | 分辨率 | 省略控制字段时 | 图片输入 |
| -------------------- | ------------ | -------------------------------- | ------------ | -------------------------------------------- |
| `MiniMax-Hailuo-2.3` | `6` 或 `10` 秒 | `768p`、`1080p`；`1080p` 仅支持 `6` 秒 | `6` 秒、`768p` | 可通过 `first_frame_image` 提交首帧图片 |
| `minimax-h3` | `4-15` 秒 | `768P`、`2K` | `5` 秒、`2K` | 支持首尾帧、参考图片/视频/音频；详见[专属文档](/video/minimax-h3) |
LoopToken 不为这些模型归一一个公共的宽高比默认值。需要固定构图时，必须显式传入 `aspect_ratio`。
## 快速开始
文生视频，用 `sora-2` 生成 8 秒、720p：
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "sora-2",
"prompt": "清晨的海岸线上，薄雾缓慢散去，镜头沿着潮线平稳前进",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
```
接口受理后返回 HTTP `202` 和任务对象（`status` 为 `pending`，用 `task_id` 轮询，见[响应](#响应)）：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "sora-2",
"status": "pending",
"created_at": 1772942400,
"duration": 8,
"resolution": "720p"
}
```
## 模式选择
| 模式 | 怎么传参 | 适用模型 |
| --------- | ------------------------------ | -------------------------------- |
| 文生视频 | 只传 `prompt` 与控制字段 | 全部 |
| 图生视频 | `image_urls` | `sora-2`、`sora-2-pro`、`veo3.1-*` |
| 首帧图生视频 | `first_frame_image` | `MiniMax-Hailuo-2.3` |
| 首尾帧、多模态参考 | 见 [H3 视频生成](/video/minimax-h3) | `minimax-h3` |
## 请求参数
这些模型共用顶层扁平字段。字段是否可用以及可选值以所选模型的能力范围为准。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------- | --------- | -- | ---------------- | ------------------------------------------------------------------------------------- |
| `model` | string | 是 | - | 上表中的精确模型 ID |
| `prompt` | string | 是 | - | 视频内容、主体动作、镜头与风格描述 |
| `duration` | integer | 否 | 见[模型与能力](#模型与能力) | 视频时长，单位秒；Veo 3.1 固定为 8 秒 |
| `resolution` | string | 否 | 见[模型与能力](#模型与能力) | 输出分辨率档位 |
| `aspect_ratio` | string | 否 | - | 输出画面宽高比；平台不归一公共默认值 |
| `image_urls` | string\[] | 否 | - | Sora 与 Veo 3.1 图生视频使用的公网图片 URL 数组 |
| `first_frame_image` | string | 否 | - | 仅 `MiniMax-Hailuo-2.3`：单个公网首帧图片 URL 或 Base64 data URI；内联数据计入 LoopToken 10 MiB 请求体读取上限 |
| `callback_url` | string | 否 | - | 任务到达终态后投递结果的公网 HTTPS URL |
## 请求示例
### 图生视频
用 `veo3.1-fast` 让一张图片产生运动：
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1-fast",
"prompt": "窗帘被微风吹动，阳光在木桌上缓慢移动，固定镜头",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9",
"image_urls": [
"https://example.com/room.jpg"
]
}'
```
`MiniMax-Hailuo-2.3` 图生视频使用单个 `first_frame_image` 字符串：
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-Hailuo-2.3",
"prompt": "海浪轻拍礁石，镜头缓慢向前推进",
"duration": 6,
"resolution": "768p",
"first_frame_image": "https://example.com/coast.jpg"
}'
```
## 响应
用 `GET /v1/tasks/{task_id}` 查询，状态依次为 `pending` → `running` → `succeeded` / `failed`（终态），轮询方式与任务对象字段见[接口说明](/video#响应)。成功任务的响应形状：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "sora-2",
"status": "succeeded",
"created_at": 1772942400,
"duration": 8,
"resolution": "720p",
"completed_at": 1772942468,
"credits_charged": 6.4,
"video_url": "https://media.example.com/video.mp4",
"expires_at": 1773028868
}
```
`failed` 状态返回公开的 `error` 对象（`code` 为 `timeout` 或 `upstream_error`）。结果字段 `video_url`、`expires_at`、`credits_charged` 的含义见[任务对象字段](/video#任务对象字段)。
## 计费
视频生成所需 credits 根据模型、时长和质量档位计算。提交任务时先冻结预计 credits，任务结束后再按实际结果结算，多退少补；成功响应中的 `credits_charged` 是本次实际扣费。精确价格见[定价页](/pricing)，实际可用状态见[模型列表](/models)。
* 预扣只读顶层 `duration` / `resolution` / `mode` / `audio`，未传则按模型默认值；Veo 3.1 无论传什么都按固定 8 秒预扣。
* 异步生成失败时预扣全额退回。
## 错误
通用错误（鉴权、余额、`task_not_found`、`no_available_channel` 等）见[接口说明](/video#错误)。本页模型特有的行为：
| HTTP | code | 触发场景 | 处理 |
| ---- | ----------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
| 404 | `model_not_found` | 时长、分辨率等组合没有对应的售价档位（`message` 为 `unknown model: `） | 对照[模型与能力](#模型与能力)调整 `duration` / `resolution` |
| 400 | `invalid_request_error` | 仅 `minimax-h3` 做字段校验，见 [H3 视频生成](/video/minimax-h3#错误)；Sora、Veo、Hailuo 的字段范围由上游校验，不合规的请求可能在 `202` 之后表现为异步 `failed` | 按各模型页的字段表修正 |
## 注意事项
* **图片 URL** → 必须能由服务端直接访问，不能依赖登录状态、Cookie 或局域网环境。
* **`video_url` 是临时地址** → 以 `expires_at` 为准，及时下载转存。
# H3 视频生成
Source: https://looptoken.vibelab.me/docs/video/minimax-h3
> minimax-h3：文生视频、首尾帧、多模态参考生成，4–15 秒、768P/2K，异步，用 GET /v1/tasks/{task_id} 查询
`minimax-h3` 使用通用异步视频接口（提交、轮询、任务对象、回调、错误见[接口说明](/video)）。所有模式通过请求字段自动识别，无需传 `mode`。提交成功返回 HTTP `202` 和 `vt_` 开头的任务 ID，客户端总超时可设为 15 分钟。
| 项 | 值 |
| -------- | --------------------------------------- |
| 模型 | `minimax-h3` |
| 模式 | 异步（提交 → 轮询 `GET /v1/tasks/{task_id}`） |
| 时长 / 分辨率 | `4-15` 秒（默认 `5`） / `768P`、`2K`（默认 `2K`） |
| 计费 | 按秒 + 参考图/参考视频，官方价格原值，见[计费](#计费) |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3",
"prompt": "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
"duration": 5,
"resolution": "2K",
"aspect_ratio": "16:9"
}'
```
提交响应（响应只包含公共任务 ID 和公共模型 ID，不包含内部路由、供应商任务 ID 或采购价格）：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "minimax-h3",
"status": "pending",
"created_at": 1786003200,
"duration": 5,
"resolution": "2k"
}
```
## 模式选择
| 模式 | 触发字段 | 说明 |
| ----- | ----------------------------------------------------------------- | ----------------------- |
| 文生视频 | 仅 `prompt` 和通用控制字段 | 纯文本生成；未传宽高比时使用 `16:9` |
| 首尾帧 | `first_frame_image` / `last_frame_image`，或对应的 `image_with_roles` | 支持首帧、尾帧或首尾帧；宽高比由图片决定 |
| 多模态参考 | `image_urls` / `video_urls` / `audio_urls`，或 `reference_image` 角色 | 使用图片、视频、音频约束角色、动作、风格或声音 |
首尾帧字段与多模态参考字段严格互斥。`audio_urls` 不能单独使用，必须同时提供至少一张参考图片或一个参考视频。
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | ------- | -- | ---------------- | ----------------------------------------------------------------------- |
| `model` | string | 是 | - | 固定为 `minimax-h3` |
| `prompt` | string | 是 | - | 非空，最长 7000 字符 |
| `duration` | integer | 否 | `5` | `4` 到 `15` 秒的整数 |
| `resolution` | string | 否 | `2K` | `768P` 或 `2K`，不区分大小写 |
| `aspect_ratio` | string | 否 | 见[宽高比规则](#宽高比规则) | `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` 或 `adaptive`；别名 `size` / `ratio` |
| `watermark` | boolean | 否 | `false` | 是否添加 AIGC 水印；别名 `aigc_watermark` |
| `callback_url` | string | 否 | - | 终态回调地址，只接受可公网访问的 HTTPS URL |
### 首尾帧字段
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------- | ------ | -- | -- | ------------------------ |
| `first_frame_image` | string | 否 | - | 公网首帧图片 URL，最多 1 个 |
| `last_frame_image` | string | 否 | - | 公网尾帧图片 URL，最多 1 个，可与首帧组合 |
### 多模态参考字段
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------ | --------- | -- | -- | --------------------------- |
| `image_urls` | string\[] | 否 | - | 最多 9 个，全部按参考图处理，不会按数量推断首尾帧 |
| `video_urls` | string\[] | 否 | - | 最多 3 个参考视频 URL |
| `audio_urls` | string\[] | 否 | - | 最多 3 个参考音频 URL；必须搭配参考图或参考视频 |
| `image_with_roles` | object\[] | 否 | - | 为图片显式指定角色，可替代上述图片字段 |
`image_with_roles` 元素：
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------------- | ------ | -- | -- | ---------------------------------------------- |
| `image_with_roles[].url` | string | 是 | - | 非空公网图片 URL |
| `image_with_roles[].role` | string | 是 | - | `first_frame`、`last_frame` 或 `reference_image` |
同一请求最多包含 1 张首帧、1 张尾帧和 9 张参考图。`image_urls` 与 `image_with_roles` 中的 `reference_image` 合并计数。
### 宽高比规则
| 模式 | 规则 |
| ----- | ------------------------------------ |
| 文生视频 | 省略或传 `adaptive` 时按 `16:9` 生成，也可传具体比例 |
| 首尾帧 | 由输入图片决定，提交的比例被忽略 |
| 多模态参考 | 默认自适应，也可传具体比例 |
### 输入媒体限制
请求体整体上限 10 MiB。较大的媒体文件必须使用无需 Cookie 或登录态即可访问的公网 HTTPS URL，不要内联 Base64。
| 类型 | 格式 | 单文件 | 其他限制 |
| -- | --------------------------- | ----: | ----------------------------------------------- |
| 图片 | JPG、JPEG、PNG、WEBP、HEIC、HEIF | 30 MB | 宽高 256-5760 px，宽高比 0.4-2.5 |
| 视频 | MP4、MOV | 50 MB | H.264/H.265；单段 2-15 秒，总时长不超过 15 秒，23.976-60 fps |
| 音频 | WAV、MP3 | 15 MB | 单段 2-15 秒，总时长不超过 15 秒 |
媒体格式、体积、时长和可访问性由生成服务进一步检查。媒体无法读取或损坏时任务会失败，失败任务不扣费。
## 请求示例
首尾帧生成：
```json
{
"model": "minimax-h3",
"prompt": "镜头从清晨缓慢过渡到日落",
"first_frame_image": "https://example.com/morning.png",
"last_frame_image": "https://example.com/sunset.png",
"duration": 8,
"resolution": "2K"
}
```
带角色的统一图片数组：
```json
{
"model": "minimax-h3",
"prompt": "镜头从清晨缓慢过渡到日落",
"image_with_roles": [
{"url": "https://example.com/morning.png", "role": "first_frame"},
{"url": "https://example.com/sunset.png", "role": "last_frame"}
],
"duration": 8
}
```
多模态参考生成：
```json
{
"model": "minimax-h3",
"prompt": "角色迎风说话，保持参考人物、动作节奏和音色",
"image_with_roles": [
{"url": "https://example.com/character.png", "role": "reference_image"}
],
"video_urls": ["https://example.com/motion.mp4"],
"audio_urls": ["https://example.com/voice.mp3"],
"duration": 5,
"resolution": "2K",
"aspect_ratio": "16:9"
}
```
## 响应
用 `GET /v1/tasks/{task_id}` 查询，状态依次为 `pending` → `running` → `succeeded` / `failed`（终态）。成功结果：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "minimax-h3",
"status": "succeeded",
"created_at": 1786003200,
"completed_at": 1786003268,
"duration": 5,
"resolution": "2k",
"credits_charged": 5.715,
"video_url": "https://media.example.com/video.mp4",
"expires_at": 1786089668
}
```
| 字段 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------------------------------------ |
| `video_url` | string | 视频下载地址，仅 `succeeded` 返回，尽快转存 |
| `expires_at` | integer | `video_url` 失效时间，Unix 秒 |
| `credits_charged` | number | 本次实际扣费（积分） |
| `error` | object | 仅 `failed` 返回：`{"code": "timeout" \| "upstream_error", "message": "..."}`；失败任务退回预扣 credits |
完整任务对象字段见[接口说明](/video#任务对象字段)。
## 计费
LoopToken 使用官方价格原值作为实际售价，不另加价，也不展示虚假折扣。`10 credits = 1 USD`。
| 项目 | 实际价格 |
| ----------- | ------------------: |
| 768P 视频 | 0.714 credits/秒 |
| 2K 视频 | 1.143 credits/秒 |
| 第 1-5 张参考图片 | 免费 |
| 第 6-9 张参考图片 | 0.286 credits/张 |
| 参考视频 | 按输出分辨率的每秒价格，与生成时长叠加 |
```text
基础费用 = 生成时长 × 分辨率每秒价格
参考视频费用 = 存在 video_urls 时，生成时长 × 分辨率每秒价格
参考图费用 = max(参考图数量 - 5, 0) × 0.286
总费用 = 基础费用 + 参考视频费用 + 参考图费用
```
例：5 秒 2K 视频、不含参考视频 = `5 × 1.143 = 5.715 credits`；同时使用参考视频 = `5 × 1.143 × 2 = 11.43 credits`。提交时先冻结预计费用，成功后按实际输出时长结算，多退少补；失败任务不扣费。
## 错误
通用错误见[接口说明](/video#错误)。本模型提交时的参数校验返回 `400 invalid_request_error`，`message` 如下：
| `message` | 处理 |
| ------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `prompt is required and must be a non-empty string` | 传非空 `prompt` |
| `prompt must not exceed 7000 characters` | 缩短提示词 |
| `duration must be an integer between 4 and 15` | 时长传 4–15 的整数 |
| `resolution must be one of 768P/2K` | 分辨率传 `768P` 或 `2K` |
| `aspect_ratio must be one of adaptive/21:9/16:9/4:3/1:1/3:4/9:16` | 比例取值见[请求参数](#请求参数)；`size`、`ratio` 别名同理 |
| `watermark must be a boolean` | `watermark` / `aigc_watermark` 传布尔值 |
| `webhook is not supported; use callback_url` | 删除 `webhook`，改用 `callback_url` |
| `first_frame_image must be a non-empty string` | 首尾帧图片传非空 URL（`last_frame_image` 同理） |
| `image_urls must contain at most 9 items` | `image_urls` ≤ 9，`video_urls` / `audio_urls` ≤ 3 |
| `image_with_roles[].role must be one of first_frame/last_frame/reference_image` | 修正 `role` |
| `at most one first frame and one last frame are allowed` | 首帧、尾帧各最多 1 张 |
| `at most 9 reference images are allowed` | 参考图（含 `image_with_roles` 中的 `reference_image`）合计 ≤ 9 |
| `first/last frame inputs cannot be combined with reference media` | 首尾帧与多模态参考二选一 |
| `audio_urls requires at least one reference image or video` | 音频须搭配参考图或参考视频 |
媒体格式、体积、时长和可访问性由生成服务进一步检查，失败表现为异步 `failed`，不扣费。
## 注意事项
不要提交 `webhook` 或供应商回调字段，统一使用 `callback_url`。大媒体必须用公网 HTTPS URL，不要内联 Base64（请求体上限 10 MiB）。
* **首尾帧字段与多模态参考字段** → 严格互斥，不能混用。
* **`audio_urls`** → 不能单独使用，必须搭配参考图或参考视频。
* **`video_urls` 存在** → 参考视频费用与生成时长叠加（费用翻倍）。
# MiniMax Hailuo 2.3
Source: https://looptoken.vibelab.me/docs/video/minimax-hailuo-23
> MiniMax-Hailuo-2.3：文生/首帧图生视频，6 或 10 秒，768p/1080p，异步，用 GET /v1/tasks/{task_id} 查询
MiniMax-Hailuo-2.3 当前暂未开放调用。本页字段说明仅供接入预览，实际可用状态以[模型列表](/models)为准。
Hailuo 2.3 通过 `/v1` 统一异步视频接口调用。提交、轮询、任务对象与错误见[接口说明](/video)。
| 项 | 值 |
| ---- | ------------------------------------- |
| 模型 | `MiniMax-Hailuo-2.3` |
| 模式 | 异步（提交 → 轮询 `GET /v1/tasks/{task_id}`） |
| 计费 | 按时长与分辨率档位，先预扣后结算，价格以[定价页](/pricing)为准 |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时 |
时长 `6` 或 `10` 秒，分辨率 `768p`、`1080p`，默认 `6` 秒、`768p`。
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-Hailuo-2.3",
"prompt": "[推进]A cute kitten running on the grass",
"duration": 6,
"resolution": "768p",
"prompt_optimizer": true,
"fast_pretreatment": false,
"watermark": false
}'
```
响应示例（HTTP `202`）：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "MiniMax-Hailuo-2.3",
"status": "pending",
"created_at": 1772942400,
"duration": 6,
"resolution": "768p"
}
```
用 `task_id` 调用 `GET /v1/tasks/{task_id}` 查询结果，见[响应](#响应)。
## 模式选择
| 模式 | 怎么传参 |
| ------ | --------------------- |
| 文生视频 | 只传 `prompt` 与控制字段 |
| 首帧图生视频 | 加 `first_frame_image` |
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------- | ------- | -- | ------- | -------------------------------- |
| `model` | string | 是 | - | 固定为 `MiniMax-Hailuo-2.3` |
| `prompt` | string | 是 | - | 视频内容描述，最长 2000 字符；可在提示词中使用镜头运动指令 |
| `duration` | integer | 否 | `6` | `6` 或 `10` |
| `resolution` | string | 否 | `768p` | `768p` 或 `1080p` |
| `first_frame_image` | string | 否 | - | 首帧图片，支持公网 URL 或 Base64 data URI |
| `prompt_optimizer` | boolean | 否 | `true` | 是否自动优化提示词 |
| `fast_pretreatment` | boolean | 否 | `false` | 是否缩短提示词优化耗时；开启后优化质量可能略受影响 |
| `watermark` | boolean | 否 | `false` | 是否添加水印 |
| `callback_url` | string | 否 | - | 任务到达终态后的 HTTPS 回调地址 |
`prompt` 中可写入镜头运动指令，例如 `[左移]`、`[右移]`、`[推进]`、`[拉远]`、`[上升]`、`[下降]`、`[变焦推近]`、`[变焦拉远]`、`[晃动]`、`[跟随]`、`[固定]` 等。
## 请求示例
首帧图生视频：
```json
{
"model": "MiniMax-Hailuo-2.3",
"prompt": "Kitten running towards camera, smiling and blinking",
"first_frame_image": "https://example.com/cat.jpg",
"duration": 6,
"resolution": "1080p"
}
```
## 响应
用 `GET /v1/tasks/{task_id}` 查询，状态依次为 `pending` → `running` → `succeeded` / `failed`（终态）。成功后 `video_url` 为视频下载地址：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "MiniMax-Hailuo-2.3",
"status": "succeeded",
"progress": 100,
"created_at": 1772942400,
"completed_at": 1772942468,
"duration": 6,
"resolution": "768p",
"video_url": "https://media.example.com/video.mp4",
"expires_at": 1773028868
}
```
| 字段 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------------------- |
| `video_url` | string | 视频下载地址，仅 `succeeded` 返回，尽快转存 |
| `expires_at` | integer | `video_url` 失效时间，Unix 秒 |
| `credits_charged` | number | 本次实际扣费（积分） |
| `error` | object | 仅 `failed` 返回：`{"code": "timeout" \| "upstream_error", "message": "..."}` |
完整任务对象字段见[接口说明](/video#任务对象字段)。
## 计费
* 提交时按顶层 `duration`、`resolution` 预扣，未传时按 `6` 秒、`768p`。
* 终态按实际结果结算，多退少补；失败全额退回预扣。
## 错误
通用错误见[接口说明](/video#错误)。
| HTTP | code | 触发场景 | 处理 |
| ---- | ----------------- | ------------------------------------ | ---------------- |
| 404 | `model_not_found` | `duration` / `resolution` 组合没有对应售价档位 | 按[注意事项](#注意事项)调整 |
本模型的字段范围由上游校验，不合规的请求可能在 `202` 之后表现为异步 `failed`。
## 注意事项
* **`1080p`** → 仅支持 `6` 秒；`768p` 支持 `6` 秒和 `10` 秒。
# Omni Flash 系列
Source: https://looptoken.vibelab.me/docs/video/omni-flash
> omni-flash-ext 与 gemini-omni-flash-preview：文生、参考视频驱动、图生与视频编辑，异步，按条计费，用 GET /v1/tasks/{task_id} 查询
本页包含两个模型：`omni-flash-ext` 支持分辨率/时长档位与参考视频驱动生成；`gemini-omni-flash-preview` 固定 `720p`、无需指定时长，支持文生视频、图生视频（参考图）、视频编辑（参考视频）与多轮续作编辑。提交、轮询、任务对象与错误见[接口说明](/video)。
| 项 | 值 |
| ---- | -------------------------------------------- |
| 模型 | `omni-flash-ext`、`gemini-omni-flash-preview` |
| 模式 | 异步（提交 → 轮询 `GET /v1/tasks/{task_id}`） |
| 计费 | 按单次任务（条）固定扣费，与实际输出时长无关，见[计费](#计费) |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时 |
| 模型 | 时长 | 分辨率 | 默认值 |
| --------------------------- | --------------------------- | ------------------- | ------------ |
| `omni-flash-ext` | `4`、`6`、`8`、`10` 秒（枚举） | `720p`、`1080p`、`4k` | `6` 秒、`720p` |
| `gemini-omni-flash-preview` | 不支持指定时长，输出约 `3`–`10` 秒由模型决定 | 固定 `720p` | `720p` |
## 快速开始
`omni-flash-ext` 按枚举时长生成：
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "omni-flash-ext",
"prompt": "工作室里的产品旋转展示，柔光打底",
"resolution": "720p",
"duration": 8
}'
```
响应示例（HTTP `202`）：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "omni-flash-ext",
"status": "pending",
"created_at": 1772942400,
"duration": 8,
"resolution": "720p"
}
```
用 `task_id` 调用 `GET /v1/tasks/{task_id}` 查询，见[响应](#响应)。
## 模式选择
| 模式 | 模型 | 怎么传参 |
| ---------- | --------------------------- | --------------------------------------- |
| 文生视频（枚举时长） | `omni-flash-ext` | `prompt` + `resolution` + `duration` |
| 参考视频驱动 | `omni-flash-ext` | `video_urls`，不传 `duration`，按参考视频档位计费 |
| 文生视频 | `gemini-omni-flash-preview` | 只传 `prompt` |
| 图生视频 | `gemini-omni-flash-preview` | `image_urls`（最多 16 张） |
| 视频编辑 | `gemini-omni-flash-preview` | `video_urls`（最多 1 个） |
| 多轮续作 | `gemini-omni-flash-preview` | `extend_from_task_id`，与 `video_urls` 互斥 |
## 请求参数
### `omni-flash-ext`
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------------- | --------- | -- | ------- | --------------------------------------------------------------- |
| `model` | string | 是 | - | 固定为 `omni-flash-ext` |
| `prompt` | string | 是 | - | 视频内容描述 |
| `resolution` | string | 否 | `720p` | `720p`、`1080p` 或 `4k` |
| `duration` | integer | 否 | `6` | `4`、`6`、`8`、`10` 之一；**不能与 `video_urls` 同时使用** |
| `video_urls` | string\[] | 否 | - | 参考视频 URL，用于驱动生成；与 `duration` 互斥，出现该字段按参考视频档位计费 |
| `generation_type` | string | 否 | 按输入自动判断 | 生成模式，配合 `video_urls` 使用，如按首尾帧（`frame`）或按参考视频驱动（`reference`）解析输入 |
| `callback_url` | string | 否 | - | 任务到达终态后的 HTTPS 回调地址 |
### `gemini-omni-flash-preview`
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------------- | --------- | -- | ------ | ---------------------------------------------------------------------------------- |
| `model` | string | 是 | - | 固定为 `gemini-omni-flash-preview` |
| `prompt` | string | 是 | - | 场景描述或编辑指令 |
| `image_urls` | string\[] | 否 | - | 参考图 URL，最多 `16` 张（JPEG/PNG），用于图生视频 |
| `video_urls` | string\[] | 否 | - | 参考视频 URL，最多 `1` 个（时长 `1`–`24` 秒，建议不超过 `3` 秒），用于视频编辑；**与 `extend_from_task_id` 互斥** |
| `aspect_ratio` | string | 否 | `16:9` | `16:9`（横屏）或 `9:16`（竖屏） |
| `extend_from_task_id` | string | 否 | - | 传入上一次任务 ID 进行多轮续作编辑；**与 `video_urls` 互斥** |
| `callback_url` | string | 否 | - | 任务到达终态后的 HTTPS 回调地址 |
该模型 `resolution` 仅接受 `720p`（可省略），不支持 `duration`（输出时长由模型自行决定）。输出视频为 `720p`、`24fps`，自带音频。
## 请求示例
`omni-flash-ext` 参考视频驱动（不传 `duration`）：
```json
{
"model": "omni-flash-ext",
"prompt": "沿用参考视频的镜头运动，主体替换为一辆红色跑车",
"resolution": "1080p",
"video_urls": ["https://example.com/ref.mp4"]
}
```
`gemini-omni-flash-preview` 文生视频：
```json
{
"model": "gemini-omni-flash-preview",
"prompt": "夕阳下的海边，海鸥掠过水面"
}
```
`gemini-omni-flash-preview` 图生视频（参考图 + 运动描述）：
```json
{
"model": "gemini-omni-flash-preview",
"prompt": "让画面中的人物转身走向远处",
"image_urls": ["https://example.com/ref.png"],
"aspect_ratio": "9:16"
}
```
## 响应
用 `GET /v1/tasks/{task_id}` 查询，状态依次为 `pending` → `running` → `succeeded` / `failed`（终态）。
| 字段 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------------------- |
| `status` | string | `pending`、`running`、`succeeded`、`failed` |
| `video_url` | string | 视频下载地址，仅 `succeeded` 返回，尽快转存 |
| `expires_at` | integer | `video_url` 失效时间，Unix 秒 |
| `credits_charged` | number | 本次实际扣费（积分） |
| `error` | object | 仅 `failed` 返回：`{"code": "timeout" \| "upstream_error", "message": "..."}` |
完整任务对象字段与示例见[接口说明](/video#任务对象字段)。`extend_from_task_id` 传入的是这里返回的 `task_id`。
## 计费
两个模型均按单次任务（条）固定扣费，与实际输出时长无关。
`omni-flash-ext` 价格取决于分辨率与时长档位：
| 分辨率 | `4` 秒 | `6` 秒 | `8` 秒 | `10` 秒 |
| ---------- | ---------- | ------------ | ------------- | ------------- |
| `720p`（默认） | 约 `3` 积分/条 | 约 `3.6` 积分/条 | 约 `4.2` 积分/条 | 约 `4.8` 积分/条 |
| `1080p` | 约 `3` 积分/条 | 约 `3.6` 积分/条 | 约 `4.2` 积分/条 | 约 `4.8` 积分/条 |
| `4k` | 约 `9` 积分/条 | 约 `9.6` 积分/条 | 约 `10.2` 积分/条 | 约 `10.8` 积分/条 |
传入 `video_urls`（参考视频驱动，不含 `duration`）时按固定档位计费：`720p`/`1080p` 约 `0.96` 积分/条，`4k` 约 `2.88` 积分/条。
`gemini-omni-flash-preview` 固定约 `9.74` 积分/条。
精确价格与实时变动以[定价页](/pricing)为准。
## 错误
通用错误见[接口说明](/video#错误)。本模型提交时的参数校验返回 `400 invalid_request_error`：
| `message` | 触发场景 | 处理 |
| -------------------------------------------------- | ---------------------------------------------- | ------------------------ |
| `resolution must be one of 720p/1080p/4k` | `omni-flash-ext` 分辨率取值不在范围内 | 改用 `720p`、`1080p` 或 `4k` |
| `resolution must be one of 720p` | `gemini-omni-flash-preview` 传了非 `720p` | 省略或传 `720p` |
| `duration must be one of 4/6/8/10` | `omni-flash-ext` 时长不是枚举值（含非整数） | 传 `4`、`6`、`8`、`10` |
| `duration cannot be used together with video_urls` | `omni-flash-ext` 同时传 `duration` 与 `video_urls` | 二选一 |
## 注意事项
`omni-flash-ext` 的 `duration` 与 `video_urls` 互斥：请求中同时出现两者会返回 `400 invalid_request_error`。
* **`gemini-omni-flash-preview` 的 `video_urls` 与 `extend_from_task_id`** → 互斥，二选一。
* **`gemini-omni-flash-preview` 传 `duration`** → 不支持，输出时长由模型决定。
# Pixverse v6
Source: https://looptoken.vibelab.me/docs/video/pixverse
> pixverse-v6：文生/首尾帧/多参考图视频，1–15 秒、360p–1080p，可选人声音效，异步，用 GET /v1/tasks/{task_id} 查询
支持文生视频、首尾帧图生视频、多参考图生成与可选人声/音效。提交、轮询、任务对象与错误见[接口说明](/video)。
| 项 | 值 |
| ---- | ---------------------------------------------- |
| 模型 | `pixverse-v6` |
| 模式 | 异步（提交 → 轮询 `GET /v1/tasks/{task_id}`） |
| 计费 | 按实际生成秒数 × 分辨率档位，`audio: true` 按更高档位，见[计费](#计费) |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时 |
时长 `1-15` 秒，分辨率 `360p`、`540p`、`720p`、`1080p`，默认 `5` 秒、`540p`、`audio: false`。
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "pixverse-v6",
"prompt": "城市夜景，霓虹灯光在雨后地面反射",
"resolution": "720p",
"duration": 5,
"audio": true
}'
```
响应示例（HTTP `202`）：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "pixverse-v6",
"status": "pending",
"created_at": 1772942400,
"duration": 5,
"resolution": "720p"
}
```
用 `task_id` 调用 `GET /v1/tasks/{task_id}` 查询，见[响应](#响应)。
## 模式选择
通过 `image_urls` 的图片数量选择模式：
| 图片数量 | 行为 |
| ---: | ---------------------------------- |
| 0 | 文生视频 |
| 1 | 作为首帧图片 |
| 2 | 第 1 张为首帧，第 2 张为尾帧 |
| 3+ | 前两张按首尾帧处理，其余作为参考图参与生成，用于保持角色/风格一致性 |
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | --------- | -- | ------- | ---------------------------- |
| `model` | string | 是 | - | 固定为 `pixverse-v6` |
| `prompt` | string | 是 | - | 视频内容描述 |
| `resolution` | string | 否 | `540p` | `360p`、`540p`、`720p`、`1080p` |
| `duration` | integer | 否 | `5` | `1-15` 秒 |
| `image_urls` | string\[] | 否 | - | 图生视频图片，行为见[模式选择](#模式选择) |
| `audio` | boolean | 否 | `false` | 是否生成人声/音效；开启后按更高档位计费 |
| `callback_url` | string | 否 | - | 任务到达终态后的 HTTPS 回调地址 |
## 请求示例
首尾帧图生视频：
```json
{
"model": "pixverse-v6",
"prompt": "镜头从清晨缓慢过渡到日落",
"resolution": "720p",
"duration": 5,
"image_urls": ["https://example.com/first.png", "https://example.com/last.png"]
}
```
## 响应
用 `GET /v1/tasks/{task_id}` 查询，状态依次为 `pending` → `running` → `succeeded` / `failed`（终态）。
| 字段 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------------------- |
| `status` | string | `pending`、`running`、`succeeded`、`failed` |
| `video_url` | string | 视频下载地址，仅 `succeeded` 返回，尽快转存 |
| `expires_at` | integer | `video_url` 失效时间，Unix 秒 |
| `credits_charged` | number | 本次实际扣费（积分） |
| `error` | object | 仅 `failed` 返回：`{"code": "timeout" \| "upstream_error", "message": "..."}` |
完整任务对象字段与示例见[接口说明](/video#任务对象字段)。
## 计费
按实际生成时长（秒）× 分辨率档位计费；`audio: true` 按更高的有声档位计费。提交时先按请求参数预扣，任务结束后按实际结果结算，多退少补。
| 分辨率 | 静音 | `audio: true` |
| ---------- | -------------- | -------------- |
| `360p` | 约 `0.192` 积分/秒 | 约 `0.288` 积分/秒 |
| `540p`（默认） | 约 `0.288` 积分/秒 | 约 `0.384` 积分/秒 |
| `720p` | 约 `0.384` 积分/秒 | 约 `0.48` 积分/秒 |
| `1080p` | 约 `0.768` 积分/秒 | 约 `0.96` 积分/秒 |
精确价格与实时变动以[定价页](/pricing)为准。
## 错误
通用错误见[接口说明](/video#错误)。本模型提交时的参数校验返回 `400 invalid_request_error`：
| `message` | 处理 |
| ------------------------------------------------ | ------------ |
| `resolution must be one of 360p/540p/720p/1080p` | 分辨率取上述值 |
| `duration must be between 1 and 15` | 时长传 `1`–`15` |
# 虚拟人像素材入库
Source: https://looptoken.vibelab.me/docs/video/private-avatar
> seedance2-private-avatar：POST /v1/seedance2/private-avatar 虚拟人像素材异步入库，GET 查询审核结果，免费
仅支持虚拟人像 / AIGC 生成人像素材，**不支持真人照片认证**。上传真人照片可能审核不通过，或在后续更新中被拒绝入库。本页仅覆盖入库与查询；`asset://` 在 Seedance 2.0 生成请求中的传参方式尚未在文档中开放。
为 Seedance 2.0 的"人物一致性"生成能力准备可复用的人像素材：提交图片素材后平台异步审核，审核通过的素材返回 `asset://` 引用，可用于保持同一人物形象。
| 项 | 值 |
| -- | --------------------------------------------------------------------------- |
| 模型 | `seedance2-private-avatar` |
| 模式 | 异步（提交入库任务 → 轮询 `GET /v1/seedance2/private-avatar/{task_id}`，建议间隔 5-10 秒） |
| 计费 | 素材入库对用户**免费**，见[计费](#计费) |
| 鉴权 | `Authorization: Bearer $LOOPTOKEN_API_KEY`、`Content-Type: application/json` |
## 快速开始
```bash
curl https://api.vibelab.me/v1/seedance2/private-avatar \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"group": {"name": "my-virtual-character"},
"assets": [
{"url": "https://example.com/avatar-front.jpg", "name": "front"},
{"url": "https://example.com/avatar-side.jpg", "name": "side"}
]
}'
```
提交成功返回 HTTP `202`：
```json
{
"code": 200,
"data": {
"id": "avatar_xxx",
"object": "seedance.avatar.asset.task",
"status": "processing",
"progress": 0
}
}
```
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | ------ | -- | --------- | ------------------------------------------------------------------------ |
| `group` | object | 否 | - | 新建素材组，`{name, description}`；与 `group_id` **二选一**，两者同传返回 400 |
| `group_id` | string | 否 | - | 已有素材组 ID，向该组追加素材；只能传本账号历史任务成功创建过的 `group_id`，传他人或不存在的 `group_id` 返回 404 |
| `project_name` | string | 否 | `default` | 素材所属项目名 |
| `asset_type` | string | 否 | `Image` | `Image`、`Video`、`Audio` 之一 |
| `assets` | array | 是 | - | 待入库素材数组，元素为 `{url, name}`，最多 `20` 个；`url` 必须为非空 `http(s)` 地址，`name` 必须非空 |
`group` 与 `group_id` 必须传且只能传一个：完全不传或两者同传都返回 400。首次入库传 `group` 新建素材组；后续向同一素材组追加素材传 `group_id`。
单素材场景支持兼容写法：直接在请求顶层传 `url`、`name`，无需包裹成 `assets` 数组，平台会自动归一化为单元素的 `assets` 数组。
## 请求示例
完整请求示例：
```json
{
"group": {
"name": "my-virtual-character",
"description": "虚拟主播形象素材"
},
"project_name": "default",
"asset_type": "Image",
"assets": [
{
"url": "https://example.com/avatar-front.jpg",
"name": "front"
},
{
"url": "https://example.com/avatar-side.jpg",
"name": "side"
}
]
}
```
单素材兼容写法：
```json
{
"group": { "name": "my-virtual-character" },
"url": "https://example.com/avatar-front.jpg",
"name": "front"
}
```
## 响应
### 提交响应
| 字段 | 类型 | 说明 |
| --------------- | ------- | ------------------------------------------------ |
| `data.id` | string | 平台任务 ID，格式 `avatar_` + UUID，用于后续查询 |
| `data.object` | string | 固定为 `seedance.avatar.asset.task` |
| `data.status` | string | 提交确认状态，此时任务已受理但尚无审核结果；任务实际状态以查询接口返回的 `status` 为准 |
| `data.progress` | integer | 审核进度百分比，提交时为 `0` |
### 查询审核结果
`GET /v1/seedance2/private-avatar/{task_id}`，路径参数 `task_id` 为提交接口返回的 `avatar_...` ID。
#### 任务状态
| status | 说明 |
| ----------- | ---------------------------------------------- |
| `pending` | 排队中，尚未开始审核 |
| `running` | 审核中 |
| `succeeded` | 全部素材审核通过 |
| `failed` | 任务未完全成功；批量提交时**任一素材审核失败，整单即判定为 `failed`** |
`pending`/`running` 状态下 `result` 字段不出现或为空，轮询直至进入 `succeeded` 或 `failed` 终态。
批量入库的部分失败语义：只要 `assets` 中有一个素材未通过审核，整个任务的 `status` 就是 `failed`，而不是部分成功状态。但这**不代表全部素材都不可用**——已通过审核的素材仍出现在 `result.usable_assets` 中，可以正常使用 `asset://` 引用。请按 `result.usable_assets` 而不是顶层 `status` 判断单个素材是否可用。
#### 响应字段
| 字段 | 类型 | 说明 |
| --------------------------- | ------- | ----------------------------------------------------- |
| `data.id` | string | 平台任务 ID |
| `data.status` | string | `pending` / `running` / `succeeded` / `failed` |
| `data.progress` | integer | 审核进度百分比，`0-100` |
| `data.result.assets` | array | 本次任务涉及的全部素材，元素含 `asset_id`、`asset_url`（`asset://` 引用） |
| `data.result.usable_assets` | array | 审核通过、可直接使用的素材子集，元素结构同 `assets` |
| `data.result.failed_assets` | array | 审核未通过的素材，含失败原因；任务全部成功时为空数组 |
成功示例：
```json
{
"code": 200,
"data": {
"id": "avatar_xxx",
"status": "succeeded",
"progress": 100,
"result": {
"assets": [
{
"asset_id": "asset-xxx",
"asset_url": "asset://asset-xxx"
},
{
"asset_id": "asset-yyy",
"asset_url": "asset://asset-yyy"
}
],
"usable_assets": [
{
"asset_id": "asset-xxx",
"asset_url": "asset://asset-xxx"
},
{
"asset_id": "asset-yyy",
"asset_url": "asset://asset-yyy"
}
],
"failed_assets": []
}
}
}
```
部分失败示例（整单 `status` 为 `failed`，但仍有可用素材）：
```json
{
"code": 200,
"data": {
"id": "avatar_xxx",
"status": "failed",
"progress": 100,
"result": {
"assets": [
{
"asset_id": "asset-xxx",
"asset_url": "asset://asset-xxx"
}
],
"usable_assets": [
{
"asset_id": "asset-xxx",
"asset_url": "asset://asset-xxx"
}
],
"failed_assets": [
{
"name": "side",
"reason": "人脸识别失败"
}
]
}
}
}
```
## 计费
素材入库对用户免费。
## 错误
| HTTP | code | 触发场景 | 处理 |
| ---- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| 400 | `invalid_request_error` | `group` 与 `group_id` 同传或都不传、`assets` 为空或超过 20 个、`asset_type` 不在 `Image` / `Video` / `Audio`、`url` 非法或缺失、`name` 缺失等参数错误；`message` 为具体原因 | 按 `message` 修正请求 |
| 404 | `task_not_found` | 查询任务时 `task_id` 不存在或不属于当前账户 | 使用提交响应中的 `data.id` |
| 404 | `group_not_found` | `group_id` 不存在，或不属于当前账户 | 只传本账号历史任务成功创建过的 `group_id`，或改传 `group` 新建 |
| 422 | `invalid_request_error` | 提交时上游同步拒绝（`message` 为 `content moderation rejected`）；多数审核结果异步产出，见[部分失败语义](#任务状态) | 更换素材 |
| 502 | `upstream_error` | 入库任务提交失败 | 短暂等待后有限次数重试 |
| 503 | `no_available_channel` | 当前没有可用渠道 | 指数退避后重试 |
错误体为 `{"error":{"code":"...","message":"..."}}`，统一格式见[错误码](/errors)。
## 注意事项
* **`asset://` 引用** → 素材归属提交它的账号；当前仅供本平台 Seedance 2.0 系列生成使用，不是通用可下载的文件地址。
* **`group_id`** → 只能传本账号历史任务中成功创建过的素材组 ID；传其他账号的 `group_id` 返回 404，不区分"不存在"与"无权限"。
* **批量入库任一素材审核失败** → 整单 `status` 为 `failed`；已通过的素材仍在 `result.usable_assets` 中，按它判断单个素材是否可用。
# Seedance 方舟原生接口
Source: https://looptoken.vibelab.me/docs/video/seedance-ark
> Seedance 2.0 与 2.5 的方舟原生协议：POST /api/v3/contents/generations/tasks 创建，GET 单任务查询与列表，异步，支持草稿与回调
本页仅描述 **Seedance 方舟原生接口**，路径与 JSON 参数遵循火山方舟协议。它与[Seedance 方舟原生素材库版](./seedance-native-assets)是独立模式：API Base、任务、Endpoint 绑定分别使用，本页接口不能访问素材库版任务或引用其素材。
| 项 | 值 |
| -------- | ----------------------------------------------------------------------------------------------- |
| API Base | `https://api.vibelab.me/api/v3`（火山方舟 SDK 设置 `base_url`，使用 LoopToken API Key） |
| 鉴权 | `Authorization: Bearer `；创建请求 `Content-Type: application/json`；密钥保存在服务端环境变量中 |
| 模式 | 异步：创建返回 `id` → 轮询 `GET /api/v3/contents/generations/tasks/{id}` |
| 计费 | 按实际 `usage.completion_tokens` 结算，见[计费](#计费) |
| 媒体保留 | 视频和尾帧 URL 24 小时有效；任务记录仅最近七天可查 |
| 不提供 | 取消/删除、素材库管理、真人认证接口 |
列表只返回当前账户有权访问的本地任务，不查询上游账户的全量任务。
## 模型
| 模型 ID | 分辨率 | 输出时长 | 参考图 / 视频 / 音频上限 |
| --------------------------------- | ------------------ | ---------------- | --------------- |
| `doubao-seedance-2-0-mini-260615` | 480p、720p | 4–15 秒，或 -1 自动选择 | 9 / 3 / 3 |
| `doubao-seedance-2-0-fast-260128` | 480p、720p | 4–15 秒，或 -1 自动选择 | 9 / 3 / 3 |
| `doubao-seedance-2-0-260128` | 480p、720p、1080p、4k | 4–15 秒，或 -1 自动选择 | 9 / 3 / 3 |
| `doubao-seedance-2-5-260628` | 480p、720p、1080p | 4–30 秒，或 -1 自动选择 | 30 / 10 / 10 |
四个模型分辨率默认 720p，比例默认 adaptive；2.5 时长默认 -1；省略控制参数时保留模型侧默认行为。`model` 也可填平台管理员已绑定的 Endpoint ID；其他账户的 Endpoint ID 和素材 ID 不能直接迁移使用。实际开放状态与销售价格以账户获准使用的模型及平台价格配置为准。
## 快速开始
```bash
curl https://api.vibelab.me/api/v3/contents/generations/tasks \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-5-260628",
"content": [{"type":"text","text":"A paper boat sails across a quiet lake"}],
"duration": 5,
"resolution": "720p",
"ratio": "16:9",
"generate_audio": true,
"return_last_frame": true
}'
```
成功返回 HTTP 200：
```json
{"id":"task_<任务标识>"}
```
这个 `id` 原样使用上游创建接口返回的网关任务 ID（`task_...`），不添加前缀或替换为自定义 UUID。保存它：查询、列表、回调都用同一个 ID。创建是异步的，返回 ID 只表示已接单，不代表视频已生成。
## 模式选择
| 模式 | 怎么传参 |
| ------------- | ----------------------------------------------------------------------------------- |
| 文生视频 | `content` 只含 `text` |
| 首帧 | `image_url` 加 `role: first_frame`（单首帧可省略 `role`） |
| 首尾帧 | 一张 `first_frame` 加一张 `last_frame`，见[首尾帧](#首尾帧) |
| 全模态参考 | `reference_image` / `reference_video` / `reference_audio`，可组合 |
| 编辑、延长（2.5） | `omni_reference_task_type` 为 `edit` / `extend`，加 `reference_video`，见[编辑和延长](#编辑和延长) |
| 草稿、草稿转正式（2.5） | `draft: true` 生成 `480p` 草稿；再用 `draft_task` 转 `1080p` 正式视频，见[草稿与正式视频](#草稿与正式视频) |
首帧、首尾帧、全模态参考三个场景互斥。
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------------------- | --------- | -- | ---------- | ------------------------------------------------------- |
| `model` | string | 是 | - | 上表 Model ID，或平台已绑定的 Endpoint ID |
| `content` | object\[] | 是 | - | 非空输入数组，见 [content 输入](#content-输入) |
| `omni_reference_task_type` | string | 否 | `auto` | 仅 2.5；`auto`、`reference`、`edit`、`extend` |
| `resolution` | string | 否 | `720p` | 必须在所选模型的分辨率范围内；草稿及草稿转正式视频有特殊规则 |
| `ratio` | string | 否 | `adaptive` | `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive` |
| `duration` | integer | 否 | 模型默认 | 正整数按模型范围，`-1` 自动选择；2.5 默认 `-1` |
| `seed` | integer | 否 | - | 随机种子，原样透传至模型服务；不能保证相同种子完全复现画面 |
| `generate_audio` | boolean | 否 | `true` | 是否生成同步音频；显式 `false` 保留 |
| `watermark` | boolean | 否 | `false` | 是否添加 AI 生成水印 |
| `output_format` | string | 否 | 模型默认 | 原样透传；常见值 `mp4`、`mov`，支持范围由模型服务校验 |
| `return_last_frame` | boolean | 否 | `false` | 返回尾帧 URL，保留上游 PNG/JPEG 格式，不转码 |
| `draft` | boolean | 否 | `false` | 2.5 样片模式，生成草稿必须 `480p` |
| `service_tier` | string | 否 | 模型默认 | 原样透传，是否支持 `default`、`flex` 等等级由模型服务判断 |
| `callback_url` | string | 否 | - | 状态变化时投递任务查询结构；HTTPS 公网地址 |
| `execution_expires_after` | integer | 否 | `172800` | `3600`–`259200` 秒，从创建时间计算 |
| `priority` | integer | 否 | 模型默认 | 排队优先级，取值范围由模型服务校验 |
| `safety_identifier` | string | 否 | - | 终端用户标识，格式要求由模型服务校验 |
| `tools` | object\[] | 否 | - | 每项须有非空字符串 `type`；例如 `{"type":"web_search"}`，其他工具及配置原样透传 |
| `frames` | integer | 否 | - | 输出帧数，支持范围与参数冲突由模型服务校验 |
| `camera_fixed` | boolean | 否 | - | 固定镜头选项，是否生效由模型服务决定 |
* 附加生成参数及未列出的扩展字段默认透传，保留 `false`、`0`、`null`、数组及嵌套对象，不再按参数白名单静默丢弃。已列出参数仍检查基本类型；支持范围、枚举及参数组合由模型服务进一步校验。
* 平台仍校验模型权限、`content`、分辨率、时长、比例、音频/草稿模式、任务有效期及回调地址等路由和计费所需字段。`callback_url` 由平台处理；转发时可按上游协议转换 `duration` 等字段名。
* 参数被接受并透传，不代表模型服务支持或保证生效；上游可能拒绝，也可能忽略该参数。
* 省略参数与显式 `false`、`0`、`-1` 含义不同。
* `resolution`、`ratio`、`duration` 等也可在文本末尾用 `--参数 值` 弱校验写法传入；顶层参数优先，提示词原样交给模型处理。建议用顶层强校验方式。
### content 输入
| type | 必需结构 | role |
| ------------ | ------------------------------------------------------------------------- | --------------------------------------------------- |
| `text` | `{"type":"text","text":"提示词"}` | 无 |
| `image_url` | `{"type":"image_url","image_url":{"url":"..."},"role":"..."}` | `first_frame`、`last_frame`、`reference_image`；单首帧可省略 |
| `video_url` | `{"type":"video_url","video_url":{"url":"..."},"role":"reference_video"}` | `reference_video` |
| `audio_url` | `{"type":"audio_url","audio_url":{"url":"..."},"role":"reference_audio"}` | `reference_audio` |
| `draft_task` | `{"type":"draft_task","draft_task":{"id":"..."}}` | 无；仅 2.5 |
* 图片、音频：公网 URL、对应 MIME 的 Base64 数据 URL、本模式获准使用的 `asset://` 素材（不能用素材库版返回的公开 Asset Id）。视频：公网 URL 或 `asset://`，不支持 Base64。
* 公网素材须无需登录即可访问，并在生成完成前保持有效。整个请求体上限 64 MiB。
* 首帧、首尾帧、全模态参考三个场景互斥。首尾帧必须同时有一张 `first_frame` 和一张 `last_frame`；参考素材可组合图片、视频、音频。
* 2.0 系列不能仅提供音频，至少还需一张图或一个视频；2.5 支持纯音频参考。
* 2.5 视频、音频各类总时长不得超过 30 秒，2.0 系列不得超过 15 秒。数量通过不代表总时长合规，素材规格和总时长仍由生成服务检查。
## 请求示例
### 指定随机种子
`seed` 必须是 JSON 整数（例如 `42` 或 `0`），不能传字符串、小数或 `null`。省略时不注入默认值；模型服务决定具体取值范围和生成效果。固定种子不保证重复请求生成完全相同的视频。
```json
{
"model": "doubao-seedance-2-0-260128",
"content": [{"type": "text", "text": "城市的清晨，街道人流缓缓移动，镜头保持静止"}],
"resolution": "480p",
"duration": 4,
"ratio": "16:9",
"seed": 42
}
```
### 首尾帧
2.5 首帧、首尾帧必须 `adaptive`；不会把显式宽高比静默改成 `adaptive`。
```json
{
"model":"doubao-seedance-2-5-260628",
"content":[
{"type":"text","text":"The scene gradually changes from dawn to sunset"},
{"type":"image_url","role":"first_frame","image_url":{"url":"https://example.com/first.jpg"}},
{"type":"image_url","role":"last_frame","image_url":{"url":"https://example.com/last.jpg"}}
],
"ratio":"adaptive",
"duration":5
}
```
### 编辑和延长
* 编辑：必须有 `reference_video`，`ratio` 必须 `adaptive`，`duration` 必须 `-1`，待编辑视频 4–30 秒。
* 延长：必须有 `reference_video` 和 `adaptive` 比例，时长可为 4–30 或 `-1`。
* 设为 `auto` 时模型自行判断任务类型。提交成功后仍可能因类型与参数不匹配而异步失败，检查终态 `error`。
```json
{
"model":"doubao-seedance-2-5-260628",
"content":[
{"type":"text","text":"Change the background of the reference video to a garden"},
{"type":"video_url","role":"reference_video","video_url":{"url":"https://example.com/reference.mp4"}}
],
"omni_reference_task_type":"edit",
"ratio":"adaptive",
"duration":-1,
"output_format":"mov"
}
```
### 草稿与正式视频
第一步：2.5、`draft:true`、`resolution:"480p"` 创建草稿并等待成功。第二步：把成功草稿的公开 ID 作为 `draft_task.id`：
```json
{
"model":"doubao-seedance-2-5-260628",
"content":[{"type":"draft_task","draft_task":{"id":"task_<草稿任务标识>"}}],
"resolution":"1080p",
"output_format":"mov",
"return_last_frame":true
}
```
* 正式视频默认且仅支持 `1080p`；`draft` 必须省略或为 `false`。
* 提示词、输入素材、`duration`、`ratio`、`seed`、`generate_audio`、`omni_reference_task_type` 自动复用草稿，不得再次传入。其他允许字段可重新指定，省略按模型默认。
* 草稿须属于当前账户、已成功、使用同一模型，且仍在七天查询窗口内。
* 草稿和正式视频是独立任务，分别收费；正式视频继承草稿是否含参考视频的计价类别。
### Python SDK
```python
import os
import time
from arkruntime import Ark
client = Ark(
base_url="https://api.vibelab.me/api/v3",
api_key=os.environ["LOOPTOKEN_API_KEY"],
)
task = client.content_generation.tasks.create(
model="doubao-seedance-2-0-mini-260615",
content=[{"type":"text","text":"A paper boat sails across a quiet lake"}],
duration=4,
resolution="480p",
)
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
result = client.content_generation.tasks.get(task_id=task.id)
if result.status == "succeeded":
print(result.content.video_url)
break
if result.status in {"failed", "expired", "cancelled"}:
raise RuntimeError(result.error)
time.sleep(5)
else:
raise TimeoutError(f"Continue querying existing task {task.id}")
```
## 响应
创建成功返回 HTTP 200 和 `{"id":"task_<任务标识>"}`，见[快速开始](#快速开始)。用该 `id` 查询任务；状态 `queued`、`running` 继续轮询，`succeeded`、`failed`、`expired`、`cancelled` 为终态。
### 查询任务
```bash
curl "https://api.vibelab.me/api/v3/contents/generations/tasks/$TASK_ID" \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
```json
{
"id":"task_<任务标识>",
"model":"doubao-seedance-2-5-260628",
"status":"succeeded",
"cgt_id":"cgt-<火山任务标识>",
"content":{
"video_url":"https://example.com/result.mp4",
"last_frame_url":"https://example.com/result-last-frame.jpg"
},
"error":null,
"duration":5,
"resolution":"720p",
"ratio":"16:9",
"framespersecond":24,
"generate_audio":true,
"usage":{"completion_tokens":108900,"total_tokens":108900},
"created_at":1791130000,
"updated_at":1791130060
}
```
| 字段 | 类型 | 含义 |
| ---------------------------------------------- | ------------- | --------------------------------------------------------------------------------- |
| `id`、`model`、`status` | string | 稳定任务 ID、实际模型版本、任务状态 |
| `cgt_id` | string | `running`、`succeeded` 且已获取火山任务 ID 时返回，原样透传 `cgt-...`，不替换 `id`；查询、列表、回调均适用；尚未获取时省略 |
| `content.video_url` | string | 成功后的视频 URL |
| `content.last_frame_url` | string | 请求尾帧时返回，保留上游 PNG/JPEG 格式和原始内容，尺寸与输出视频相同 |
| `created_at`、`updated_at` | integer | Unix 秒 |
| `duration` | integer | 实际帧数 / 24 向下取整的秒数，可能与实际媒体时长略有差异 |
| `resolution`、`ratio`、`output_format` | string | 实际输出规格 |
| `framespersecond` | integer | 输出帧率 |
| `generate_audio`、`draft` | boolean | 音频、样片标志 |
| `draft_task_id` | string | 正式视频对应的公开草稿任务 ID，为平台稳定 ID |
| `error` | object / null | 失败时 `code`、`message`；成功时 `null` |
| `execution_expires_after`、`priority` | integer | 任务超时阈值、执行优先级 |
| `service_tier`、`safety_identifier` | string | 服务等级、已传入的终端用户标识 |
| `tools` | object\[] | 实际工具，项含 `type` |
| `usage.completion_tokens`、`usage.total_tokens` | integer | 上游返回的实际 Token 用量 |
| `usage.tool_usage.web_search` | integer | 实际搜索次数，使用工具时可返回 |
* 可选字段按实际任务响应返回。`seed` 仅在模型服务返回时透传，不会用请求值伪造响应；`frames` 不主动构造。Token 用量不会被隐藏，也不会把 admission 预估值当实际用量返回。
* `queued`、`running` 时每 5–10 秒继续查询；`succeeded` 读 `content`；`failed`、`expired`、`cancelled` 均为终态。HTTP 200 可能携带失败任务，必须检查 `status`。
* 任务记录仅在最近七天滚动窗口可查，窗口为 `[当前 UTC 秒时间戳 - 7 天, 当前 UTC 秒时间戳)`。
* 视频和尾帧 URL 有效期 24 小时，请及时下载。生成服务的下载次数限制仍然适用，2.5 视频最多下载 100 次。
### 查询列表
```bash
curl --get https://api.vibelab.me/api/v3/contents/generations/tasks \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
--data-urlencode 'page_num=1' \
--data-urlencode 'page_size=20' \
--data-urlencode 'filter.status=succeeded' \
--data-urlencode "filter.task_ids=$TASK_ID_1" \
--data-urlencode "filter.task_ids=$TASK_ID_2"
```
| Query 参数 | 类型 | 默认 / 范围 |
| --------------------- | --------- | ---------------------------------------------------------------- |
| `page_num` | integer | 1；1–500 |
| `page_size` | integer | 20；1–500 |
| `filter.model` | string | 不传；Endpoint ID 精确筛选，不是 Model ID |
| `filter.service_tier` | string | `default`；`default`、`flex` |
| `filter.status` | string | 不传；`queued`、`running`、`cancelled`、`succeeded`、`failed`、`expired` |
| `filter.task_ids` | string\[] | 不传；重复参数名传多个 ID |
响应 `{"total":整数,"items":[任务查询对象]}`。`total` 为筛选后的总数；超过最后一页时 `items` 为 `[]`，`total` 仍保留。按创建时间倒序，创建时间相同按任务 ID 定序。旧 `/v1` 任务不会混入。
### 回调
`callback_url` 接收 POST JSON，结构与任务查询相同，使用同一个公开任务 ID。排队、运行、成功、失败、过期等状态变化可产生回调。
* 接收端需在 5 秒内返回 2xx；失败最多尝试三次，间隔 30 秒。接收端应按 `id` 和 `status` 幂等处理。
* `callback_url` 必须是 HTTPS 公网地址，不能指向回环、内网或元数据地址，不接受重定向。也可以只用轮询。
## 计费
* 公式：费用 = Token 用量 / 1,000,000 × 对应档位 Token 单价 × 账户折扣。按实际 `usage.completion_tokens` 扣费。
* 默认折扣系数 `1`（原价），`0.8` 为八折；模型专属折扣覆盖通用折扣，不叠乘。已配置的原生专属绝对价格优先，也不叠加折扣。
* Token 单价按模型、输出分辨率、输入是否含参考视频分档。参考视频的输入总时长会影响计费用量，并非按文件个数固定加价；不要在 `completion_tokens` 上再加一次输入视频用量。缺少计费用量时不会按零元结算。
* 生成前按已配置销售档位预扣，成功后按实际用量结算，失败/过期释放预扣。预扣不是最终费用。
* 预扣按请求时长和分辨率估算输出用量（24 fps）；未指定或自动时长先按 5 秒估算，不用模型最大时长或统一 4K 预算。估算像素预算：480p 854×480、720p 1280×720、1080p 1920×1080、4k 3840×2160。实际宽高、参考视频用量和自动时长以生成服务返回为准，结算时补退差额。
* 提交时锁定价格版本和折扣，执行期间改价不影响该任务。草稿与正式视频分别结算。
* 与[Seedance 方舟原生素材库版](./seedance-native-assets)共用同一套 Token 基础价格，但两种模式的账户和模型折扣分别配置，互不继承。
* 积分换算 10 积分 = 1 美元（1 积分 = ¥0.7）；正数金额按平台精度向上取整，最低扣费 0.001 积分；最终费用以账户账单为准。
## 错误
HTTP 错误体：`{"error":{"code":"...","message":"..."}}`。
| HTTP | code | 触发场景 | 处理 |
| --------------- | -------------------------------------------------------- | -------------------------------------- | ----------------------------- |
| 400 | `MissingParameter`、`InvalidParameter` | 缺少必填项、类型或模型参数限制不符，`message` 为具体原因（见下表） | 修正必填项、类型或模型参数限制 |
| 401 | `AuthenticationError` | API Key 缺失或无效 | 检查 API Key |
| 403 | `AccessDenied`、`QuotaExceeded` | 模型/来源权限不足，或余额、账户额度不足 | 检查权限、余额与账户额度 |
| 404 | `InvalidEndpointOrModel.NotFound`、`InvalidTask.NotFound` | 模型、Endpoint 不存在，或任务不属于当前账户 / 已超出七天窗口 | 检查模型、Endpoint、任务归属及七天窗口 |
| 429 | `RateLimitExceeded` | 请求过于频繁 | 降低请求频率，遵循 `Retry-After` |
| 500 / 502 / 503 | `InternalServiceError`、`ServiceUnavailable` | 平台或上游异常，或没有兼容的原生视频通道 | 保留请求 ID；已有任务 ID 时先继续查询 |
| 503 | `SubmissionUnconfirmed` | 创建请求的提交结果无法确认 | 不要重新提交，保留 `X-Request-Id` 联系支持 |
常见 `400` 的 `message`：
| `message` | 处理 |
| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `model is required and must be a string` / `model is not supported` | 使用[模型](#模型)表中的 ID |
| `content must be a non-empty array of objects` | `content` 传非空数组 |
| `resolution is not supported by this model` | 分辨率取所选模型的范围 |
| `ratio is invalid` | 比例取[请求参数](#请求参数)中的枚举 |
| `duration must be -1 or between 4 and N` | 时长传 `4`–`N`（2.5 为 30，2.0 为 15）或 `-1` |
| `duration=-1 (auto duration) is not currently supported for this model; specify an integer duration between 4 and 30` | 当前可选通道不支持自动时长，改传 `4`–`30` 的整数 |
| `execution_expires_after must be between 3600 and 259200` | 任务有效期传 `3600`–`259200` |
| `omni_reference_task_type requires Seedance 2.5` | 仅 2.5 支持该字段 |
| `draft requires Seedance 2.5 at 480p` | 草稿须用 2.5 且 `resolution: "480p"` |
| `draft_task output requires resolution=1080p` / `draft_task cannot request draft=true` | 草稿转正式视频的规则见[草稿与正式视频](#草稿与正式视频) |
| `<字段> must be omitted when using draft_task` | 已自动复用的字段不得再次传入 |
| `video_url does not support Base64` | 视频传公网 URL 或 `asset://` |
| `first/last frame cannot be combined with reference media` | 首尾帧不能与参考素材混用 |
| `Seedance 2.0 audio requires an image or video` | 2.0 的参考音频须搭配图片或视频 |
| `this task requires ratio=adaptive` / `edit requires reference_video and duration=-1` / `extend requires reference_video` | 首帧、首尾帧、编辑、延长的约束见[编辑和延长](#编辑和延长) |
| `too many reference media items` | 参考素材数量超过模型上限（见[模型](#模型)表） |
## 注意事项
创建请求超时后不要盲目重新提交 → 已获得 ID 时查询原任务。HTTP 200 可能携带失败任务 → 必须检查 `status`。
* 视频和尾帧 URL 24 小时过期；任务记录七天后不可查 → 及时下载转存。
* 2.5 首帧/首尾帧/编辑/延长必须 `adaptive`，编辑还必须 `duration: -1` → 按此传参。
* 草稿转正式视频时，已自动复用的字段（提示词、素材、`duration`、`ratio`、`seed`、`generate_audio`、`omni_reference_task_type`）→ 不得再次传入。
* 本模式的 Endpoint ID、素材 ID 不能与素材库版互用。
# Seedance 方舟原生素材库版
Source: https://looptoken.vibelab.me/docs/video/seedance-native-assets
> Seedance 方舟原生素材库版：素材组与素材管理、真人认证，以及 /hub/api/v3 视频创建、查询、列表、删除，异步
本模式独立提供 v3 视频创建、查询、列表、删除，以及素材组、素材与真人认证接口。**素材库版与[Seedance 方舟原生接口](./seedance-ark)是两个独立模式**：视频 API Base 不同，任务、素材、Endpoint 绑定不能跨模式使用；相同 model ID 不会自动切换模式。
| 项 | 值 |
| ----------- | -------------------------------------------------------------------------- |
| 视频 API Base | `https://api.vibelab.me/hub/api/v3`（支持自定义地址的方舟视频 SDK 将 `base_url` 设为此地址） |
| 素材/认证入口 | `POST https://api.vibelab.me/?Action=&Version=2024-01-01`，JSON 请求体 |
| 鉴权 | `Authorization: Bearer `，无需 AK/SK 或 V4 签名 |
| 模式 | 视频异步：创建 → 轮询 `GET /hub/api/v3/contents/generations/tasks/{id}` |
| 计费 | 按 `usage.completion_tokens`，见[计费](#计费) |
| 媒体保留 | 视频产物 URL 最长 24 小时，任务记录仅最近 7 天可查；素材临时链接最长 12 小时 |
* 请求字段、Action 名称、成功响应使用方舟原生格式。官方 SDK 中需要 AK/SK 的管理客户端不能直接使用此鉴权，请按下文 HTTP 示例调用。
* `/api/v3` 属于独立的方舟原生接口，不能用来访问本模式任务。两种模式可用同一把 LoopToken Key，仍须分别获得对应模式和模型的访问权限。
* 素材功能需要账户、Key、模型均获准使用本模式。受限 Key 按原有权限访问，不获得额外权限。
## 快速开始
```bash
curl 'https://api.vibelab.me/hub/api/v3/contents/generations/tasks' \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model":"doubao-seedance-2-5-260628",
"content":[{"type":"text","text":"一只猫在阳光下散步"}],
"duration":5,"resolution":"720p","ratio":"16:9","watermark":false
}'
```
成功返回 HTTP 200，`id` 原样使用上游创建接口返回的任务 ID（兼容 `output.task_id`），不替换为平台生成的任务编号：
```json
{"id":"cgt-上游任务标识"}
```
这是异步任务，保存 `id`，用本模式的 v3 查询接口检查状态；创建成功不代表视频已生成。
## 模式选择
| 要做什么 | 怎么调用 |
| ------------ | ------------------------------------------------------------------------------ |
| 生成视频 | `POST /hub/api/v3/contents/generations/tasks`，见[视频参数](#视频参数) |
| 查询、列出、删除视频任务 | `GET` / `DELETE /hub/api/v3/contents/generations/tasks[/{id}]`，见[响应](#响应) |
| 管理素材组与素材 | `POST /?Action=&Version=2024-01-01`，见[素材 Action](#素材-action) |
| 真人认证 | `CreateVisualValidateSession` / `GetVisualValidateResult`，见[真人认证 H5](#真人认证-h5) |
## 请求参数
### 视频参数
支持的模型 ID（实际开放状态与售价以账户权限及平台价格配置为准）：`doubao-seedance-2-0-260128`、`doubao-seedance-2-0-fast-260128`、`doubao-seedance-2-0-mini-260615`、`doubao-seedance-2-5-260628`。也可用平台为本模式绑定的 Endpoint ID；另一模式的 Endpoint 绑定不能复用。
创建请求是 JSON 对象，控制参数在顶层，媒体在 `content` 数组；不要使用 `/v1` 接口的扁平 `prompt` 请求体。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------------- | ------- | -- | -- | ------------------------------------------------- |
| `model` | string | 是 | - | 上述模型 ID 或本模式已绑定的 Endpoint ID |
| `content` | array | 是 | - | 非空的文本、图片、视频、音频数组 |
| `duration` | integer | 否 | - | 秒数：2.0 系列 4–15，2.5 为 4–30；`-1` 自动选择 |
| `resolution` | string | 否 | - | `480p`、`720p` 等模型支持的档位；通常用 `720p` |
| `ratio` | string | 否 | - | `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive` |
| `seed` | integer | 否 | - | 随机种子，原样透传；不能保证相同种子完全复现画面，具体取值范围与效果由模型服务决定 |
| `generate_audio` | boolean | 否 | - | 是否生成音频 |
| `watermark` | boolean | 否 | - | 是否添加水印 |
| `callback_url` | string | 否 | - | 可公开访问的 HTTPS 回调地址；回调使用创建时返回的上游任务 ID |
| `execution_expires_after` | integer | 否 | - | 任务过期秒数，`3600`–`259200` |
附加生成参数与未列出的扩展字段默认透传，保留原始值和嵌套结构，支持范围由模型服务校验。平台仍执行模型权限、素材归属、路由、计费及回调所需校验；参数被接受不代表模型服务保证支持或生效。
省略控制参数时保留模型服务的默认行为。分辨率、时长、媒体组合仍须符合所选模型能力。创建前预冻结积分，完成后按核实的生成用量结算。
`content` 结构：
| type | 内容字段 | role |
| ----------- | --------------- | ---------------------------------------------- |
| `text` | `text` | 不需要 |
| `image_url` | `image_url.url` | `reference_image`、`first_frame` 或 `last_frame` |
| `video_url` | `video_url.url` | `reference_video` |
| `audio_url` | `audio_url.url` | `reference_audio` |
* 图片、视频、音频可用无需登录的公网 URL，或本模式返回的 `asset://asset-公开标识`。图片与音频也可用对应 MIME 的 Base64 数据 URL；视频不支持 Base64。请求体上限 64 MiB。
* 首尾帧不能与参考图模式混用。
### 素材 Action
| Action | 请求字段 | Result |
| --------------------------- | ---------------------------------------------------------------- | -------------------------------- |
| CreateAssetGroup | Name，Description 可选，GroupType 仅 AIGC，LibraryKey 可选 | Id |
| ListAssetGroups | Filter.GroupType，分页/排序，LibraryKey 可选筛选 | Items，Libraries；页码模式带 TotalCount |
| GetAssetGroup | Id | 素材组信息 |
| UpdateAssetGroup | Id，Name/Description | Id |
| DeleteAssetGroup | Id | 空对象 |
| CreateAsset | GroupId，URL，AssetType，Name 可选，Moderation 可选 | Id |
| ListAssets | Filter.GroupType，GroupIds/Name/Statuses 可选，分页/排序，LibraryKey 可选筛选 | Items；页码模式带 TotalCount |
| GetAsset | Id | 素材信息，含 Status 与临时 URL |
| UpdateAsset | Id，Name | Id |
| DeleteAsset | Id | 空对象 |
| CreateVisualValidateSession | CallbackURL，LibraryKey 可选 | H5Link，BytedToken，CallbackURL |
| GetVisualValidateResult | BytedToken | GroupId（完成后） |
* 可用素材库以 `ListAssetGroups` 返回的 `Libraries` 为准（每项含 `LibraryKey` 与 `Name`），库的数量和可用模型可能调整，不要写死。建组或发起真人认证时可传 `LibraryKey` 指定素材库，不传则落平台默认库；只有一个库时无需传。素材组、素材条目带 `LibraryKey` 字段，`ListAssetGroups` / `ListAssets` 可按 `LibraryKey` 筛选。
* 全部操作支持可选 `ProjectName`，默认 `default`。资源 ID、认证 token、分页 token 仅在当前账户及项目下有效。
* 同一账户的多把 Key 可按各自权限访问该账户资源；不同账户完全隔离。直接传入他人的 ID 返回资源不可用，不暴露是否存在。素材组删除后，其素材引用与下载链接均失效。
* `Name` 最长 64 字符，素材组 `Description` 最长 300 字符。`AssetType` 为 Image、Video 或 Audio。
* 素材状态 Processing、Active、Failed，只有 Active 可用于生成。
* `Moderation` 若提供，必须是 `{"Strategy":"Default"}`。
* 真人素材必须经过认证，无法通过 CreateAssetGroup 自行创建 LivenessFace 素材组；在已有真人组追加素材时，仍由服务检查人脸一致性与审核。
#### 素材组与素材示例
```bash
curl 'https://api.vibelab.me/?Action=CreateAssetGroup&Version=2024-01-01' \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" -H 'Content-Type: application/json' \
-d '{"Name":"产品参考","Description":"产品视频使用","GroupType":"AIGC"}'
```
```json
{"ResponseMetadata":{"RequestId":"请求标识","Action":"CreateAssetGroup","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},"Result":{"Id":"group-公开标识"}}
```
```bash
curl 'https://api.vibelab.me/?Action=CreateAsset&Version=2024-01-01' \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" -H 'Content-Type: application/json' \
-d '{"GroupId":"group-公开标识","Name":"参考图","AssetType":"Image","URL":"https://example.com/reference.png"}'
```
* 素材 URL 必须无需登录即可访问。控制台也提供文件上传。
* 创建返回 Id 后调用 GetAsset 检查处理状态；控制台可用“刷新状态”。
* 素材临时访问链接有效期最长 12 小时，需下载时重新查询；删除或账户禁用可提前使链接失效。
以下是各 Action 的 body 示例（HTTP 调用时 Action 放 query，body 放 JSON 请求体）：
```json
{"Action":"GetAsset","body":{"Id":"asset-公开标识"}}
{"Action":"GetAssetGroup","body":{"Id":"group-公开标识"}}
{"Action":"UpdateAssetGroup","body":{"Id":"group-公开标识","Name":"新名称","Description":"新描述"}}
{"Action":"DeleteAssetGroup","body":{"Id":"group-公开标识"}}
{"Action":"UpdateAsset","body":{"Id":"asset-公开标识","Name":"新名称"}}
{"Action":"DeleteAsset","body":{"Id":"asset-公开标识"}}
```
#### 列表与分页
`Filter` 必填，`GroupType` 为 AIGC 或 LivenessFace。可按 Name、GroupIds 过滤；ListAssets 还支持 Statuses 数组。
```json
{"Action":"ListAssetGroups","body":{"Filter":{"GroupType":"AIGC"},"PageNumber":1,"PageSize":20}}
{"Action":"ListAssets","body":{"Filter":{"GroupType":"AIGC","GroupIds":["group-公开标识"],"Statuses":["Active"]},"MaxResults":20}}
```
| 模式 | 参数 | 规则 |
| ----- | --------------------------------------------- | ------------------------------------------------------------------------ |
| 页码 | `PageNumber`（从 1 开始）+ `PageSize`（1–100），必须同时传 | 带 TotalCount；素材组 `PageNumber × PageSize > 10000`、素材超过 20000 时改用 token 模式 |
| token | `MaxResults`（默认 10，1–100）+ 上一页的 `NextToken` | 不返回 TotalCount；无 NextToken 表示结束；token 有效期 1 小时 |
* 两种模式不能混用。取下一页时保持筛选、排序、项目、MaxResults 一致。
* `SortBy` 支持 CreateTime、UpdateTime；ListAssets 另支持 GroupId。`SortOrder` 为 Asc 或 Desc，默认 Desc。列表与计数仅含当前账户资源。
#### 真人认证 H5
```bash
curl 'https://api.vibelab.me/?Action=CreateVisualValidateSession&Version=2024-01-01' \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" -H 'Content-Type: application/json' \
-d '{"CallbackURL":"https://your-app.example/verified"}'
```
```json
{"Action":"GetVisualValidateResult","body":{"BytedToken":"validate-公开标识"}}
```
* 返回 `H5Link` 与公开 `BytedToken`。把 **H5Link 原样展示给用户**，用户打开链接完成活体认证；链接可能使用认证服务域名，属于此流程的授权例外。会话有效期 30 分钟。API Key 不会放入链接。
* 成功后 `GetVisualValidateResult` 返回当前账户的 GroupId，可调用 ListAssets 查询该真人组。未完成返回 AuthenticationPending，可稍后重查。
* 认证结束后浏览器跳转 CallbackURL，带 `bytedToken`、`resultCode`，成功时附公开 GroupId。浏览器参数不能作为授权依据：服务端必须用原 Key 调 GetVisualValidateResult 确认。
## 请求示例
引用素材生成视频：
```json
{
"model":"doubao-seedance-2-0-260128",
"content":[
{"type":"text","text":"人物向镜头挥手"},
{"type":"image_url","image_url":{"url":"asset://asset-公开标识"},"role":"reference_image"}
],
"duration":5,"resolution":"720p"
}
```
素材引用使用本平台返回的公开 Asset Id。生成前检查所有权、状态、媒体类型与真人认证关系。素材须属于同一素材渠道和同一项目，并使用该项目可用的模型/Endpoint；项目与模型的兼容性仍由生成服务校验。其他模式不能使用本模式素材。
## 响应
创建成功返回 HTTP 200 和 `{"id":"cgt-上游任务标识"}`，见[快速开始](#快速开始)。用该 `id` 查询任务，`status` 取值见下。
### 查询视频
```bash
curl 'https://api.vibelab.me/hub/api/v3/contents/generations/tasks/cgt-上游任务标识' \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
```json
{
"id":"cgt-上游任务标识",
"model":"doubao-seedance-2-5-260628",
"status":"succeeded",
"duration":5,"resolution":"720p",
"content":{"video_url":"https://api.vibelab.me/native-assets/media/临时访问标识"},
"usage":{"completion_tokens":12345,"total_tokens":12345}
}
```
* 建议每 5–10 秒查询一次。`status`：`queued`（排队）、`running`（生成中）、`succeeded`（成功）、`failed`（失败）、`expired`（过期）。
* 字段以实际返回为准，`usage` 中的用量并非每次都齐全。
* 任务响应、列表、回调使用同一上游任务 ID；旧平台任务 ID 仍可作为查询、筛选、删除的兼容别名。
* 视频产物 URL 为平台临时链接，最长 24 小时，请及时下载。查询范围为最近 7 天。
* 任务不存在、属于另一账户或属于另一模式时返回 404。
提交网络异常、响应损坏或未返回任务 ID 时可能仍已接单。此时返回 HTTP 503，`error.code=SubmissionUnconfirmed`，不返回虚构的任务 ID。**不要重新提交相同付费任务** → 保留响应头 `X-Request-Id` 联系管理员核对。
* 冻结额度保留，由管理员核对后恢复查询或退款。未确认的提交不会出现在视频任务列表中；核对确认未创建时，回调用 `request_id` 关联原始请求，不提供任务 `id`。
* 缺少可计费用量的成功任务也需要核对，不会当成免费生成。
### 视频列表
```bash
curl 'https://api.vibelab.me/hub/api/v3/contents/generations/tasks?page_num=1&page_size=20&filter.status=succeeded' \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
返回 `{"total":1,"items":[任务对象]}`，只含当前账户、当前模式及当前 Key 有权限访问的最近 7 天任务。
| 查询参数 | 说明 |
| --------------------- | ------------------------------------- |
| `page_num` | 页码，从 1 开始，默认 1，最大 500 |
| `page_size` | 每页条数，默认 20，最大 500 |
| `filter.status` | 按任务状态筛选 |
| `filter.task_ids` | 按上游任务 ID 筛选（兼容旧平台任务 ID），可重复传入 |
| `filter.model` | 本模式绑定的 Endpoint ID，以 `ep-` 开头 |
| `filter.service_tier` | `default` 或 `flex`；本模式创建仅支持 `default` |
视频列表用小写 query 参数；素材 Action 列表用上文的 JSON 分页字段，两者不能混用。
### 删除视频记录
```bash
curl -X DELETE 'https://api.vibelab.me/hub/api/v3/contents/generations/tasks/cgt-上游任务标识' \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
* 仅删除已结束且完成计费核对的任务记录，成功返回 HTTP 200 和 `{}`，其平台产物访问链接随之失效。
* 不会取消生成，也不会撤销已结算费用。
* 排队中、处理中或尚未完成计费核对返回 409 → 继续查询原任务。另一账户或另一模式的任务返回 404。
## 计费
* 视频生成与[Seedance 方舟原生接口](./seedance-ark)共用同一套 Token 基础价格，按模型、分辨率、是否含参考视频选档，按 `usage.completion_tokens` 结算，不按视频秒数收费。创建时预扣估算额度，结算按返回的生成 Token 数计算。
* 两种模式的折扣独立：管理员在用户列表选“素材折”，可设素材库版通用折扣和模型折扣；模型留空继承素材库版通用折扣，默认系数 `1` 为原价，`0.8` 为八折。原生接口已有的折扣不会自动应用到素材库版。
* 共用基础价中的原生专属绝对价优先，不叠加折扣；新折扣仅影响新任务，已创建任务按创建时锁定的价格档位与折扣结算。
* 素材管理和真人认证本身不按视频生成 Token 计费。
* 用户可在控制台“模型价格”的“Seedance 方舟原生素材库版”分组查看自己的有效 Token 价格。
## 错误
素材 Action 错误采用 `ResponseMetadata.Error`，含 Code、Message，请求标识与 Action 保留，错误内容经过净化。视频接口错误体 `{"error":{"code":"错误码","message":"说明"}}`：400 参数问题；401/403 Key 或模式权限问题；404 模型或任务不可访问；409 无法删除当前任务；503 本模式暂无可用服务。
| HTTP | code | 触发场景 | 处理 |
| --------- | -------------------------------------------------- | ----------------------------------- | ------------------------------ |
| 400 | `InvalidParameter` | 参数、分页或素材类型不合法 | 检查参数、分页及素材类型 |
| 401 / 403 | 鉴权错误 / `AccessDenied` | Key 无效，或账户、Key、模型未获准使用本模式 | 检查 Key 与权限 |
| 404 | `InvalidAsset.NotFound` | 素材资源不存在、已删除或无访问权限；任务不存在或属于另一账户、另一模式 | 检查 ID 与归属 |
| 409 | `AuthenticationPending` / `AuthenticationConflict` | 真人认证未完成或会话冲突；删除时任务尚未结束或未完成计费核对 | 等待认证完成或重新核对会话；继续查询原任务 |
| 502 / 503 | `ServiceUnavailable` | 本模式暂无可用服务 | 稍后重试查询；创建请求结果不明确时先核对 |
| 503 | `SubmissionUnconfirmed` | 创建请求提交结果无法确认 | 不要重新提交，保留 `X-Request-Id` 联系管理员 |
## 注意事项
* **创建请求超时或未返回任务 ID** → 不要重新提交，先按[查询视频](#查询视频)中的说明保留 `X-Request-Id` 核对。
* **素材 `asset://` 引用** → 只能用本模式返回的素材，只有 `Active` 状态可用于生成；其他模式不能使用。
* **视频产物 URL 与素材临时链接** → 有时效，及时下载转存。
* **`/api/v3` 任务与本模式任务** → 互不可见，查询范围仅最近 7 天。
# Seedance 系列
Source: https://looptoken.vibelab.me/docs/video/seedance
> Seedance 2.0/2.5 全系列：文生、首帧、首尾帧、参考图/视频/音频生成与 2.5 编辑延长，/v1 异步，用 GET /v1/tasks/{task_id} 查询
Seedance 支持文生视频、首帧、首尾帧过渡、参考图/视频/音频驱动，以及可选的自动音频。官方模型名的 `/api/v3` 创建、查询、列表及自动时长、草稿功能，见[Seedance 方舟原生接口](/video/seedance-ark)；本页描述 `/v1` 路径。
| 项 | 值 |
| ---- | ------------------------------------------------------- |
| 模型 | 见[适用模型](#适用模型)，同代按后缀区分通道，请求体形状完全一致 |
| 模式 | 异步：提交（HTTP `202`）→ 每 5-10 秒轮询 `GET /v1/tasks/{task_id}` |
| 计费 | 多数按秒（实际时长 × 分辨率档位单价）；按次版（`-c` 系列）按条，见[计费](#计费) |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时，见[响应](#响应) |
请求体用顶层 `content`、`ratio`、`duration`。不要把 Wan 系列的 `input`、`parameters` 请求体用于本页模型。
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-0-260128",
"ratio": "16:9",
"content": [{"type": "text", "text": "海边日落，海浪拍打礁石，镜头缓慢横移，电影级光影"}],
"duration": 5
}'
```
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "doubao-seedance-2-0-260128",
"status": "pending",
"progress": 0,
"created_at": 1783819200,
"duration": 5,
"resolution": "720p"
}
```
轮询：`GET /v1/tasks/{task_id}`。`pending`/`running` 继续轮询；`succeeded` 读 `video_url`；`failed` 读 `error`。
## 模式选择
| 模式 | 怎么传参 | 支持的模型 |
| ---------- | ----------------------------------------------------------------------------- | ---------------------- |
| 文生视频 | `content` 只含 `text` | 全部 |
| 首帧 / 首尾帧 | `image_url` 加 `role: first_frame` / `last_frame`，`ratio` 用 `adaptive`（2.5 必须） | `doubao-` 开头模型、`-duo` |
| 多图 / 多素材参考 | `image_url` 全部标 `role: reference_image`，可加 `video_url`、`audio_url`；不要与首尾帧混传 | 全部（素材上限见[适用模型](#适用模型)） |
| 视频编辑 / 延长 | `omni_reference_task_type: "edit"` / `"extend"` 加参考视频 | 2.5 系列，见[适用模型](#适用模型) |
## 请求参数
请求头：`Authorization: Bearer `（必填），`Content-Type: application/json`（必填）。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------------------- | ------- | -- | ------------------ | --------------------------------------------------------------------------------------------------- |
| `model` | string | 是 | - | [适用模型](#适用模型)之一 |
| `content` | array | 是 | - | 提示词与素材数组，至少含一个 `text` 对象 |
| `resolution` | string | 否 | `720p` | 取值逐模型不同，见[适用模型](#适用模型) |
| `ratio` | string | 否 | `adaptive` | `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`；部分通道范围更窄，行为见[ratio 与 adaptive](#ratio-与-adaptive) |
| `duration` | integer | 否 | `-1`（2.5）/ `5`（其余） | 范围逐模型不同；`-1`（模型自动选择）只有 `doubao-` 开头的模型接受 |
| `generate_audio` | boolean | 否 | `true` | 是否生成与画面同步的人声、音效、背景音乐。`doubao-` 开头模型默认有声，要无声显式 `false` |
| `omni_reference_task_type` | string | 否 | `auto` | 2.5：`auto`、`edit`、`extend`；`seedance-2-5-duo` 四选一：`auto`、`reference`、`edit`、`extend`；其余分销版不支持 |
| `output_format` | string | 否 | `mp4` | 2.5：`mp4` 或适合后期的 `mov` |
| `return_last_frame` | boolean | 否 | `false` | 任务结果是否返回最后一帧 |
| `watermark` | boolean | 否 | `false` | 右下角是否加“AI 生成”水印 |
| `priority` | integer | 否 | `0` | 排队优先级 `0-9`，越大越优先 |
| `execution_expires_after` | integer | 否 | `172800` | 任务过期阈值，秒，`3600-259200` |
| `callback_url` | string | 否 | - | 终态回调地址，必须是公网可访问的 HTTPS |
### content 对象
| `type` | 必填字段 | `role` | 说明 |
| ----------- | --------------- | ---------------------------------------------------- | ----------------------------------------------- |
| `text` | `text` | 无 | 提示词，描述主体、动作、镜头、场景、光影、风格、音效。多张参考图时应说明每张图的用途 |
| `image_url` | `image_url.url` | `first_frame` / `last_frame` / `reference_image`（必填） | 公网 HTTP/HTTPS URL 或 `data:{MIME};base64,{data}` |
| `video_url` | `video_url.url` | 固定 `reference_video` | 公网可访问的 MP4 URL |
| `audio_url` | `audio_url.url` | 固定 `reference_audio` | 公网可访问的 MP3 URL |
`role` 数量限制：
| role | 用途 | 数量 |
| ----------------- | ------------- | ---------------------------- |
| `first_frame` | 指定第一帧 | 最多 1 张 |
| `last_frame` | 指定最后一帧，首尾平滑过渡 | 最多 1 张；应与 `first_frame` 同时使用 |
| `reference_image` | 参考人物、物体、场景、风格 | 全部图片合计最多 9 张（2.5 见下） |
素材上限：
| | 图片 | 参考视频 | 参考音频 |
| --- | ---- | --------------- | ----------------------- |
| 2.5 | 30 张 | 10 个，总时长 ≤ 30 秒 | 10 个，总时长 ≤ 30 秒，支持纯音频参考 |
| 2.0 | 9 张 | 3 个 | 3 个，必须同时含至少一张图或一个视频 |
* 2.5 单次图片、视频、音频合计最多 50 个素材。各通道例外见[适用模型](#适用模型)。
* 传参考音频时，`generate_audio` 决定是否同时生成额外配音或音效。
* 多素材参考时每张图都标 `reference_image`，不要与 `first_frame`/`last_frame` 混在一次请求：上游按 role 判断是“多图参考”还是“首尾帧过渡”，混传按后者处理。
* 提示词里用 `@图1`、`@视频1`（分销版 `@图片1`）指代素材，编号按各自类型在 `content` 中的出现顺序从 1 起。
### 适用模型
`seedance-2-5` 与 `seedance-2-0` 是两代标准款，参数范围最窄，不确定选哪个先用它们试跑通。同代下按后缀区分通道：`-max`、`-hig` 长片版，`-duo` 分销版，`seedance-2.5-c`、`seedance-2.5-c1`、`seedance-2.5-c2`、`seedance-2.5-c7`、`seedance-2.0-c` 按次版。请求体形状一致，差别只在参数范围、计费方式和出片速度。
`ratio` 取值缩写：**R7** = `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`；**R6** = R7 去掉 `adaptive`；`无` = 不支持，`—` = 原文未单列。素材上限写作 图/视频/音频。
**按秒计费 · Seedance 2.5**
| 模型 | `resolution` | `duration` | `ratio` | 首/尾帧 | 素材上限 |
| --------------------------- | --------------------- | --------------- | ------- | ---- | -------- |
| `seedance-2-5` | `480p`/`720p` | `4`-`30`，默认 `5` | R7 | 无 | 30/10/10 |
| `doubao-seedance-2-5-cloud` | `480p`/`720p`/`1080p` | `4`-`30`，可 `-1` | R7 | 支持 | 30/10/10 |
| `seedance-2-5-max` | `480p`/`720p`/`1080p` | `4`-`30`，默认 `5` | R6 | 无 | — |
| `seedance-2-5-hig` | `480p`/`720p` | `4`-`30` | R7 | 无 | 30/10/— |
| `seedance-2-5-duo` | `480p`/`720p`/`1080p` | `4`-`30` | R7 | 支持 | 30/10/10 |
**按秒计费 · Seedance 2.0**
| 模型 | `resolution` | `duration` | `ratio` | 首/尾帧 | 素材上限 |
| --------------------------------- | -------------------------- | --------------- | ------- | ---- | ----- |
| `seedance-2-0` | `480p`/`720p` | `4`-`15`，默认 `5` | R7 | 无 | 9/3/3 |
| `seedance-2-0-hig` | `480p`/`720p` | `4`-`15` | R7 | 无 | 9/3/— |
| `seedance-2-0-duo` | `480p`/`720p`/`1080p`/`4k` | `4`-`15` | R7 | 支持 | 9/3/3 |
| `seedance-2-0-fast-duo` | `480p`/`720p` | `4`-`15` | R7 | 支持 | 9/3/3 |
| `seedance-2-0-mini-duo` | `480p`/`720p` | `4`-`15` | R7 | 支持 | 9/3/3 |
| `doubao-seedance-2-0-260128` | `480p`/`720p`/`1080p`/`4k` | `4`-`15`，可 `-1` | R7 | 支持 | 9/3/3 |
| `doubao-seedance-2-0-fast-260128` | `480p`/`720p` | `4`-`15`，可 `-1` | R7 | 支持 | 9/3/3 |
| `doubao-seedance-2-0-mini-260615` | `480p`/`720p` | `4`-`15`，可 `-1` | R7 | 支持 | 9/3/3 |
**按次计费**（每条一个价，见[按次版](#按次版-c)）
| 模型 | `resolution` | `duration` | `ratio` | 首/尾帧 | 素材上限 |
| ----------------- | -------------------------- | --------------- | ------------ | ---- | -------- |
| `seedance-2.5-c` | `480p`/`720p`/`1080p` | `4`-`30`，默认 `5` | R7 | 按参考图 | 30/10/10 |
| `seedance-2.5-c1` | `720p` | `4`-`30`，默认 `5` | R7 去掉 `21:9` | 按参考图 | 9/3/3 |
| `seedance-2.5-c2` | `720p`/`1080p` | `4`-`30`，默认 `5` | R7 | 按参考图 | 30/10/10 |
| `seedance-2.5-c7` | `720p` | `4`-`30`，默认 `5` | R7 | 按参考图 | 30/10/10 |
| `seedance-2.0-c` | `480p`/`720p`/`1080p`/`4k` | `4`-`15`，默认 `5` | R7 | 按参考图 | 9/3/3 |
实际可用模型与价格以[模型列表](/models)为准。越界参数统一返回 400（任务不建立、不计费），下文不再逐条重复。
#### 标准版
`seedance-2-5`、`seedance-2-0`：
| 项 | `seedance-2-5` | `seedance-2-0` |
| ------- | -------------- | -------------- |
| 提示词长度 | 最多 15000 字符 | 最多 5000 字符 |
| 参考图 | 可选，最多 30 张 | 可选，最多 9 张 |
| 参考视频 | 可选，最多 10 条 | 可选，最多 3 条 |
| 参考音频 | 可选，最多 10 条 | 可选，最多 3 条 |
| 首帧 / 尾帧 | **不支持** | **不支持** |
* `ratio` 取值同 R7（含 `adaptive`），不传按 `16:9` 出片。
* 图片只能用 `role: reference_image`，带 `first_frame`/`last_frame` 返回 400。
* 提示词不能为空，只传参考图返回 400。
* 以下顶层字段带了返回 400（`message` 为 `<字段> is not supported for <模型>`）：`seed`、`camera_fixed`、`return_last_frame`、`draft`、`service_tier`、`execution_expires_after`、`omni_reference_task_type`。`generate_audio` 不报错，但会被忽略。
* `seedance-2-0` 写 20 秒返回 400（上限 15 秒），要更长用 `seedance-2-5`。`duration` 不传按 5 秒出片。
* `seedance-2-5` 不再有 `1080p`，要 `1080p` 用 `seedance-2-5-max`。
* 带参考视频按加价档计费，每秒比同分辨率纯文生贵一档。
#### 2.5 特殊约束（`doubao-seedance-2-5-cloud` 等 2.5 模型）
* 首帧、首尾帧、视频编辑、视频延长必须 `ratio: "adaptive"`。
* 编辑：`omni_reference_task_type: "edit"`、`duration: -1`，至少一个 4-30 秒参考视频。
* 延长：`omni_reference_task_type: "extend"`，至少一个参考视频。
* 2.5 不支持 `4k`。
#### 长片版（`-max`、`-hig`）
长片版共同点：按秒计费、不支持首帧/尾帧（带 `first_frame`/`last_frame` 返回 400）、回报真实 `progress`、不传 `ratio` 一律按 `16:9` 出片（要自适应显式写 `adaptive`）、`role: reference_video` 都收。
| | `seedance-2-5-max` | `-hig` |
| ----------------- | -------------------------------------------- | ------------------------------------ |
| `resolution` | `480p`/`720p`/`1080p`，不传按 `720p`；`4k` 返回 400 | 只有 `480p`/`720p`，`1080p`/`4k` 返回 400 |
| 参考素材 | 可选，纯文生可用 | 可选，纯文生可用 |
| 参考视频计费 | 加价档，每秒比纯文生贵一档（同 `doubao-seedance-2-5-cloud`） | 恒为同分辨率不带视频时的 **1.7 倍** |
| 参考音频 | — | 支持 |
| `ratio: adaptive` | 返回 400 | 支持 |
| 出片耗时 | 20 秒的片实测 4-6 分钟，带参考图更慢 | — |
* `-max` 的比例范围为 R6（横竖屏之外还有 `1:1`、`4:3`、`3:4`、`21:9`），不要求带参考图。
* `duration`：2.5 是 `4`-`30`，2.0 是 `4`-`15`。按 2.5 写法给 2.0 的 `-hig` 发 20 秒返回 400。
* 素材上限按代走：2.5 的 `-hig` 最多 10 个视频、30 张图；2.0 的 `-hig` 最多 3 个视频、9 张图。超限返回 400。
##### 长片版的参考视频
**视频只当风格与氛围参考**：画面内容由提示词决定，源视频既不被照搬也不被逐帧改写。要按源视频逐帧编辑，用 `doubao-seedance-2-5-cloud` 的编辑任务。
单个视频须满足下表，否则提交后才失败，任务以 `upstream_error` 收尾、预扣全额退回：
| 项 | 要求 |
| --- | ------------------------------------- |
| 大小 | ≤ 200 MB |
| 时长 | `2`-`30` 秒 |
| 格式 | mp4 或 mov，视频编码 H.264/H.265，音频 AAC/MP3 |
| 分辨率 | `480p` 或 `720p` |
| 尺寸 | 宽高比 0.4-2.5，宽高各 300-6000 px |
| 帧率 | 24-60 FPS |
| 内容 | 不能含真人人脸 |
素材 URL 必须是可匿名直接下载的直链：上游拉素材不带 `User-Agent`、不跟随跳转。对 UA 有要求的图床（维基共享资源）返回 403，带 302 的随机图链接（`picsum.photos` 之类）拉不到，两者都在提交之后才失败，任务以 `upstream_error` 收尾、预扣全额退回。用自己的 OSS 或对象存储直链最稳。
##### 通道改投
同代长片通道不带参考视频时价格一致，换 `model` 后缀即可换产能：
| 改投 | 前提 |
| --------------- | ------------------------------------------- |
| `-max` → `-hig` | 没写 `1080p`；带参考视频时 `-hig` 按同分辨率不带视频价的 1.7 倍收 |
#### 分销版（`-duo`）
四个模型：`seedance-2-5-duo`、`seedance-2-0-duo`，以及 2.0 轻量款 `seedance-2-0-fast-duo`（速度款）、`seedance-2-0-mini-duo`（最便宜）。时长范围与长片版一样宽，但**支持首帧和尾帧**（长片版都不支持）；要长片又要首尾帧过渡，只能选这四个。
| 项 | `seedance-2-5-duo` | `seedance-2-0-duo` | `-2-0-fast-duo` | `-2-0-mini-duo` |
| -------------------------- | ---------------------------------- | ------------------------------------------ | --------------- | --------------- |
| `resolution` | `480p`、`720p`、`1080p` | `480p`、`720p`、`1080p`、`4k`（长片型通道里唯一有 `4k`） | `480p`、`720p` | `480p`、`720p` |
| `omni_reference_task_type` | `auto`、`reference`、`edit`、`extend` | 不支持，传了返回 400 | 同左 | 同左 |
| `720p` 单价（积分每秒） | 2.774 | 1.62 | 1.228 | 0.817 |
* 其余同[适用模型](#适用模型)：`duration`、R7、素材上限、首尾帧。
* 参考图可带可不带，只给提示词即文生视频。素材一律传公网 HTTPS 地址，不接受 Base64。
* `seedance-2-5-duo` 上游偶尔把多图参考判成首尾帧时，用 `omni_reference_task_type: "reference"` 显式钉死。
#### 按次版（`-c`）
`seedance-2.5-c`、`seedance-2.5-c1`、`seedance-2.5-c2`、`seedance-2.5-c7`、`seedance-2.0-c`：请求体与其他 Seedance 模型一致，照常传 `duration`、参考素材，**但按次计费**：同分辨率每条一个价，4 秒和 30 秒（2.0 为 15 秒）同价，带参考视频也不加价（`seedance-2.5-c2` 例外：与分辨率无关，按时长分 ≤15 秒、>15 秒两档价；`seedance-2.5-c7` 例外：带参考视频走单独的加价档）。适合长片；短片按秒模型更便宜。
* 不支持 `duration: -1`、`generate_audio: false`、`return_last_frame`、`draft`、编辑/延长，传了返回 400。
* `first_frame`/`last_frame` 图会收下，但按参考图交给上游，不保证严格作为首尾帧。
* `ratio: adaptive` 或不传时按 `16:9` 出片。
* 素材一律传公网 HTTPS 地址，不接受 Base64。
* `seedance-2.5-c7` 只出 `720p`（传 `480p`/`1080p` 返回 400），其余边界同 2.5（含 `21:9`，素材最多 30 图 10 视频 10 音频）。
* `seedance-2.5-c1` 只出 `720p`，不支持 `21:9`（`adaptive` 按 `16:9`），提示词最多 10000 字，素材最多 9 图 3 视频 3 音频；带参考视频或参考音频时至少要有 1 张参考图，否则返回 400。
#### ratio 与 adaptive
`ratio: adaptive` 时，文生视频按提示词选比例，首帧/首尾帧按首帧选最接近的比例。
| 行为 | 模型 |
| ------ | ---------------------------------- |
| 支持自适应 | `doubao-` 开头模型、`-hig`、`-duo`、两个标准款 |
| 返回 400 | `seedance-2-5-max` |
## 请求示例
首帧：
```json
{
"model": "doubao-seedance-2-0-260128",
"ratio": "16:9",
"content": [
{"type": "text", "text": "小猫缓缓睁开眼睛，站起来伸懒腰，镜头轻微向前推进"},
{"type": "image_url", "role": "first_frame", "image_url": {"url": "https://example.com/cat-first-frame.jpg"}}
],
"duration": 4
}
```
首尾帧：
```json
{
"model": "seedance-2-5-duo",
"content": [
{"type": "text", "text": "人物从房间走到花园，镜头平稳跟随，自然光"},
{"type": "image_url", "role": "first_frame", "image_url": {"url": "https://cdn.example.com/first.png"}},
{"type": "image_url", "role": "last_frame", "image_url": {"url": "https://cdn.example.com/last.png"}}
],
"resolution": "1080p",
"ratio": "adaptive",
"duration": 8,
"generate_audio": true
}
```
多素材参考（图 + 视频）：
```json
{
"model": "seedance-2-0-duo",
"content": [
{"type": "text", "text": "参考 @图片1 的角色和 @视频1 的运镜，生成一段产品广告片"},
{"type": "image_url", "role": "reference_image", "image_url": {"url": "https://cdn.example.com/role.png"}},
{"type": "video_url", "role": "reference_video", "video_url": {"url": "https://cdn.example.com/move.mp4"}}
],
"resolution": "720p",
"ratio": "16:9",
"duration": 10
}
```
参考图生视频（长片版）：
```json
{
"model": "seedance-2-5-hig",
"content": [
{"type": "text", "text": "镜头缓慢环绕产品一周，干净背景，真实光影，高级质感"},
{"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/product.png"}}
],
"resolution": "720p",
"ratio": "adaptive",
"duration": 20,
"generate_audio": true
}
```
参考视频（长片版，视频只作风格参考）：
```json
{
"model": "seedance-2-0-hig",
"content": [
{"type": "text", "text": "一只白猫蹲在木桌上吃东西，室内自然光"},
{"type": "video_url", "role": "reference_video", "video_url": {"url": "https://example.com/reference.mp4"}}
],
"resolution": "480p",
"ratio": "adaptive",
"duration": 10,
"generate_audio": true
}
```
2.5 视频编辑（`doubao-seedance-2-5-cloud`）：
```json
{
"model": "doubao-seedance-2-5-cloud",
"content": [
{"type": "text", "text": "将 @Video 1 的天空替换为晚霞，保留人物动作和原始对白"},
{"type": "video_url", "role": "reference_video", "video_url": {"url": "https://example.com/source.mov"}}
],
"omni_reference_task_type": "edit",
"ratio": "adaptive",
"duration": -1,
"output_format": "mov"
}
```
## 响应
### 提交响应
HTTP `202`：
| 字段 | 类型 | 说明 |
| ------------ | ------- | -------------------- |
| `task_id` | string | 平台任务 ID，`vt_` + UUID |
| `model` | string | 请求使用的模型 |
| `status` | string | 提交成功为 `pending` |
| `created_at` | integer | 创建时间，Unix 秒 |
| `duration` | integer | 请求的视频时长 |
| `resolution` | string | 计费分辨率档位 |
### 查询任务
`GET /v1/tasks/{task_id}`，路径参数 `task_id` 为提交返回的 `vt_...` ID。
| status | 说明 |
| ----------- | ---- |
| `pending` | 排队中 |
| `running` | 正在生成 |
| `succeeded` | 生成成功 |
| `failed` | 生成失败 |
`progress` 为 `0`-`100`，终态一律 `100`。只有长片版（`-max`、`-hig`）回报真实进度，其余模型生成期间恒为 `0`——判断是否结束请看 `status`。
成功响应字段：
| 字段 | 类型 | 说明 |
| ----------------------------- | ---------------- | ------------------------------------------------------------------- |
| `task_id` / `model` | string | 任务 ID / 模型 |
| `status` / `progress` | string / integer | `succeeded` / `100` |
| `created_at` / `completed_at` | integer | Unix 秒 |
| `video_url` | string | 视频下载 URL，有时效，成功后立即下载转存 |
| `expires_at` | integer | 下载 URL 过期时间，Unix 秒 |
| `duration` | number | 实际视频时长，秒 |
| `resolution` | string | 实际输出分辨率档位：`480p` / `720p` / `1080p` / `4k`，可选范围因模型而异，见[适用模型](#适用模型) |
| `ratio` | string | 实际视频比例，如 `16:9` |
| `usage` | object | 模型返回的用量明细 |
| `credits_charged` | number | 实际扣费 |
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "doubao-seedance-2-0-260128",
"status": "succeeded",
"progress": 100,
"created_at": 1783819200,
"completed_at": 1783819268,
"video_url": "https://example.com/generated/video.mp4",
"expires_at": 1784078468,
"duration": 4,
"resolution": "720p",
"ratio": "16:9",
"usage": {"duration": 4, "video_count": 1, "SR": 720, "ratio": "16:9", "output_video_duration": 4},
"credits_charged": 24
}
```
失败响应字段：`status`=`failed`；`error.code` 为 `timeout` 或 `upstream_error`；`error.message` 失败原因；`completed_at` 失败时间。
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "doubao-seedance-2-0-260128",
"status": "failed",
"progress": 100,
"error": {"code": "upstream_error", "message": "video generation failed"},
"completed_at": 1783819268
}
```
## 计费
按秒模型按“实际时长 × 分辨率档位单价”，按次模型（`seedance-2.5-c`、`seedance-2.5-c1`、`seedance-2.5-c2`、`seedance-2.5-c7`、`seedance-2.0-c`）按“条数 × 分辨率档位单价”，实时价格见[模型列表](/models)。
| 方式 | 模型 | 规则 |
| -------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| 按次 | `seedance-2.5-c`、`seedance-2.5-c1`、`seedance-2.5-c7`、`seedance-2.0-c` | 同分辨率每条一个价，与 `duration` 无关，带参考视频不加价（`seedance-2.5-c7` 带参考视频另有加价档）：长片越长越划算，短片反而比按秒贵 |
| 按次（分时长档） | `seedance-2.5-c2` | 与分辨率无关，`duration` ≤15 秒一个价、>15 秒一个价，带参考视频不加价 |
| 按秒 | 其余全部 | 30 秒的片是 5 秒的六倍价；`duration` 不传按默认值出片（标准款、`-max` 等见[适用模型](#适用模型)默认列，多为 5 秒），长片必须显式写 |
参考视频加价口径各通道不同，改投通道时要重算预算：
| 通道 | 带参考视频 |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `seedance-2-5`、`seedance-2-5-max`、`doubao-seedance-2-5-cloud` | 加价档，每秒比纯文生贵一档 |
| `-hig` | 每秒恒为同分辨率不带视频的 1.7 倍；档位只看分辨率与是否带视频，与视频条数、时长无关（`seedance-2-0-hig` 10 秒 `720p` 带一个或三个视频同价） |
| `-duo` | 独立的 `+video` 档，比同档基础价贵两成左右（`seedance-2-0-duo` 的 `720p` 为 1.62 对 2.592） |
* `-duo` `720p` 单价（积分每秒）：`-mini-duo` 0.817、`-fast-duo` 1.228、`seedance-2-0-duo` 1.62、`seedance-2-5-duo` 2.774。
* `seedance-2-0-duo` 的 `4k` 单价是 `720p` 的近 9 倍（14.45 对 1.62 积分每秒），上游对 4k 用另一套倍率，不要线性估预算。
* 失败：`upstream_error` 预扣全额退回；`timeout` 退款。
## 错误
通用错误见[接口说明](/video#错误)，本页补充：
| HTTP | code | 触发场景 | 处理 |
| ---- | ----------------------- | -------------------------------------------------- | ---------------------- |
| 400 | `invalid_request_error` | 参数越界或组合不合法，`message` 为具体原因（见下表）；越界参数同步拒绝，任务不建立、不计费 | 按 `message` 修正 |
| 402 | `insufficient_credits` | 余额不足 | 充值或降低时长、分辨率 |
| 404 | `model_not_found` | 模型不存在，或分辨率/时长组合没有对应售价档位 | 使用[适用模型](#适用模型)中的精确 ID |
| 404 | `task_not_found` | 任务不存在或无权访问 | 使用提交返回的 `task_id` |
| 502 | `upstream_error` | 模型任务提交失败 | 短暂等待后有限次数重试 |
| 503 | `no_available_channel` | 模型暂时不可用 | 指数退避后重试 |
常见 `message`（`` 为请求的模型）：
| `message` | 处理 |
| --------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `content is required and must be a non-empty array` / `content must contain at least one text item` | `content` 至少包含一个 `text` 项 |
| `image_url role must be one of first_frame/last_frame/reference_image` | 修正图片 `role` |
| `video_url role must be reference_video` / `audio_url role must be reference_audio` | 修正视频、音频 `role` |
| `content supports at most 30 images, 10 videos, and 10 audios` | 素材超过通用上限；各模型更严的上限见[适用模型](#适用模型) |
| `last_frame requires first_frame` / `at most one first_frame and one last_frame are allowed` | 尾帧必须配首帧，首尾帧各最多 1 张 |
| `first_frame and last_frame are not supported by ` | 该通道不支持首尾帧，改用参考图或选 `-duo` / `doubao-` 模型 |
| `resolution must be one of ...` | 分辨率取 `message` 列出的值 |
| `duration must be an integer between 4 and N` | 时长传 `4`–`N` 的整数（2.5 为 30，2.0 为 15） |
| `ratio must be one of ...` | 比例取 `message` 列出的值 |
| `omni_reference_task_type is not supported by ` | 仅 2.5 系列支持该字段 |
| ` is not supported for ` | 删除该字段 |
统一错误体格式见[错误码](/errors)。
## 注意事项
`duration` 不传按默认值（多为 5 秒）出片，要长片必须显式写。
* 公网 URL 必须允许模型服务直接下载，不能要求登录、Cookie 或临时请求头 → 用自己的对象存储直链。
* Base64 只适用于图片，格式 `data:image/png;base64,...` 或 `data:image/jpeg;base64,...`；视频、音频传公网 URL。
* 首尾帧的主体、构图、宽高比应尽量接近 → 否则易跳变、形变或过渡失败。
* 生成结果 URL 有时效 → 成功后立即下载到自己的存储。
* 长片版等慢通道长时间停在 `running`/低 `progress` 属正常 → 不要重复提交。
# SkyReels V4
Source: https://looptoken.vibelab.me/docs/video/skyreels
> skyreels-v4-fast、skyreels-v4-std：文生/首尾帧/参考图与参考视频生成，3–15 秒、480p–1080p，异步，用 GET /v1/tasks/{task_id} 查询
支持文生视频、首尾帧图生视频，以及带 `@tag` 引用的多素材参考生成（参考图 + 参考视频）。提交、轮询、任务对象与错误见[接口说明](/video)。
| 项 | 值 |
| ---- | ------------------------------------------------ |
| 模型 | `skyreels-v4-fast`（速度优先）、`skyreels-v4-std`（质量优先） |
| 模式 | 异步（提交 → 轮询 `GET /v1/tasks/{task_id}`） |
| 计费 | 按实际生成秒数 × 分辨率档位，带 `ref_videos` 按更高档位，见[计费](#计费) |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时 |
两个模型时长均为 `3-15` 秒，分辨率 `480p`、`720p`、`1080p`，默认 `5` 秒、`1080p`。
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "skyreels-v4-fast",
"prompt": "海边日落，海浪拍打礁石，镜头缓慢横移",
"resolution": "720p",
"duration": 5
}'
```
响应示例（HTTP `202`）：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "skyreels-v4-fast",
"status": "pending",
"created_at": 1772942400,
"duration": 5,
"resolution": "720p"
}
```
用 `task_id` 调用 `GET /v1/tasks/{task_id}` 查询，见[响应](#响应)。
## 模式选择
| 模式 | 怎么传参 |
| -------- | ---------------------------------------------------------------- |
| 文生视频 | 只传 `prompt` 与控制字段 |
| 首帧 / 首尾帧 | `image_urls` 传 1 张（首帧）或 2 张（首帧 + 尾帧） |
| 参考图 | `ref_images`，在 `prompt` 中用 `@tag` 引用 |
| 参考视频 | `ref_videos`，`type` 为 `extend`（续写）或 `reference`（参考运镜/动作），按更高档位计费 |
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | --------- | -- | ------- | ---------------------------------------------------------- |
| `model` | string | 是 | - | `skyreels-v4-fast` 或 `skyreels-v4-std` |
| `prompt` | string | 是 | - | 视频内容描述；使用 `ref_images`/`ref_videos` 时可用 `@tag` 在提示词中引用具体素材 |
| `resolution` | string | 否 | `1080p` | `480p`、`720p` 或 `1080p` |
| `duration` | integer | 否 | `5` | `3-15` 秒 |
| `image_urls` | string\[] | 否 | - | 图生视频图片；1 张作为首帧，2 张作为首帧 + 尾帧 |
| `ref_images` | object\[] | 否 | - | 参考图素材数组，用于保持角色/风格一致性 |
| `ref_videos` | object\[] | 否 | - | 参考视频素材数组；出现该字段按更高档位计费（见[计费](#计费)） |
| `callback_url` | string | 否 | - | 任务到达终态后的 HTTPS 回调地址 |
### 参考图 `ref_images`
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------------ | ------ | -- | -- | ----------------------------------------- |
| `ref_images[].tag` | string | 是 | - | 素材标签，如 `@C1`，在 `prompt` 中用同名 `@tag` 引用该素材 |
| `ref_images[].image_url` | string | 是 | - | 公网可访问的图片 URL |
### 参考视频 `ref_videos`
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------------ | ------ | -- | -- | ------------------------------------------------------------------------------ |
| `ref_videos[].tag` | string | 是 | - | 素材标签，如 `@V1` |
| `ref_videos[].type` | string | 是 | - | `extend`（视频续写，按请求 `duration` 计算时长）或 `reference`（参考运镜/动作，实际时长由参考视频覆盖，最长 `10` 秒） |
| `ref_videos[].video_url` | string | 是 | - | 公网可访问的 MP4 视频 URL |
## 请求示例
带参考视频：
```json
{
"model": "skyreels-v4-std",
"prompt": "沿用 @V1 的运镜方式，主体换成一只金毛犬",
"resolution": "720p",
"ref_videos": [
{"tag": "@V1", "type": "reference", "video_url": "https://example.com/ref.mp4"}
]
}
```
## 响应
用 `GET /v1/tasks/{task_id}` 查询，状态依次为 `pending` → `running` → `succeeded` / `failed`（终态）。
| 字段 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------------------- |
| `status` | string | `pending`、`running`、`succeeded`、`failed` |
| `video_url` | string | 视频下载地址，仅 `succeeded` 返回，尽快转存 |
| `expires_at` | integer | `video_url` 失效时间，Unix 秒 |
| `credits_charged` | number | 本次实际扣费（积分） |
| `error` | object | 仅 `failed` 返回：`{"code": "timeout" \| "upstream_error", "message": "..."}` |
完整任务对象字段与示例见[接口说明](/video#任务对象字段)。
## 计费
按实际生成时长（秒）× 分辨率档位计费；请求中包含非空 `ref_videos` 时按更高的参考视频档位计费。提交时先按请求参数预扣，任务结束后按实际结果结算，多退少补。
| 档位 | `skyreels-v4-fast` | `skyreels-v4-std` |
| -------------- | ------------------ | ----------------- |
| `480p` | 约 `0.768` 积分/秒 | 约 `1.056` 积分/秒 |
| `720p` | 约 `1.056` 积分/秒 | 约 `1.344` 积分/秒 |
| `1080p`（默认） | 约 `2.64` 积分/秒 | 约 `3.36` 积分/秒 |
| `480p` + 参考视频 | 约 `1.44` 积分/秒 | 约 `1.728` 积分/秒 |
| `720p` + 参考视频 | 约 `1.92` 积分/秒 | 约 `2.4` 积分/秒 |
| `1080p` + 参考视频 | 约 `4.8` 积分/秒 | 约 `6` 积分/秒 |
精确价格与实时变动以[定价页](/pricing)为准。
## 错误
通用错误见[接口说明](/video#错误)。本模型提交时的参数校验返回 `400 invalid_request_error`：
| `message` | 处理 |
| ------------------------------------------- | ---------------------------- |
| `resolution must be one of 480p/720p/1080p` | 分辨率传 `480p`、`720p` 或 `1080p` |
| `duration must be between 3 and 15` | 时长传 `3`–`15` |
# Sora 2
Source: https://looptoken.vibelab.me/docs/video/sora2
> sora-2 与 sora-2-pro：文生/图生视频，4–20 秒，异步，用 GET /v1/tasks/{task_id} 查询
Sora 2 系列当前暂未开放调用。本页字段说明仅供接入预览，实际可用状态以[模型列表](/models)为准。
Sora 2 通过 `/v1` 统一异步视频接口调用，请求体为统一扁平字段。提交、轮询、任务对象与错误见[接口说明](/video)。
| 项 | 值 |
| ---- | --------------------------------------------------------- |
| 模型 | `sora-2`（`720p`）、`sora-2-pro`（`720p` / `1024p` / `1080p`） |
| 模式 | 异步（提交 → 轮询 `GET /v1/tasks/{task_id}`） |
| 计费 | 按模型、时长、分辨率档位，先预扣后结算，价格以[定价页](/pricing)为准 |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "sora-2",
"prompt": "A waterfall cascading down forming a rainbow",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
```
响应示例（HTTP `202`）：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "sora-2",
"status": "pending",
"created_at": 1772942400,
"duration": 8,
"resolution": "720p"
}
```
用 `task_id` 调用 `GET /v1/tasks/{task_id}` 查询结果，见[响应](#响应)。
## 模式选择
| 模式 | 怎么传参 |
| ---- | -------------------------- |
| 文生视频 | 只传 `prompt` 与控制字段 |
| 图生视频 | `image_urls` 传 1 张公网图片 URL |
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | --------- | -- | ------ | ------------------------------------------------------------ |
| `model` | string | 是 | - | `sora-2` 或 `sora-2-pro` |
| `prompt` | string | 是 | - | 视频内容描述 |
| `duration` | integer | 否 | `4` | `4`、`8`、`12`、`16`、`20` 秒 |
| `resolution` | string | 否 | `720p` | `sora-2` 仅支持 `720p`；`sora-2-pro` 支持 `720p`、`1024p`、`1080p` |
| `aspect_ratio` | string | 否 | 横屏 | `16:9`、`landscape`、`9:16`、`portrait`；不传默认横屏 |
| `image_urls` | string\[] | 否 | - | 图生视频传 1 张公网图片 URL；支持 `.jpeg`、`.jpg`、`.png`、`.webp`，单图最大 10MB |
| `callback_url` | string | 否 | - | 任务到达终态后的 HTTPS 回调地址 |
## 请求示例
图生视频：
```json
{
"model": "sora-2-pro",
"prompt": "镜头缓慢推进，画面中的人物转身微笑",
"duration": 8,
"resolution": "1080p",
"image_urls": ["https://example.com/reference.jpg"]
}
```
## 响应
用 `GET /v1/tasks/{task_id}` 查询，状态依次为 `pending` → `running` → `succeeded` / `failed`（终态）。成功后 `video_url` 为视频下载地址：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "sora-2",
"status": "succeeded",
"progress": 100,
"created_at": 1772942400,
"completed_at": 1772942468,
"duration": 8,
"resolution": "720p",
"credits_charged": 6.4,
"video_url": "https://media.example.com/video.mp4",
"expires_at": 1773028868
}
```
| 字段 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------------------- |
| `video_url` | string | 视频下载地址，仅 `succeeded` 返回，尽快转存 |
| `expires_at` | integer | `video_url` 失效时间，Unix 秒 |
| `credits_charged` | number | 本次实际扣费（积分） |
| `error` | object | 仅 `failed` 返回：`{"code": "timeout" \| "upstream_error", "message": "..."}` |
完整任务对象字段见[接口说明](/video#任务对象字段)。
## 计费
* 提交时按顶层 `duration`、`resolution` 预扣，未传时按 `4` 秒、`720p`。
* 终态按实际结果结算，多退少补；失败全额退回预扣。
## 错误
通用错误见[接口说明](/video#错误)。
| HTTP | code | 触发场景 | 处理 |
| ---- | ----------------- | ----------------------------------------------------------- | ---------------- |
| 404 | `model_not_found` | `duration` / `resolution` 组合没有对应售价档位（例如 `sora-2` 只有 `720p`） | 按[请求参数](#请求参数)调整 |
本模型的字段范围由上游校验，不合规的请求可能在 `202` 之后表现为异步 `failed`。
## 注意事项
* **传入 `image_urls`** → 画面方向根据参考图自动判断，`aspect_ratio` 可省略。
# Veo 3.1
Source: https://looptoken.vibelab.me/docs/video/veo31
> veo3.1-fast、veo3.1-quality、veo3.1-lite：文生/图生视频，固定 8 秒，异步，用 GET /v1/tasks/{task_id} 查询
Veo 3.1 系列当前暂未开放调用。本页字段说明仅供接入预览，实际可用状态以[模型列表](/models)为准。
Veo 3.1 通过 `/v1` 统一异步视频接口调用。提交、轮询、任务对象与错误见[接口说明](/video)。
| 项 | 值 |
| ---- | --------------------------------------------------------------------- |
| 模型 | `veo3.1-fast`（快速预览与迭代）、`veo3.1-quality`（高质量成片）、`veo3.1-lite`（低成本批量生成） |
| 模式 | 异步（提交 → 轮询 `GET /v1/tasks/{task_id}`） |
| 计费 | 按模型与分辨率档位，时长固定 `8` 秒，先预扣后结算，价格以[定价页](/pricing)为准 |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时 |
三个模型的时长均固定 `8` 秒，分辨率均为 `720p`、`1080p`、`4k`，默认 `8` 秒、`720p`。
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1-fast",
"prompt": "海豚在碧蓝海洋中跳跃",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
```
响应示例（HTTP `202`）：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "veo3.1-fast",
"status": "pending",
"created_at": 1772942400,
"duration": 8,
"resolution": "720p"
}
```
用 `task_id` 调用 `GET /v1/tasks/{task_id}` 查询结果，见[响应](#响应)。
## 模式选择
| 模式 | 怎么传参 |
| ---------- | --------------------------------------------------------- |
| 文生视频 | 只传 `prompt` 与控制字段 |
| 图生视频（自动判断） | `image_urls` 传 1–3 张图，不传 `generation_type` 时按图片数量自动判断 |
| 首尾帧 | `generation_type: "frame"`，`image_urls` 第 1 张为首帧、第 2 张为尾帧 |
| 参考图 | `generation_type: "reference"`；`veo3.1-quality` 不支持 |
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------------- | --------- | -- | --------- | ----------------------------------------------------------------------------------------- |
| `model` | string | 是 | - | `veo3.1-fast`、`veo3.1-quality` 或 `veo3.1-lite` |
| `prompt` | string | 是 | - | 视频内容描述 |
| `duration` | integer | 否 | `8` | 仅支持 `8` 秒 |
| `resolution` | string | 否 | `720p` | `720p`、`1080p`、`4k` |
| `aspect_ratio` | string | 否 | - | `16:9` 或 `9:16` |
| `generation_type` | string | 否 | 按图片数量自动判断 | `frame` 表示首尾帧生成；`reference` 表示参考图生成；`veo3.1-quality` 不支持 `reference`，`veo3.1-lite` 不支持该字段 |
| `image_urls` | string\[] | 否 | - | 图生视频参考图，最多 3 张；支持公网图片 URL，单图最大 10MB；`veo3.1-lite` 不支持该字段 |
| `enable_gif` | boolean | 否 | `false` | 是否输出 GIF；不能与 `1080p` 或 `4k` 同时使用 |
| `callback_url` | string | 否 | - | 任务到达终态后的 HTTPS 回调地址 |
## 请求示例
首尾帧：
```json
{
"model": "veo3.1-fast",
"prompt": "镜头从清晨缓慢过渡到日落",
"generation_type": "frame",
"image_urls": ["https://example.com/first.png", "https://example.com/last.png"],
"resolution": "1080p",
"aspect_ratio": "16:9"
}
```
## 响应
用 `GET /v1/tasks/{task_id}` 查询，状态依次为 `pending` → `running` → `succeeded` / `failed`（终态）。成功后 `video_url` 为视频下载地址：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "veo3.1-fast",
"status": "succeeded",
"progress": 100,
"created_at": 1772942400,
"completed_at": 1772942468,
"duration": 8,
"resolution": "720p",
"video_url": "https://media.example.com/video.mp4",
"expires_at": 1773028868
}
```
| 字段 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------------------- |
| `video_url` | string | 视频下载地址，仅 `succeeded` 返回，尽快转存 |
| `expires_at` | integer | `video_url` 失效时间，Unix 秒 |
| `credits_charged` | number | 本次实际扣费（积分） |
| `error` | object | 仅 `failed` 返回：`{"code": "timeout" \| "upstream_error", "message": "..."}` |
完整任务对象字段见[接口说明](/video#任务对象字段)。
## 计费
* 无论请求传什么 `duration`，预扣均按固定 `8` 秒；档位按 `resolution`（未传按 `720p`）。
* 终态按实际结果结算，多退少补；失败全额退回预扣。
## 错误
通用错误见[接口说明](/video#错误)。
| HTTP | code | 触发场景 | 处理 |
| ---- | ----------------- | --------------------- | ---------------------- |
| 404 | `model_not_found` | `resolution` 没有对应售价档位 | 使用 `720p`、`1080p`、`4k` |
本模型的 `generation_type`、`image_urls`、`enable_gif` 等字段由上游校验，不合规的请求可能在 `202` 之后表现为异步 `failed`。
## 注意事项
* **`veo3.1-lite`** → 不支持 `generation_type` 与 `image_urls`。
* **`veo3.1-quality`** → 不支持 `generation_type: reference`。
* **`enable_gif: true`** → 不能与 `1080p`、`4k` 同时使用。
# Vidu Q3 系列
Source: https://looptoken.vibelab.me/docs/video/vidu
> viduq3、viduq3-mix、viduq3-pro、viduq3-turbo：多参考图/文生/图生/首尾帧视频，1–16 秒、540p–1080p，异步，用 GET /v1/tasks/{task_id} 查询
Vidu Q3 系列包含 4 个子型号，图生视频输入的必填性与用法因型号而异。提交、轮询、任务对象与错误见[接口说明](/video)。
| 项 | 值 |
| ---- | ------------------------------------------------------- |
| 模型 | `viduq3`、`viduq3-mix`、`viduq3-pro`、`viduq3-turbo`，差异见下表 |
| 模式 | 异步（提交 → 轮询 `GET /v1/tasks/{task_id}`） |
| 计费 | 按实际生成秒数 × 分辨率档位，见[计费](#计费) |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时 |
四个型号的能力对比：
| 模型 | 定位 | 时长 | 分辨率 | `image_urls` | 默认值 |
| -------------- | ------------- | -------- | -------------------------- | ------------ | ------------ |
| `viduq3` | 多参考图、标准档 | `3-16` 秒 | `540p`、`720p`、`1080p` | 必填，`1-7` 张 | `5` 秒、`720p` |
| `viduq3-mix` | 多参考图、高画质 | `1-16` 秒 | `720p`、`1080p`（不支持 `540p`） | 必填，`1-7` 张 | `5` 秒、`720p` |
| `viduq3-pro` | 文生/图生/首尾帧，质量档 | `1-16` 秒 | `540p`、`720p`、`1080p` | 可选 | `5` 秒、`720p` |
| `viduq3-turbo` | 文生/图生/首尾帧，速度档 | `1-16` 秒 | `540p`、`720p`、`1080p` | 可选 | `5` 秒、`720p` |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "viduq3-turbo",
"prompt": "无人机航拍山谷云海，镜头缓慢上升",
"resolution": "540p",
"duration": 5
}'
```
响应示例（HTTP `202`）：
```json
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "viduq3-turbo",
"status": "pending",
"created_at": 1772942400,
"duration": 5,
"resolution": "540p"
}
```
用 `task_id` 调用 `GET /v1/tasks/{task_id}` 查询，见[响应](#响应)。
## 模式选择
`viduq3` 与 `viduq3-mix` 必须传 `image_urls`（缺失 → `400 invalid_request_error`），`1-7` 张图片按多参考图方式融合生成，不区分首尾帧。
`viduq3-pro` 与 `viduq3-turbo` 的 `image_urls` 可选，按图片数量路由：
| 图片数量 | 行为 |
| ---: | -------- |
| 0 | 文生视频 |
| 1 | 图生视频（首帧） |
| 2 | 首尾帧生成 |
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | --------- | --- | ------- | ------------------------------------------------------- |
| `model` | string | 是 | - | `viduq3`、`viduq3-mix`、`viduq3-pro` 或 `viduq3-turbo` |
| `prompt` | string | 是 | - | 视频内容描述 |
| `resolution` | string | 否 | `720p` | 范围见上表 |
| `duration` | integer | 否 | `5` | 范围见上表 |
| `image_urls` | string\[] | 视模型 | - | `viduq3`/`viduq3-mix` 必填；`viduq3-pro`/`viduq3-turbo` 可选 |
| `audio` | boolean | 否 | `false` | 是否生成人声/音效 |
| `callback_url` | string | 否 | - | 任务到达终态后的 HTTPS 回调地址 |
## 请求示例
`viduq3` 多参考图（必须提供 `image_urls`）：
```json
{
"model": "viduq3",
"prompt": "两个参考主体在同一场景中互动",
"image_urls": ["https://example.com/ref-1.jpg", "https://example.com/ref-2.jpg"],
"resolution": "720p",
"duration": 4
}
```
`viduq3-pro` 首尾帧：
```json
{
"model": "viduq3-pro",
"prompt": "镜头从清晨缓慢过渡到日落",
"image_urls": ["https://example.com/first.png", "https://example.com/last.png"],
"resolution": "1080p",
"duration": 5
}
```
## 响应
用 `GET /v1/tasks/{task_id}` 查询，状态依次为 `pending` → `running` → `succeeded` / `failed`（终态）。
| 字段 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------------------- |
| `status` | string | `pending`、`running`、`succeeded`、`failed` |
| `video_url` | string | 视频下载地址，仅 `succeeded` 返回，尽快转存 |
| `expires_at` | integer | `video_url` 失效时间，Unix 秒 |
| `credits_charged` | number | 本次实际扣费（积分） |
| `error` | object | 仅 `failed` 返回：`{"code": "timeout" \| "upstream_error", "message": "..."}` |
完整任务对象字段与示例见[接口说明](/video#任务对象字段)。
## 计费
按实际生成时长（秒）× 分辨率档位计费。提交时先按请求参数预扣，任务结束后按实际结果结算，多退少补。
| 分辨率 | `viduq3-turbo` | `viduq3` | `viduq3-mix` | `viduq3-pro` |
| ---------- | -------------- | ------------- | ------------- | -------------- |
| `540p` | 约 `0.384` 积分/秒 | 约 `0.48` 积分/秒 | 不支持 | 约 `0.672` 积分/秒 |
| `720p`（默认） | 约 `0.576` 积分/秒 | 约 `0.96` 积分/秒 | 约 `1.2` 积分/秒 | 约 `1.44` 积分/秒 |
| `1080p` | 约 `0.672` 积分/秒 | 约 `1.2` 积分/秒 | 约 `1.44` 积分/秒 | 约 `1.536` 积分/秒 |
精确价格与实时变动以[定价页](/pricing)为准。
## 错误
通用错误见[接口说明](/video#错误)。本模型提交时的参数校验返回 `400 invalid_request_error`：
| `message` | 处理 |
| ------------------------------------------- | -------------------------------------------- |
| `image_urls is required for this model` | `viduq3`、`viduq3-mix` 必须传非空 `image_urls` |
| `resolution must be one of 540p/720p/1080p` | `viduq3`、`viduq3-pro`、`viduq3-turbo` 分辨率取上述值 |
| `resolution must be one of 720p/1080p` | `viduq3-mix` 不支持 `540p` |
| `duration must be between 3 and 16` | `viduq3` 时长传 `3`–`16` |
| `duration must be between 1 and 16` | 其余三个型号时长传 `1`–`16` |
## 注意事项
* **`viduq3` / `viduq3-mix` 缺 `image_urls`** → 返回 `400 invalid_request_error`。
* **`viduq3-mix` 传 `540p`** → 不支持，用 `720p` 或 `1080p`。
# Wan 视频
Source: https://looptoken.vibelab.me/docs/video/wan
> wan3.0-video / wan3.0-video-prime：DashScope 风格 input + parameters 的异步视频生成，支持文生、首尾帧、参考生成与视频编辑，480P/720P/1080P，用 GET /v1/tasks/{task_id} 查询
Wan 使用统一异步任务 API，请求体为 DashScope 风格（`input` + `parameters`）。提交、轮询、任务对象字段、回调与通用错误见[接口说明](/video)，本页只写 Wan 的差异。
| 项 | 值 |
| ---- | --------------------------------------------------------------------------------------- |
| 模型 | `wan3.0-video`（标准版）、`wan3.0-video-prime`（高速版）；二者参数、素材规则、计费时长口径相同，只在 `model` 取值与速度、单价上不同 |
| 模式 | 异步（提交 → 轮询 `GET /v1/tasks/{task_id}`）；支持文生、首尾帧、参考生成与视频编辑 |
| 计费 | 按计费时长 × 480p/720p/1080p 档位；带参考视频（视频编辑）时计费时长含输入视频，见[计费](#计费) |
| 媒体保留 | `video_url` 最长保留至任务完成后 72 小时 |
## 快速开始
```bash
TASK_ID=$(curl -sS https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan3.0-video",
"input": {"prompt": "一只金毛寻回犬在金色的秋天落叶中奔跑"},
"parameters": {"resolution": "720P", "duration": 5}
}' | jq -r '.task_id')
curl -sS "https://api.vibelab.me/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
提交固定返回 HTTP `202`，包含 `task_id`、`model`、`status`（提交时为 `pending`）、`created_at`、`duration`、`resolution`。
## 请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------------------- | ------- | ---------------------- | ---------- | --------------------------------------------------------------------------------- |
| `model` | string | 是 | - | `wan3.0-video`（标准版）或 `wan3.0-video-prime`（高速版） |
| `input.prompt` | string | 与 `input.media` 至少传一个 | - | 文本描述，最多 20000 字符；纯文生视频只传它 |
| `input.media` | array | 与 `input.prompt` 至少传一个 | - | 参考素材，每项 `{"type": "...", "url": "..."}`，见[参考素材](#参考素材) |
| `parameters.resolution` | string | 否 | `1080P` | `480P`、`720P`、`1080P`；未传时平台按 `720P` 预扣，终态按实际结果结算 |
| `parameters.duration` | integer | 否 | `5` | 输出时长，整数秒 |
| `parameters.ratio` | string | 否 | `adaptive` | `adaptive` 按输入自动选择（实测 320x240 输入输出 4:3）；可选 `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
| `parameters.audio` | boolean | 否 | `true` | 是否生成音频，开关价格相同 |
| `parameters.seed` | integer | 否 | - | `-1` 或 0–2147483647；相同 seed 不保证结果完全一致 |
| `parameters.prompt_extend` | boolean | 否 | `true` | 开启后上游会智能改写提示词，耗时增加；编辑场景若要严格按原文执行可设 `false` |
| `parameters.watermark` | boolean | 否 | `false` | 是否添加水印 |
| `callback_url` | string | 否 | - | 公网 HTTPS URL；不能替代任务轮询 |
本页列出的字段为已验证字段，未列出的字段原样透传，不作稳定兼容承诺。有视频输入时，输入视频总时长 + 输出时长不得超过 30 秒。
## 参考素材
`input.media[]` 每项为 `{"type": "...", "url": "..."}`，`url` 须为公网可访问的 HTTP/HTTPS 地址。
| `type` | 数量 | 限制 |
| ----------------- | ------ | --------------------------------------------------------------------------- |
| `first_frame` | 1 张 | 严格作首帧 |
| `last_frame` | 1 张 | 严格作尾帧 |
| `reference_image` | ≤ 10 张 | jpeg/jpg/png（不支持透明通道）/bmp/webp；单边 240–8000px；长宽比 ≤ 8:1；单张 ≤ 20MB |
| `reference_video` | ≤ 5 段 | 总时长 ≤ 15 秒；mp4/mov；单段 1–15 秒；帧率 ≥ 16fps；单边 240–4096px；长宽比 ≤ 8:1；单文件 ≤ 100MB |
| `reference_audio` | ≤ 5 段 | 总时长 ≤ 15 秒；wav/mp3；单段 1–15 秒；单文件 ≤ 15MB |
| `file` / `link` | 各 1 个 | 文档或网页；二者不可同用；使用时 `prompt_extend` 必须为 `true` |
组合规则：
* 首帧/尾帧不能与 `reference_*`、`file`、`link` 混用。
* `reference_image`、`reference_video`、`reference_audio` 可自由组合。
* 视频编辑和视频延长必须包含 `reference_video`，可再配 `reference_image`、`reference_audio`。
* 提示词中可用「图1」「视频1」「音频1」指代素材，序号按该类型在 `media` 中出现的顺序计（图片、视频、音频分别计数）。
## 视频编辑
在 `media` 中放入 `reference_video`，并在 `prompt` 中写编辑指令即可。
风格转换：
```bash
curl -sS https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan3.0-video",
"input": {
"prompt": "将视频画面整体转换为黑白风格，其余保持不变。",
"media": [
{"type": "reference_video", "url": "https://example.com/source.mp4"}
]
},
"parameters": {"resolution": "720P", "duration": 5}
}'
```
替换背景或人物：`media` 同时放入 `reference_image` 与 `reference_video`，提示词用「图1」「视频1」指代。
```bash
curl -sS https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan3.0-video",
"input": {
"prompt": "视频1 的背景替换为 图1，人物保持不变",
"media": [
{"type": "reference_image", "url": "https://example.com/background.png"},
{"type": "reference_video", "url": "https://example.com/source.mp4"}
]
},
"parameters": {"resolution": "720P", "duration": 5}
}'
```
输出时长由 `parameters.duration` 决定，不会自动等于输入视频时长。想保持原时长，请把 `duration` 设为不小于输入视频的整数秒。
## 响应
用 `GET /v1/tasks/{task_id}` 查询，状态依次为 `pending` → `running` → `succeeded` / `failed`（终态）。任务对象通用字段见[接口说明](/video#任务对象字段)。
| 字段 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------ |
| `video_url` | string | 临时下载地址，仅 `succeeded` 返回，以 `expires_at` 为准及时转存 |
| `expires_at` | integer | `video_url` 失效时间，Unix 秒 |
| `usage` | object | 仅可能包含 `duration`、`SR`、`ratio`；`duration` 为计费时长，有视频输入时含输入视频时长 |
| `credits_charged` | number | 完成结算后实际扣除的积分 |
| `error` | object | 仅 `failed` 返回：`error.code` 为 `upstream_error` 或 `timeout` |
## 计费
* 按计费时长和 480p/720p/1080p 档位计费；视频编辑与图生视频费率相同（按分辨率档位的每秒单价），不因编辑加价。
* 带 `reference_video` 时，计费时长 = 输入视频时长 + 输出时长（取上游 `usage.duration`，结算时折算为整秒），因此编辑通常比同时长的图/文生视频更贵。
* 示例：480P、输入 1 秒视频、`duration=2`，任务对象 `duration: 3.0`，扣 1.9287 积分（3 秒 × 0.6429）。
* 提交时按请求的 `duration` 预扣，完成后按实际 `usage.duration` 与 `usage.SR` 多退少补；失败退款。
* 单价以[模型列表](/models)展示的当前价格为准。
## 错误
通用错误见[接口说明](/video#错误)。`parameters.resolution` 不在 `480P` / `720P` / `1080P` 内时，预扣档位按 `720P` 处理，平台不会在提交阶段拒绝；`input` / `parameters` 的其余取值由上游校验，参数问题可能在 `202` 之后表现为异步 `failed`，`error.code` 为 `upstream_error`。
## 注意事项
* **`202` 响应** → 只表示任务已创建，参数问题可能在任务创建后异步 `failed`。
* **参考素材 URL** → 必须公网可访问，且在任务运行期间保持可用。
* **素材不合规** → 格式、时长、大小不符合要求时，会在 `202` 之后异步 `failed`，`error.code` 为 `upstream_error`。
* **轮询频率** → 建议每 5-10 秒一次，逐步退避，最长不超过 30 秒一次。
# 创建数字人任务
Source: https://looptoken.vibelab.me/docs/video/kling/avatar-create
> POST /v1/videos/avatar/image2video：用一张人像和一段音频生成口播视频，异步
用数字人参考图和音频生成说话视频。
| 项 | 值 |
| -- | ---------------------------------------------------------------------------------------- |
| 模式 | 异步（提交 → 轮询 `GET /v1/videos/avatar/image2video/{id}`，见[查询数字人任务](/video/kling/avatar-get)） |
| 计费 | 按输出视频实际时长（秒）结算，提交时按音频上限 300 秒预冻结 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/avatar/image2video \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/portrait.png",
"sound_file": "https://example.com/speech.mp3",
"prompt": "一边说话，一边兴奋地摇头晃脑",
"mode": "std"
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"task_id": "893605946402811985",
"task_status": "submitted",
"task_info": {
"external_task_id": "your-id"
},
"created_at": 1722769557708,
"updated_at": 1722769557708
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------------ | ------- | -- | ------- | ---------------------------------------------------------------------------- |
| `image` | string | 是 | - | 数字人参考图，URL 或不带前缀的 Base64；jpg/jpeg/png，不超过 10MB，宽高不小于 300px，宽高比 1:2.5 到 2.5:1 |
| `sound_file` | string | 是 | - | 音频 URL 或 Base64；mp3/wav/m4a/aac，不超过 5MB，时长 2–300 秒 |
| `prompt` | string | 否 | - | 动作、情绪、运镜描述，不超过 2500 个字符 |
| `mode` | string | 否 | `std` | `std` 或 `pro` |
| `watermark_info.enabled` | boolean | 否 | `false` | 是否同时生成含水印结果 |
| `callback_url` | string | 否 | - | 任务状态变化时的 HTTPS 回调地址，见[概览](/video/kling#回调) |
| `external_task_id` | string | 否 | - | 自定义任务 ID，同一账号下不可重复 |
## 响应
| 字段 | 类型 | 说明 |
| ----------------------------------- | ------- | ------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.task_id` | string | 任务 ID |
| `data.task_status` | string | `submitted`、`processing`、`succeed`、`failed` |
| `data.task_info.external_task_id` | string | 创建时传入的自定义任务 ID |
| `data.created_at`、`data.updated_at` | integer | Unix 毫秒时间戳 |
## 计费
按输出视频实际时长（秒）结算。提交时按音频时长上限 300 秒预冻结额度，任务结束后多退少补；失败全额退回。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ---------------------------------------------------------------------------------------- | --------------- |
| 400 | `1201` | `image is required and must be a string` / `sound_file is required and must be a string` | 补齐必填字段 |
| 400 | `1201` | `audio_id is not supported, use sound_file` | 改传 `sound_file` |
| 400 | `1201` | `prompt must not exceed 2500 characters` | 缩短提示词 |
| 400 | `1201` | `mode must be std or pro` | 传 `std` 或 `pro` |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **与官方的差别** → 不支持 `audio_id`（它指向可灵账号里的历史作品，不属于你的账号），请改用 `sound_file`；响应不返回 `final_unit_deduction`、`final_balance_deduction`；`callback_url` 由 LoopToken 投递，`external_task_id` 在你的账号范围内去重。
# 查询数字人任务
Source: https://looptoken.vibelab.me/docs/video/kling/avatar-get
> GET /v1/videos/avatar/image2video/{id}：按 task_id 或 external_task_id 查询数字人任务
| 项 | 值 |
| -- | ----- |
| 模式 | 同步查询 |
| 计费 | 查询不收费 |
## 快速开始
```bash
curl "https://api.vibelab.me/v1/videos/avatar/image2video/893605946402811985" \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"task_id": "893605946402811985",
"task_status": "succeed",
"task_status_msg": "",
"task_info": {
"external_task_id": "your-id"
},
"task_result": {
"videos": [
{
"id": "893605946402811986",
"url": "https://example.com/result.mp4",
"watermark_url": "https://example.com/result-wm.mp4",
"duration": "5.0"
}
]
},
"created_at": 1722769557708,
"updated_at": 1722769600000
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
### 路径参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---- | ------ | -- | -- | ------------------------------------------- |
| `id` | string | 是 | - | 数字人任务的 `task_id`，或创建时传入的 `external_task_id` |
## 响应
| 字段 | 类型 | 说明 |
| ----------------------------------------- | ------- | ------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.task_id` | string | 任务 ID |
| `data.task_status` | string | `submitted`、`processing`、`succeed`、`failed` |
| `data.task_status_msg` | string | 失败原因 |
| `data.task_info.external_task_id` | string | 自定义任务 ID |
| `data.task_result.videos[].id` | string | 视频 ID |
| `data.task_result.videos[].url` | string | 视频地址，30 天后清理，请及时转存 |
| `data.task_result.videos[].watermark_url` | string | 含水印视频地址，仅请求了水印时有值 |
| `data.task_result.videos[].duration` | string | 视频时长，单位秒 |
| `data.created_at`、`data.updated_at` | integer | Unix 毫秒时间戳 |
## 计费
查询不收费。
## 错误
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | --------------------------------------- | ------- |
| 404 | `1203` | `task not found`：任务不存在、不属于当前账号或已超过 30 天 | 核对 `id` |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **查询范围** → 只能查询自己最近 30 天的任务。
# 数字人任务列表
Source: https://looptoken.vibelab.me/docs/video/kling/avatar-list
> GET /v1/videos/avatar/image2video：分页列出数字人任务
| 项 | 值 |
| -- | ----- |
| 模式 | 同步查询 |
| 计费 | 查询不收费 |
## 快速开始
```bash
curl "https://api.vibelab.me/v1/videos/avatar/image2video?pageNum=1&pageSize=30" \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": [
{
"task_id": "893605946402811985",
"task_status": "succeed",
"task_status_msg": "",
"task_info": {
"external_task_id": "your-id"
},
"task_result": {
"videos": [
{
"id": "893605946402811986",
"url": "https://example.com/result.mp4",
"watermark_url": "https://example.com/result-wm.mp4",
"duration": "5.0"
}
]
},
"created_at": 1722769557708,
"updated_at": 1722769600000
}
]
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
### 查询参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ------- | -- | ---- | ---------- |
| `pageNum` | integer | 否 | `1` | 页码，1–1000 |
| `pageSize` | integer | 否 | `30` | 每页数量，1–500 |
## 响应
| 字段 | 类型 | 说明 |
| ------------ | ------- | ------------------------------------------ |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data[]` | array | 任务列表，字段同[查询数字人任务](/video/kling/avatar-get) |
## 计费
查询不收费。
## 错误
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ------------------------------------ | ----------- |
| 400 | `1201` | `pageNum must be between 1 and 1000` | 页码传 1–1000 |
| 400 | `1201` | `pageSize must be between 1 and 500` | 每页数量传 1–500 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **排序与范围** → 按创建时间倒序，只返回自己最近 30 天的任务。
# 主体管理
Source: https://looptoken.vibelab.me/docs/video/kling/elements
> /v1/general/*：创建、查询和删除 Kling 主体，以及查询官方主体库；创建异步，用 GET /v1/general/advanced-custom-elements/{id} 查询
创建可在 [Kling 4.0](/video/kling/kling-4) 全能参考中引用的主体（`element_id`），并查询、删除自己的主体，查询官方主体库。接口风格与可灵官方一致，属于[旧版风格](/video/kling#接口清单)（响应字段 `task_id` / `task_status`）。
| 项 | 值 |
| -- | --------------------------------------------------------------------------- |
| 模型 | `kling-custom-elements` |
| 模式 | 创建为异步（提交 → 轮询 `GET /v1/general/advanced-custom-elements/{id}`）；列表、官方库、删除为同步 |
| 计费 | 创建按次计费，价格以[定价页](/pricing)为准；查询、列表和删除不向用户计费 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/general/advanced-custom-elements \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"element_name":"小猫","element_description":"白色长毛猫","reference_type":"image_refer","element_image_list":{"frontal_image":"https://example.com/front.jpg","refer_images":[{"image_url":"https://example.com/side.jpg"}]},"external_task_id":"my-cat"}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"task_id": "893605946402811985",
"task_status": "submitted",
"task_info": {
"external_task_id": "my-cat"
},
"created_at": 1722769557708,
"updated_at": 1722769557708
}
}
```
`data.task_id` 是创建任务 ID，**不是主体 ID**。轮询见[响应](#响应)。
## 请求参数
### 创建主体请求体
认证为 `Authorization: Bearer $LOOPTOKEN_API_KEY`，`Content-Type: application/json`。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------------- | ------ | ---------------- | -- | ------------------------------------------------------ |
| `element_name` | string | 是 | - | 不超过 20 个字符 |
| `element_description` | string | 是 | - | 不超过 100 个字符 |
| `reference_type` | string | 是 | - | `image_refer` 或 `video_refer` |
| `element_image_list` | object | `image_refer` 必填 | - | `frontal_image`（正面图）加 1–3 张 `refer_images[].image_url` |
| `element_video_list` | object | `video_refer` 必填 | - | `refer_videos: [{"video_url": "URL"}]`，仅 1 段 |
| `element_voice_id` | string | 否 | - | 绑定自己的音色，或已通过官方列表查询过的官方音色 |
| `tag_list` | array | 否 | - | `[{"tag_id":"o_102"}]` |
| `callback_url` | string | 否 | - | 任务状态变化时的 HTTPS 回调地址（顶层字段），见[回调](/video/kling#回调) |
| `external_task_id` | string | 否 | - | 自定义任务 ID，同一账号下不可重复（顶层字段） |
* 图片：URL 或 Base64，JPG/JPEG/PNG，≤ 10MB，宽高 ≥ 300px，比例 1:2.5–2.5:1。
* 视频：MP4/MOV，3–8 秒，1080p，16:9 或 9:16，≤ 200MB，仅支持写实人形；视频包含人声时上游可能自动定制并绑定音色。
* 标签 `o_101`–`o_108` 依次为热梗、人物、动物、道具、服饰、场景、特效、其他。
### 其他接口参数
| 接口 | 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------------------------------------------------------------------- | ------------ | ------- | -- | ---- | ----------------- |
| `GET .../advanced-custom-elements/{id}` | `id`（路径） | string | 是 | - | 创建任务 ID 或自定义任务 ID |
| `GET .../advanced-custom-elements`、`GET .../advanced-presets-elements` | `pageNum` | integer | 否 | `1` | `1`–`1000` |
| 同上 | `pageSize` | integer | 否 | `30` | `1`–`500` |
| `POST .../delete-advanced-elements` | `element_id` | string | 是 | - | 要删除的主体 ID |
## 响应
轮询单个查询，`data.task_status` 为 `submitted`、`processing`、`succeed`（终态）、`failed`（终态）。
| 字段 | 类型 | 说明 |
| ---------------------------------------- | ------ | ----------------------------------------------- |
| `data.task_id` | string | 创建任务 ID |
| `data.task_status` | string | 任务状态 |
| `data.task_info.external_task_id` | string | 自定义任务 ID |
| `data.task_result.elements[].element_id` | string | 成功后的主体 ID，在 Omni 的 `contents` 中以 `element` 素材引用 |
* 列表（`GET .../advanced-custom-elements`）只返回当前用户的创建任务记录，不受 30 天限制；官方列表实时查询上游。
* 删除成功后 LoopToken 立即停止允许引用该主体，原创建任务快照保留历史结果。
* 不返回上游成本字段。
## 计费
创建时预扣一次，失败任务退款；查询、列表和删除不收费。
## 错误
创建时的参数校验返回 `400 / 1201`，其余为本页特有的错误：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| 400 | `1201` | `element_name is required and must be a string` / `element_description is required and must be a string` | 补齐必填字段 |
| 400 | `1201` | `element_name must not exceed 20 characters` / `element_description must not exceed 100 characters` | 缩短文本 |
| 400 | `1201` | `reference_type must be image_refer or video_refer` | 传二者之一 |
| 400 | `1201` | `element_image_list requires frontal_image and 1-3 refer_images` / `refer_images require image_url` | 补正面图，参考图 1–3 张且都带 `image_url` |
| 400 | `1201` | `element_video_list requires exactly one refer_videos entry with video_url` | `refer_videos` 恰好 1 项且带 `video_url` |
| 400 | `1201` | `invalid pageNum` / `invalid pageSize`（列表） | 页码 `1`–`1000`，每页 `1`–`500` |
| 400 | `1201` | `invalid JSON body` / `asset ID is required`（删除） | 请求体传 `{"element_id":"..."}` |
| 404 | `1203` | `asset not found`（删除）：不是自己创建的主体，或渠道不可用 | 官方主体不能删除，核对 `element_id` |
| 404 | `1203` | `task not found`（查询） | 核对任务 ID |
| 503 | `5001` | 没有能使用所引用音色（`element_voice_id`）的渠道 | 确认音色是自己创建的，或先查询官方列表 |
通用错误见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **引用主体** → 只能引用自己创建的主体，或已通过官方列表核实的预置主体。
* **删除** → 只有创建者可以删除自定义主体，官方主体不能删除。
* **渠道绑定** → 主体与音色都绑定到原上游渠道账号，不能跨渠道账号引用。
# 查询任务
Source: https://looptoken.vibelab.me/docs/video/kling/get-tasks
> GET /tasks：按任务 ID 或自定义任务 ID 查询文生视频、图生视频、动作控制、全能参考视频任务
查询文生视频、图生视频、动作控制、全能参考视频任务。
| 项 | 值 |
| -- | ----- |
| 模式 | 同步查询 |
| 计费 | 查询不收费 |
## 快速开始
```bash
curl "https://api.vibelab.me/tasks?task_ids=893605946402811985,893605946402811986" \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": [
{
"id": "893605946402811985",
"status": "succeeded",
"message": "",
"create_time": 1781080778802,
"update_time": 1781080794151,
"external_id": "your-id",
"outputs": [
{
"type": "video",
"id": "893605946402811986",
"url": "https://example.com/result.mp4",
"watermark_url": "https://example.com/result-wm.mp4",
"duration": "5"
}
]
}
]
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
### 查询参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------- | ------ | --- | -- | --------------------------- |
| `task_ids` | string | 二选一 | - | 任务 ID，多个用英文逗号分隔，最多 100 个 |
| `external_task_ids` | string | 二选一 | - | 自定义任务 ID，多个用英文逗号分隔，最多 100 个 |
## 响应
| 字段 | 类型 | 说明 |
| ----------------------------------------- | ------- | --------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data[]` | array | 任务列表，字段见下 |
| `data[].id` | string | 任务 ID |
| `data[].status` | string | `submitted`、`processing`、`succeeded`、`failed` |
| `data[].message` | string | 失败原因 |
| `data[].create_time`、`data[].update_time` | integer | Unix 毫秒时间戳 |
| `data[].external_id` | string | 自定义任务 ID |
| `data[].outputs[].type` | string | `video` |
| `data[].outputs[].id` | string | 视频 ID |
| `data[].outputs[].url` | string | 视频地址，30 天后清理，请及时转存 |
| `data[].outputs[].watermark_url` | string | 含水印视频地址 |
| `data[].outputs[].duration` | string | 视频时长，单位秒 |
## 计费
查询不收费。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ----------------------------------------------------------- | ------------------ |
| 400 | `1201` | `exactly one of task_ids and external_task_ids is required` | 两个参数二选一，不能都传也不能都不传 |
| 400 | `1201` | `at most 100 ids per query` | 拆成多次查询 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **查不到的 ID** → 不报错，该 ID 不出现在 `data` 中（任务不存在或不属于当前账号时返回空数组）。
* **查询范围** → 只能查询自己最近 30 天的任务。
* **适用范围** → 仅文生视频、图生视频、动作控制、全能参考视频；数字人、音效、对口型、多模态编辑使用各自的查询接口。
# 人脸识别
Source: https://looptoken.vibelab.me/docs/video/kling/identify-face
> POST /v1/videos/identify-face：识别视频中可对口型的人脸，对口型的前置步骤，同步
识别视频中可以对口型的人脸，得到后续[创建对口型任务](/video/kling/lip-sync-create)需要的 `session_id` 和 `face_id`。
| 项 | 值 |
| -- | ---------- |
| 模式 | 同步 |
| 计费 | 每次成功识别计费一次 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/identify-face \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/talk.mp4"
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"session_id": "850508686686064678",
"face_data": [
{
"face_id": "0",
"face_image": "https://example.com/face0.png",
"start_time": 0,
"end_time": 5200
}
]
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------ | -- | -- | ----------------------------------------------------------------------- |
| `video_url` | string | 是 | - | 视频地址；mp4/mov，不超过 100MB，2–60 秒，720p 或 1080p，边长 512–2160px。不支持 `video_id` |
## 响应
| 字段 | 类型 | 说明 |
| ---------------------------------------- | ------- | --------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.session_id` | string | 会话 ID，只有识别它的账号可以使用 |
| `data.face_data[].face_id` | string | 人脸 ID |
| `data.face_data[].face_image` | string | 人脸图片地址 |
| `data.face_data[].start_time`、`end_time` | integer | 人脸出现的起止时间，毫秒 |
## 计费
每次成功识别计费一次；识别失败不收费。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | -------------------------------------------- | -------------- |
| 400 | `1201` | `request body must be a JSON object` | 请求体传 JSON 对象 |
| 400 | `1201` | `video_url is required and must be a string` | 传 `video_url` |
| 400 | `1201` | `video_id is not supported, use video_url` | 改传 `video_url` |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **会话归属** → `session_id` 只有识别它的账号可以使用。
# 图像识别
Source: https://looptoken.vibelab.me/docs/video/kling/image-recognize
> POST /v1/videos/image-recognize：识别图片中的主体、人脸和服装，同步
直接返回识别结果。
| 项 | 值 |
| -- | ---------- |
| 模式 | 同步 |
| 计费 | 每次成功识别计费一次 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/image-recognize \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/photo.png"
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"task_result": {
"images": [
{
"type": "object_seg",
"is_contain": true,
"url": "https://example.com/object_seg.png"
},
{
"type": "head_seg",
"is_contain": true,
"url": "https://example.com/head_seg.png"
},
{
"type": "face_seg",
"is_contain": true,
"url": "https://example.com/face_seg.png"
},
{
"type": "cloth_seg",
"is_contain": true,
"url": "https://example.com/cloth_seg.png"
}
]
}
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ------ | -- | -- | ------------------------------------------------------------------------ |
| `image` | string | 是 | - | 图片 URL 或不带前缀的 Base64；jpg/jpeg/png，不超过 10MB，宽高不小于 300px，宽高比 1:2.5 到 2.5:1 |
## 响应
| 字段 | 类型 | 说明 |
| -------------------------------------- | ------- | ------------------------------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.task_result.images[].type` | string | `object_seg` 主体、`head_seg` 含头发的人脸、`face_seg` 不含头发的人脸、`cloth_seg` 服装 |
| `data.task_result.images[].is_contain` | boolean | 是否识别到 |
| `data.task_result.images[].url` | string | 识别结果图片地址，30 天后清理，请及时转存 |
## 计费
每次成功识别计费一次；识别失败不收费。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ---------------------------------------- | ------------ |
| 400 | `1201` | `request body must be a JSON object` | 请求体传 JSON 对象 |
| 400 | `1201` | `image is required and must be a string` | 传 `image` |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
# 图生视频
Source: https://looptoken.vibelab.me/docs/video/kling/image-to-video
> POST /image-to-video/{model}：可灵 3.0 / 3.0 Turbo 图生视频，异步，用 GET /tasks 查询
用首帧（可选尾帧、主体）和提示词生成视频。
| 项 | 值 |
| -- | -------------------------------------------------------- |
| 模型 | `kling-3.0-turbo` / `kling-3.0` |
| 模式 | 异步（提交 → 轮询 `GET /tasks`，见[查询任务](/video/kling/get-tasks)） |
| 计费 | 按输出视频时长（秒）结算 |
## 快速开始
```bash
curl https://api.vibelab.me/image-to-video/kling-3.0 \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"type": "prompt",
"text": "女孩坐在火车上望向窗外，神情忧郁"
},
{
"type": "first_frame",
"url": "https://example.com/start.jpg"
},
{
"type": "last_frame",
"url": "https://example.com/end.jpg"
}
],
"settings": {
"resolution": "1080p",
"duration": 10,
"audio": "native"
}
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"id": "893605946402811985",
"status": "submitted",
"create_time": 1781080778802,
"update_time": 1781080778802,
"external_id": "your-id"
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 路径参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ------ | -- | -- | ------------------------------- |
| `model` | string | 是 | - | `kling-3.0-turbo` 或 `kling-3.0` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------------------------- | ------- | -- | ------- | ------------------------------------------------ |
| `contents` | array | 是 | - | 素材数组，元素见下 |
| `contents[].type=prompt` | object | 否 | - | 提示词，字段 `text`，不超过 3072 个字符 |
| `contents[].type=first_frame` | object | 是 | - | 首帧图，字段 `url`（公网 URL 或 Base64），必须有 |
| `contents[].type=last_frame` | object | 否 | - | 尾帧图，字段 `url`；仅 `kling-3.0`，须与 `first_frame` 同时传 |
| `contents[].type=element` | object | 否 | - | 主体引用，字段 `element_id` 和 `id`，最多 3 个；仅 `kling-3.0` |
| `settings.resolution` | string | 否 | `720p` | 同[文生视频](/video/kling/text-to-video) |
| `settings.duration` | integer | 否 | `5` | `3`–`15` 秒 |
| `settings.audio` | string | 否 | `off` | 仅 `kling-3.0`：`native` 或 `off` |
| `options.callback_url` | string | 否 | - | 任务状态变化时的 HTTPS 回调地址，见[概览](/video/kling#回调) |
| `options.external_task_id` | string | 否 | - | 自定义任务 ID，同一账号下不可重复 |
| `options.watermark_info.enabled` | boolean | 否 | `false` | 是否同时生成含水印结果 |
## 响应
| 字段 | 类型 | 说明 |
| ------------------------------------- | ------- | --------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.id` | string | 任务 ID |
| `data.status` | string | `submitted`、`processing`、`succeeded`、`failed` |
| `data.create_time`、`data.update_time` | integer | Unix 毫秒时间戳 |
| `data.external_id` | string | 创建时传入的 `options.external_task_id`，没传则无此字段 |
## 计费
按输出视频时长（秒）结算；任务失败全额退回。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| 404 | `1203` | `model not found`（路径 `{model}` 不是已上架的可灵模型） | 路径写 `kling-3.0-turbo` 或 `kling-3.0` |
| 400 | `1201` | `contents is required and must be a non-empty array` | 传非空 `contents` 数组 |
| 400 | `1201` | `contents must include a first_frame` | 补一项 `first_frame` |
| 400 | `1201` | `unsupported contents type "..." for ...` | 只接受 `prompt`、`first_frame`、`last_frame`、`element`；`kling-3.0-turbo` 不接受 `last_frame`、`element` |
| 400 | `1201` | `at most 3 elements are supported` | `element` 不超过 3 个 |
| 400 | `1201` | `prompt must not exceed 3072 characters` | 缩短提示词 |
| 400 | `1201` | `settings.resolution "..." is not supported for ...` | 同[文生视频](/video/kling/text-to-video#错误) |
| 400 | `1201` | `settings.duration must be between 3 and 15` | 传 `3`–`15` 的整数 |
| 400 | `1201` | `settings.audio "..." is not supported for ...` | `kling-3.0` 只接受 `native`/`off`；`kling-3.0-turbo` 不能传 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **图片格式** → 支持 jpg、jpeg、png，宽高不小于 300px，宽高比在 1:2.5 到 2.5:1 之间。
# Kling 原生接口
Source: https://looptoken.vibelab.me/docs/video/kling
> 可灵 4.0 / 3.0 / 3.0 Turbo 视频生成、动作控制、数字人、音效、对口型、多模态编辑、图像识别，路径与字段和可灵官方 API 一致
LoopToken 直接使用可灵官方 API 的路径、请求体和响应体。把官方示例里的域名换成 `https://api.vibelab.me`，把 `Authorization` 换成 LoopToken API Key，即可沿用官方文档和 SDK 的写法。
模型的可用状态以[模型列表](/models)为准，精确价格以[定价页](/pricing)为准。
## 认证与基础地址
| 项 | 值 |
| ---- | ------------------------------------------------------------ |
| 基础地址 | `https://api.vibelab.me` |
| 认证 | `Authorization: Bearer $LOOPTOKEN_API_KEY`，所有接口使用同一个 API Key |
## Kling 4.0
[视频生成与全能参考](/video/kling/kling-4) · [主体管理](/video/kling/elements) · [音色管理](/video/kling/voices)
4.0 使用 `/text-to-video/kling-4.0`、`/image-to-video/kling-4.0`、`/omni-video/kling-4.0`，支持 3–30 秒、720p/1080p。主体和音色管理使用 `/v1/general/*`。
## 接口清单
| 方法 | 路径 | 说明 | 文档 |
| ---- | --------------------------------------------- | ------------------------- | -------------------------------------------------------- |
| POST | `/text-to-video/{model}` | 文生视频 | [文生视频](/video/kling/text-to-video) |
| POST | `/image-to-video/{model}` | 图生视频 | [图生视频](/video/kling/image-to-video) |
| POST | `/omni-video/kling-4.0` | 4.0 全能参考生成与视频编辑 | [Kling 4.0](/video/kling/kling-4) |
| POST | `/motion-control/kling-3.0` | 动作控制 | [动作控制](/video/kling/motion-control) |
| GET | `/tasks` | 查询任务（文生视频、图生视频、动作控制、全能参考） | [查询任务](/video/kling/get-tasks) |
| POST | `/tasks` | 按游标列出任务 | [按游标列出任务](/video/kling/list-tasks) |
| POST | `/v1/videos/avatar/image2video` | 创建数字人任务 | [创建数字人任务](/video/kling/avatar-create) |
| GET | `/v1/videos/avatar/image2video/{id}` | 查询数字人任务 | [查询数字人任务](/video/kling/avatar-get) |
| GET | `/v1/videos/avatar/image2video` | 数字人任务列表 | [数字人任务列表](/video/kling/avatar-list) |
| POST | `/v1/audio/text-to-audio` | 创建文生音效任务 | [创建文生音效任务](/video/kling/text-to-audio-create) |
| GET | `/v1/audio/text-to-audio/{id}` | 查询文生音效任务 | [查询文生音效任务](/video/kling/text-to-audio-get) |
| GET | `/v1/audio/text-to-audio` | 文生音效任务列表 | [文生音效任务列表](/video/kling/text-to-audio-list) |
| POST | `/v1/videos/identify-face` | 人脸识别（对口型前置步骤） | [人脸识别](/video/kling/identify-face) |
| POST | `/v1/videos/advanced-lip-sync` | 创建对口型任务 | [创建对口型任务](/video/kling/lip-sync-create) |
| GET | `/v1/videos/advanced-lip-sync/{id}` | 查询对口型任务 | [查询对口型任务](/video/kling/lip-sync-get) |
| GET | `/v1/videos/advanced-lip-sync` | 对口型任务列表 | [对口型任务列表](/video/kling/lip-sync-list) |
| POST | `/v1/videos/multi-elements/init-selection` | 初始化待编辑视频 | [初始化待编辑视频](/video/kling/multi-elements-init-selection) |
| POST | `/v1/videos/multi-elements/add-selection` | 增加视频选区 | [增加视频选区](/video/kling/multi-elements-add-selection) |
| POST | `/v1/videos/multi-elements/delete-selection` | 删减视频选区 | [删减视频选区](/video/kling/multi-elements-delete-selection) |
| POST | `/v1/videos/multi-elements/clear-selection` | 清除视频选区 | [清除视频选区](/video/kling/multi-elements-clear-selection) |
| POST | `/v1/videos/multi-elements/preview-selection` | 预览已选区视频 | [预览已选区视频](/video/kling/multi-elements-preview-selection) |
| POST | `/v1/videos/multi-elements` | 创建多模态编辑任务 | [创建多模态编辑任务](/video/kling/multi-elements-create) |
| GET | `/v1/videos/multi-elements/{id}` | 查询多模态编辑任务 | [查询多模态编辑任务](/video/kling/multi-elements-get) |
| GET | `/v1/videos/multi-elements` | 多模态编辑任务列表 | [多模态编辑任务列表](/video/kling/multi-elements-list) |
| POST | `/v1/videos/image-recognize` | 图像识别 | [图像识别](/video/kling/image-recognize) |
两种接口风格：
* 新版（文生视频、图生视频、动作控制、全能参考）：用 `/tasks` 查询，响应字段 `id` / `status` / `succeeded`。
* 旧版（其余能力，官方的 `/v1/...` 接口）：各自有单个查询和分页列表，响应字段 `task_id` / `task_status` / `succeed`。
请按各接口页面的响应示例对接。
## 与官方的差别
* 响应中不返回扣费信息：新版的 `billing`，旧版的 `final_unit_deduction`、`final_balance_deduction`。
* `external_task_id` 在你的账号范围内去重。
* `callback_url` 由 LoopToken 向你的地址投递。
* 不支持 `video_id`、`audio_id`：它们指向可灵账号里的历史作品，不属于你的账号，请改用 `video_url`、`sound_file`。
* `session_id`（人脸识别、视频初始化返回）只能由识别它的账号使用。
## 任务状态
| 风格 | 状态取值 |
| -------------------- | --------------------------------------------- |
| 新版（3.0 系列、4.0、动作控制） | `submitted`、`processing`、`succeeded`、`failed` |
| 旧版（数字人、音效、对口型、多模态编辑） | `submitted`、`processing`、`succeed`、`failed` |
失败的任务不扣费。生成的视频、音频链接 30 天后会被清理，请及时转存。
## 回调
设置回调地址后，任务状态每次变化，LoopToken 会向该地址 `POST` 一份任务对象，结构与对应查询接口返回的单个任务相同。回调地址必须是公网 HTTPS，响应 2xx 视为投递成功，失败最多重试 3 次。
## 计费与预冻结
视频类接口按输出时长结算。提交任务时无法预知输出时长，所以会按该接口的时长上限预冻结额度，任务结束后按实际用量结算、多退少补；失败的任务全额退回。余额不足以预冻结时返回 `403 / 1102`。各接口的冻结口径见其页面的“计费”一节。
## 错误
错误响应与官方一致，结构为 `{ "code": ..., "message": "...", "request_id": "..." }`。各接口页的“错误”一节只列本页特有的参数校验错误，以下是通用错误。
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| 401 | `1000` | API Key 无效 | 检查 Key |
| 403 | `1102` | `insufficient credits`（余额不足以预冻结），或 `API key quota exceeded (settled usage)`（Key 额度用完） | 充值，或调高 Key 额度 |
| 429 | `1102` | `video generation quota exceeded`（账号的视频任务配额用完） | 联系管理员调整配额 |
| 403 | `1103` | `model not allowed for this key` | 换有权限的 Key |
| 403 | `1304` | `client IP not allowed for this key` | 把调用方 IP 加入 Key 白名单 |
| 429 | `1302` | `user or API key request limit exceeded` | 降低请求频率 |
| 429 | `1303` | `parallel task over limit`（并发任务数超限，响应带 `Retry-After`） | 退避重试 |
| 400 | `1201` | 参数非法，`message` 给出具体字段 | 按各接口页“错误”一节修正 |
| 400 | `1201` | `request body must be a JSON object` | 请求体传 JSON 对象 |
| 400 | `1201` | `callback_url` 不是公网 HTTPS 地址（如 `callback_url must use https`） | 改用公网 HTTPS 地址 |
| 400 | `1201` | `external_task_id already exists`（同一账号下重复） | 换一个自定义任务 ID |
| 400 | `1201` | `session_id not found`（会话不属于当前账号） | 重新初始化或识别 |
| 404 | `1203` | `model not found`（路径中的模型不存在）或 `task not found`（任务不存在或超过 30 天） | 核对路径与 ID |
| 400 | `1301` | 内容触发安全策略（上游返回，`message` 透传） | 修改素材或提示词 |
| 503 | `5001` | `no compatible video channel is available`、`model sales price is not configured` 或 `upstream service temporarily unavailable` | 稍后重试；持续出现请联系支持 |
上游返回 `1200`–`1203`、`1300`、`1301` 时，HTTP 状态、`code`、`message` 原样透传；返回 `1302`、`1303` 时转成 `429 / parallel task over limit`；其余上游错误统一返回 `503 / 5001`，不外露上游内部信息。
# Kling 4.0 视频生成
Source: https://looptoken.vibelab.me/docs/video/kling/kling-4
> kling-4.0：文生视频、多关键帧图生视频、全能参考生成与视频编辑，3–30 秒、720p/1080p，异步，用 GET /tasks 查询
可用状态以[模型列表](/models)为准，价格以[定价页](/pricing)为准。
可灵 4.0 的三个生成入口，路径与字段和可灵官方 API 一致。注意这些路径**不带 `/v1` 前缀**。
| 项 | 值 |
| ---- | -------------------------------------------------- |
| 模型 | `kling-4.0`（写在路径里，请求体不传 `model`） |
| 模式 | 异步（提交 → 轮询 [`GET /tasks`](/video/kling/get-tasks)） |
| 计费 | 按总时长（秒）结算，按分辨率、是否有输入视频分别计价，见[计费](#计费) |
| 媒体保留 | 结果链接 30 天后清理，请及时转存 |
## 快速开始
```bash
curl https://api.vibelab.me/text-to-video/kling-4.0 \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "一只猫在窗台上打哈欠，镜头缓慢推进，伴随轻柔的环境音。",
"settings": {"duration": 10, "resolution": "1080p", "aspect_ratio": "16:9"}
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"id": "893605946402811985",
"status": "submitted",
"create_time": 1781080778802,
"update_time": 1781080778802
}
}
```
用 `data.id` 调用 `GET /tasks?task_ids=893605946402811985` 查询结果，见[响应](#响应)。
## 模式选择
| 模式 | 入口 | 怎么传参 |
| ------ | --------------------------- | ---------------------------------------------------------------------------------- |
| 文生视频 | `/text-to-video/kling-4.0` | 顶层 `prompt` |
| 图生视频 | `/image-to-video/kling-4.0` | `contents` 中放 1–10 张 `first_frame` / `middle_frame` / `last_frame`，可选 1 项 `prompt` |
| 全能参考生成 | `/omni-video/kling-4.0` | `contents` 中恰好 1 项 `prompt`，加参考图、参考视频、主体、音色 |
| 视频编辑 | `/omni-video/kling-4.0` | 同上，素材中放 1 段 `base_video`（待编辑视频） |
## 请求参数
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------------------------- | --------- | --------- | ------------------------- | ----------------------------------------------------------------------------- |
| `prompt` | string | 文生视频必填 | - | 仅文生视频使用。长度须满足 `英文字符数 / 26000 + 非英文字符数 / 11000 ≤ 1`（纯英文 ≤ 26,000，纯中文 ≤ 11,000） |
| `contents` | object\[] | 图生、全能参考必填 | - | 素材列表，每项结构见下表 |
| `settings.resolution` | string | 否 | `1080p` | `720p`、`1080p` |
| `settings.duration` | integer | 否 | 由模型决定 | `3`–`30` 秒。省略时由模型从提示词识别时长，识别不到为 10 秒；有待编辑视频时优先采用其时长 |
| `settings.aspect_ratio` | string | 否 | 文生 `16:9`；全能参考 `adaptive` | `21:9`、`16:9`、`9:16`、`1:1`；全能参考额外支持 `adaptive`；图生视频采用图片比例 |
| `options.callback_url` | string | 否 | - | 任务状态变化时的 HTTPS 回调地址，见[回调](/video/kling#回调) |
| `options.external_task_id` | string | 否 | - | 自定义任务 ID，同一账号下不可重复，可用于查询 |
| `options.watermark_info.enabled` | boolean | 否 | `false` | 是否额外生成带水印结果 |
### contents 素材项
| `type` | 内容字段 | `id` | 数量限制 |
| ---------------------------- | ---------------------- | ----------- | ------------------------ |
| `prompt` | `text`（长度规则同 `prompt`） | - | 图生视频 ≤ 1；全能参考恰好 1 |
| `first_frame` / `last_frame` | `url` | 可选 | 各 ≤ 1 |
| `middle_frame` | `url` | 全能参考中有多张时必填 | 图片合计 ≤ 10 |
| `refer_image` | `url` | 多张时必填 | 图片合计 ≤ 10；仅全能参考 |
| `feature_video` | `url` | 可选 | 参考视频 + 待编辑视频合计 ≤ 5；仅全能参考 |
| `base_video` | `url` | 可选 | ≤ 1；仅全能参考 |
| `element` | `element_id` | 必填 | ≤ 7（视频角色主体 ≤ 3）；仅全能参考 |
| `voice` | `voice_id` | 必填 | ≤ 3；仅全能参考 |
* 除 `prompt` 外的素材合计 ≤ 15；同一任务内 `id` 不得重复，在提示词中用 `@id` 引用。
* 图片：URL 或 Base64，JPG/JPEG/PNG，≤ 30MB，宽高 ≥ 300px，比例 2:5–5:2。
* 视频：URL，MP4/MOV，≤ 300MB，每段和总时长 3–30 秒（含视频角色主体），宽高 700–4553px，总像素 ≤ 8,294,400，比例 2:5–5:2，24–60fps。存在视频角色主体时，其与参考视频合计 ≤ 5。
* 图片、视频的格式、尺寸和时长由上游最终校验；数量限制由 LoopToken 提交时校验。
* `element_id`、`voice_id` 来自[主体管理](/video/kling/elements)和[音色管理](/video/kling/voices)，只能引用自己创建的资产，或已通过官方列表核实的预置资产（**首次使用官方 ID 前先查询对应的官方列表页**）。
## 请求示例
### 图生视频：首帧、中间帧、尾帧
```json
{
"contents": [
{"type": "prompt", "text": "从 @start 自然过渡到 @middle，再到 @end，保持人物一致。"},
{"type": "first_frame", "url": "https://example.com/start.jpg", "id": "start"},
{"type": "middle_frame", "url": "https://example.com/middle.jpg", "id": "middle"},
{"type": "last_frame", "url": "https://example.com/end.jpg", "id": "end"}
],
"settings": {"duration": 15, "resolution": "1080p"}
}
```
### 视频编辑
```json
{
"contents": [
{"type": "prompt", "text": "编辑 @video，参考 @image 的色彩，保留原有动作与背景。"},
{"type": "base_video", "url": "https://example.com/input.mp4", "id": "video"},
{"type": "refer_image", "url": "https://example.com/style.jpg", "id": "image"}
],
"settings": {"duration": 10, "resolution": "1080p", "aspect_ratio": "adaptive"}
}
```
## 响应
用 [`GET /tasks`](/video/kling/get-tasks) 查询，状态依次为 `submitted` → `processing` → `succeeded` / `failed`（终态）。成功结果在 `data[].outputs`：
| 字段 | 类型 | 说明 |
| ------------------------- | ------ | ----------------------------------------------------- |
| `outputs[].type` | string | `video` |
| `outputs[].url` | string | 视频地址 |
| `outputs[].duration` | string | 实际输出时长（秒） |
| `outputs[].watermark_url` | string | 带水印结果，仅 `options.watermark_info.enabled` 为 `true` 时返回 |
| `usage.input_duration` | string | 输入视频总时长（秒，含视频角色主体），仅有输入视频且任务结束时返回 |
输出为 24fps，始终带声音（声音内容通过提示词描述）。除上游的 `billing` 扣费字段外，官方返回的其他字段原样透传。
## 计费
总时长按官方规则计算后乘以对应档位单价。输出时长按标称整数秒计（如结果 `3.041` 秒计 3 秒），输入时长按 `usage.input_duration`（两位小数）计：
| 情况 | 总时长 | 档位 |
| ----------------- | ----------- | ----- |
| 无输入视频 | 输出时长 | 无视频输入 |
| 有输入视频，输入时长 ≤ 输出时长 | 输出时长 × 2 | 有视频输入 |
| 有输入视频，输入时长 > 输出时长 | 输入时长 + 输出时长 | 有视频输入 |
输入视频包含 `feature_video`、`base_video` 和视频角色主体，是否有输入视频以结果中的 `usage.input_duration` 为准。
* 提交时按 `settings.duration` 预冻结，省略时长按 30 秒；含 `feature_video`、`base_video` 或 `element` 时按有视频输入档位、时长再加 30 秒预冻结。
* 成功后按实际总时长结算，多退少补；失败全额退回。
## 错误
错误体为 `{"code": ..., "message": "...", "request_id": "..."}`，通用错误码见 [Kling 错误](/video/kling#错误)。以下是本页参数校验返回的 `400 / 1201`：
| `message` | 处理 |
| ---------------------------------------------------------------------------- | -------------------------------------------------- |
| `prompt is required and must be a string` | 文生视频传顶层 `prompt`；`contents` 中的 `prompt` 项要带 `text` |
| `prompt exceeds Kling 4.0 mixed-language length limit` | 缩短提示词，满足混合长度规则 |
| `contents must be a non-empty array` | 图生、全能参考必须传 `contents` |
| `contents must include exactly one prompt` | 全能参考恰好 1 项 `prompt`；图生最多 1 项 |
| `image-to-video requires 1-10 images; omni-video supports at most 10 images` | 调整图片数量 |
| `unsupported image-to-video contents type "..."` | 图生视频只接受 `prompt` 和三种帧 |
| `contents exceeds Kling 4.0 material limits` | 对照[素材项](#contents-素材项)的数量限制 |
| `element requires id` / `voice requires id` | 为主体、音色素材填写 `id` |
| `settings.duration must be an integer between 3 and 30` | 时长传 3–30 的整数，或省略 |
| `settings.resolution must be 720p or 1080p` | 4.0 不支持 `4k` |
| `settings.audio is not supported for kling-4.0` | 删除 `settings.audio`，在提示词中描述声音 |
| `unsupported settings.aspect_ratio` | `adaptive` 仅全能参考可用 |
| `external_task_id already exists` | 换一个自定义任务 ID |
没有能使用所引用主体或音色的渠道时，返回 `503 / 5001`。
## 注意事项
* **请求体传 `settings.audio`** → 400；4.0 始终有声。
* **主体、音色资产** → 只能在创建或查询它的原渠道账号下使用。
# 创建对口型任务
Source: https://looptoken.vibelab.me/docs/video/kling/lip-sync-create
> POST /v1/videos/advanced-lip-sync：让视频中的人脸对上指定音频的口型，异步
让视频中的人脸对上指定音频的口型。
| 项 | 值 |
| -- | ----------------------------------------------------------------------------------------- |
| 模式 | 异步（提交 → 轮询 `GET /v1/videos/advanced-lip-sync/{id}`，见[查询对口型任务](/video/kling/lip-sync-get)） |
| 计费 | 按输出视频实际时长计费，5 秒为单位向上取整，提交时按 60 秒预冻结 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/advanced-lip-sync \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session_id": "850508686686064678",
"face_choose": [
{
"face_id": "0",
"sound_file": "https://example.com/speech.mp3",
"sound_start_time": 0,
"sound_end_time": 3000,
"sound_insert_time": 1000,
"sound_volume": 1,
"original_audio_volume": 1
}
]
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"task_id": "893605946402811985",
"task_status": "submitted",
"task_info": {
"external_task_id": "your-id"
},
"created_at": 1722769557708,
"updated_at": 1722769557708
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------------------------- | ------- | -- | ------- | ----------------------------------------------------- |
| `session_id` | string | 是 | - | [人脸识别](/video/kling/identify-face)返回的会话，只能使用自己识别得到的会话 |
| `face_choose` | array | 是 | - | 指定人脸，目前仅支持 1 张 |
| `face_choose[].face_id` | string | 是 | - | 人脸 ID |
| `face_choose[].sound_file` | string | 是 | - | 音频 URL 或 Base64；mp3/wav/m4a/aac，不超过 5MB，2–60 秒 |
| `face_choose[].sound_start_time` | integer | 是 | - | 音频裁剪起点（毫秒） |
| `face_choose[].sound_end_time` | integer | 是 | - | 音频裁剪终点（毫秒），裁剪后不短于 2 秒 |
| `face_choose[].sound_insert_time` | integer | 是 | - | 裁剪后音频插入视频的时间（毫秒），与该人脸可对口型区间至少重合 2 秒 |
| `face_choose[].sound_volume` | number | 否 | `1` | 音频音量，0–2 |
| `face_choose[].original_audio_volume` | number | 否 | `1` | 原视频音量，0–2 |
| `watermark_info.enabled` | boolean | 否 | `false` | 是否同时生成含水印结果 |
| `callback_url` | string | 否 | - | HTTPS 回调地址 |
| `external_task_id` | string | 否 | - | 自定义任务 ID，同一账号下不可重复 |
## 响应
| 字段 | 类型 | 说明 |
| ----------------------------------- | ------- | ------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.task_id` | string | 任务 ID |
| `data.task_status` | string | `submitted`、`processing`、`succeed`、`failed` |
| `data.task_info.external_task_id` | string | 创建时传入的自定义任务 ID |
| `data.created_at`、`data.updated_at` | integer | Unix 毫秒时间戳 |
## 计费
按输出视频实际时长计费，不足 5 秒按 5 秒、向上取整到 5 秒的整数倍。提交时按 60 秒预冻结额度，任务结束后多退少补；失败全额退回。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| 400 | `1201` | `session_id is required and must be a string` | 传[人脸识别](/video/kling/identify-face)返回的 `session_id` |
| 400 | `1201` | `session_id not found` | 会话不存在或不属于当前账号，重新初始化/识别后再用 |
| 400 | `1201` | `face_choose must contain exactly one face` | `face_choose` 恰好 1 项 |
| 400 | `1201` | `face_id is required and must be a string` / `sound_file is required and must be a string` | 补齐 `face_choose[]` 必填字段 |
| 400 | `1201` | `audio_id is not supported, use sound_file` | 改传 `sound_file` |
| 400 | `1201` | `sound_start_time, sound_end_time and sound_insert_time are required numbers` | 三个时间字段都传数字（毫秒） |
| 400 | `1201` | `trimmed sound must be at least 2000 ms and start with non-negative times` | 裁剪后不短于 2000 毫秒，起点和插入时间不为负 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **前置步骤** → 先调用[人脸识别](/video/kling/identify-face)得到 `session_id` 和 `face_id`。
* **与官方的差别** → 不支持 `face_choose[].audio_id`（它指向可灵账号里的历史作品，不属于你的账号），请改用 `sound_file`；响应不返回 `final_unit_deduction`、`final_balance_deduction`；`callback_url` 由 LoopToken 投递，`external_task_id` 在你的账号范围内去重。
# 查询对口型任务
Source: https://looptoken.vibelab.me/docs/video/kling/lip-sync-get
> GET /v1/videos/advanced-lip-sync/{id}：按 task_id 或 external_task_id 查询对口型任务
| 项 | 值 |
| -- | ----- |
| 模式 | 同步查询 |
| 计费 | 查询不收费 |
## 快速开始
```bash
curl "https://api.vibelab.me/v1/videos/advanced-lip-sync/893605946402811985" \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"task_id": "893605946402811985",
"task_status": "succeed",
"task_status_msg": "",
"task_info": {
"external_task_id": "your-id"
},
"task_result": {
"videos": [
{
"id": "893605946402811986",
"url": "https://example.com/result.mp4",
"watermark_url": "https://example.com/result-wm.mp4",
"duration": "5.0"
}
]
},
"created_at": 1722769557708,
"updated_at": 1722769600000
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
### 路径参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---- | ------ | -- | -- | ------------------------------------------- |
| `id` | string | 是 | - | 对口型任务的 `task_id`，或创建时传入的 `external_task_id` |
## 响应
| 字段 | 类型 | 说明 |
| ----------------------------------------- | ------- | ------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.task_id` | string | 任务 ID |
| `data.task_status` | string | `submitted`、`processing`、`succeed`、`failed` |
| `data.task_status_msg` | string | 失败原因 |
| `data.task_info.external_task_id` | string | 自定义任务 ID |
| `data.task_result.videos[].id` | string | 视频 ID |
| `data.task_result.videos[].url` | string | 视频地址，30 天后清理，请及时转存 |
| `data.task_result.videos[].watermark_url` | string | 含水印视频地址，仅请求了水印时有值 |
| `data.task_result.videos[].duration` | string | 视频时长，单位秒 |
| `data.created_at`、`data.updated_at` | integer | Unix 毫秒时间戳 |
## 计费
查询不收费。
## 错误
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | --------------------------------------- | ------- |
| 404 | `1203` | `task not found`：任务不存在、不属于当前账号或已超过 30 天 | 核对 `id` |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
# 对口型任务列表
Source: https://looptoken.vibelab.me/docs/video/kling/lip-sync-list
> GET /v1/videos/advanced-lip-sync：分页列出对口型任务
| 项 | 值 |
| -- | ----- |
| 模式 | 同步查询 |
| 计费 | 查询不收费 |
## 快速开始
```bash
curl "https://api.vibelab.me/v1/videos/advanced-lip-sync?pageNum=1&pageSize=30" \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": [
{
"task_id": "893605946402811985",
"task_status": "succeed",
"task_status_msg": "",
"task_info": {
"external_task_id": "your-id"
},
"task_result": {
"videos": [
{
"id": "893605946402811986",
"url": "https://example.com/result.mp4",
"watermark_url": "https://example.com/result-wm.mp4",
"duration": "5.0"
}
]
},
"created_at": 1722769557708,
"updated_at": 1722769600000
}
]
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
### 查询参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ------- | -- | ---- | ---------- |
| `pageNum` | integer | 否 | `1` | 页码，1–1000 |
| `pageSize` | integer | 否 | `30` | 每页数量，1–500 |
## 响应
| 字段 | 类型 | 说明 |
| ------------ | ------- | -------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data[]` | array | 任务列表，字段同[查询对口型任务](/video/kling/lip-sync-get) |
## 计费
查询不收费。
## 错误
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ------------------------------------ | ----------- |
| 400 | `1201` | `pageNum must be between 1 and 1000` | 页码传 1–1000 |
| 400 | `1201` | `pageSize must be between 1 and 500` | 每页数量传 1–500 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
# 按游标列出任务
Source: https://looptoken.vibelab.me/docs/video/kling/list-tasks
> POST /tasks：按时间窗口和状态游标分页列出文生视频、图生视频、动作控制、全能参考视频任务
按创建时间倒序列出文生视频、图生视频、动作控制、全能参考视频任务。
| 项 | 值 |
| -- | ----- |
| 模式 | 同步查询 |
| 计费 | 查询不收费 |
## 快速开始
```bash
curl https://api.vibelab.me/tasks \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"limit": 100,
"filters": [
{
"key": "status",
"values": [
"succeeded"
]
}
]
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"result": [
{
"id": "893605946402811985",
"status": "succeeded",
"message": "",
"create_time": 1781080778802,
"update_time": 1781080794151,
"external_id": "your-id",
"outputs": [
{
"type": "video",
"id": "893605946402811986",
"url": "https://example.com/result.mp4",
"watermark_url": "https://example.com/result-wm.mp4",
"duration": "5"
}
]
}
],
"count": 1,
"has_more": false
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | ------- | -- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `start_time` | string | 否 | `end_time` 往前 30 天 | 起始时间（毫秒时间戳） |
| `end_time` | string | 否 | 当前时间 | 结束时间（毫秒时间戳） |
| `cursor` | string | 否 | - | 上一页返回的 `next_cursor`；传入后忽略时间窗口 |
| `limit` | integer | 否 | `100` | 每页数量，最大 `500` |
| `filters` | array | 否 | - | `[{ "key": "status", "values": ["succeeded"] }]`；`key` 支持 `status`（`submitted`、`processing`、`succeeded`、`failed`）与 `product_type`（`video`；传其他值返回空列表） |
## 响应
| 字段 | 类型 | 说明 |
| ------------------ | ------- | -------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.result` | array | 任务列表，字段同[查询任务](/video/kling/get-tasks) |
| `data.count` | integer | 本页数量 |
| `data.has_more` | boolean | 是否还有下一页 |
| `data.next_cursor` | string | 下一页游标，仅 `has_more` 为 `true` 时返回 |
## 计费
查询不收费。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| 400 | `1201` | `invalid request body` | 请求体传合法 JSON |
| 400 | `1201` | `end_time must be a millisecond timestamp` / `start_time must be a millisecond timestamp` | 传毫秒时间戳 |
| 400 | `1201` | `start_time must be earlier than end_time` | 起始时间早于结束时间 |
| 400 | `1201` | `limit must not exceed 500` | `limit` 不超过 500 |
| 400 | `1201` | `unknown status filter ...` | `status` 取 `submitted`、`processing`、`succeeded`、`failed` |
| 400 | `1201` | `unknown filter key ...` | `key` 只支持 `status`、`product_type` |
| 400 | `1201` | `invalid cursor` | 原样传上一页返回的 `next_cursor` |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **`limit` 不传或小于等于 0** → 按 `100` 处理。
* **传 `cursor`** → 忽略 `start_time`，按游标继续往前翻。
# 动作控制
Source: https://looptoken.vibelab.me/docs/video/kling/motion-control
> POST /motion-control/kling-3.0：用参考视频的动作驱动参考图中的人物，异步，用 GET /tasks 查询
用动作参考视频驱动形象参考图中的人物。
| 项 | 值 |
| -- | -------------------------------------------------------- |
| 模型 | `kling-3.0-motion-control`（路径写 `kling-3.0`） |
| 模式 | 异步（提交 → 轮询 `GET /tasks`，见[查询任务](/video/kling/get-tasks)） |
| 计费 | 按输出视频实际时长结算，提交时预冻结 |
## 快速开始
```bash
curl https://api.vibelab.me/motion-control/kling-3.0 \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"type": "prompt",
"text": "女孩穿着宽松的灰色 T 恤和牛仔短裤"
},
{
"type": "image",
"url": "https://example.com/girl.png"
},
{
"type": "video",
"url": "https://example.com/dance.mp4"
}
],
"settings": {
"character_orientation": "video",
"resolution": "1080p",
"audio": "original"
}
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"id": "893605946402811985",
"status": "submitted",
"create_time": 1781080778802,
"update_time": 1781080778802,
"external_id": "your-id"
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------------------------- | ------- | -- | ---------- | ----------------------------------------------------------- |
| `contents[].type=prompt` | object | 否 | - | 提示词，字段 `text`，不超过 2500 个字符 |
| `contents[].type=image` | object | 是 | - | 形象参考图，字段 `url`（URL 或 Base64），有且仅有 1 张 |
| `contents[].type=video` | object | 是 | - | 动作参考视频，字段 `url`，有且仅有 1 个 |
| `contents[].type=element` | object | 否 | - | 主体引用，字段 `element_id` 和 `id`，最多 1 个 |
| `settings.character_orientation` | string | 是 | - | 人物朝向：`image`（与图片一致，参考视频 3–10 秒）或 `video`（与视频一致，参考视频 3–30 秒） |
| `settings.resolution` | string | 否 | `720p` | `720p`、`1080p` |
| `settings.audio` | string | 否 | `original` | `original`（保留参考视频原声）或 `off` |
| `options.callback_url` | string | 否 | - | 任务状态变化时的 HTTPS 回调地址，见[概览](/video/kling#回调) |
| `options.external_task_id` | string | 否 | - | 自定义任务 ID，同一账号下不可重复 |
| `options.watermark_info.enabled` | boolean | 否 | `false` | 是否同时生成含水印结果 |
## 响应
| 字段 | 类型 | 说明 |
| ------------------------------------- | ------- | --------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.id` | string | 任务 ID |
| `data.status` | string | `submitted`、`processing`、`succeeded`、`failed` |
| `data.create_time`、`data.update_time` | integer | Unix 毫秒时间戳 |
| `data.external_id` | string | 创建时传入的 `options.external_task_id`，没传则无此字段 |
## 计费
按**输出视频的实际时长**（不足 1 秒向上取整）结算。提交时按参考视频时长上限预冻结额度（`character_orientation` 为 `video` 时 30 秒，为 `image` 时 10 秒），任务结束后多退少补；失败全额退回。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ----------------------------------------------------------------- | -------------------------------------- |
| 404 | `1203` | `model not found`（路径 `{model}` 不是 `kling-3.0`） | 路径固定写 `kling-3.0` |
| 400 | `1201` | `contents is required and must be a non-empty array` | 传非空 `contents` |
| 400 | `1201` | `contents image requires a url` / `contents video requires a url` | `image`、`video` 项补 `url` |
| 400 | `1201` | `unsupported contents type "..." for motion-control` | 只接受 `prompt`、`image`、`video`、`element` |
| 400 | `1201` | `contents must include exactly one image and one video` | 各传且仅传 1 项 |
| 400 | `1201` | `at most 1 element is supported` | `element` 至多 1 个 |
| 400 | `1201` | `prompt must not exceed 2500 characters` | 缩短提示词 |
| 400 | `1201` | `settings.character_orientation must be image or video` | 必传 `image` 或 `video` |
| 400 | `1201` | `settings.resolution "..." is not supported for motion-control` | 传 `720p` 或 `1080p` |
| 400 | `1201` | `settings.audio "..." is not supported for motion-control` | 传 `original` 或 `off` |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **模型名** → 路径中的 `kling-3.0` 是官方写法，计费按模型 `kling-3.0-motion-control` 处理。
* **素材限制** → 图片支持 jpg、jpeg、png，不超过 50MB，宽高不小于 300px，宽高比 1:2.5 到 2.5:1；视频支持 mp4、mov，不超过 100MB，宽高在 340px 到 3850px 之间。
* **动作过快或过难** → 模型只提取有效动作，输出可能短于参考视频。
# 增加视频选区
Source: https://looptoken.vibelab.me/docs/video/kling/multi-elements-add-selection
> POST /v1/videos/multi-elements/add-selection：增加视频选区，同步
| 项 | 值 |
| -- | ------- |
| 模式 | 同步 |
| 计费 | 目前不单独计费 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/multi-elements/add-selection \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session_id": "847570360458960960",
"frame_index": 0,
"points": [
{
"x": 0.7738,
"y": 0.2971
}
]
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"status": 0,
"session_id": "847570360458960960",
"res": {
"frame_index": 0,
"rle_mask_list": [
{
"object_id": 0,
"rle_mask": {
"size": [
720,
1280
],
"counts": "…"
},
"png_mask": {
"size": [
720,
1280
],
"base64": "…"
}
}
]
}
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------- | ------- | -- | -- | ---------------------------------------------------------------- |
| `session_id` | string | 是 | - | 初始化返回的会话 |
| `frame_index` | integer | 是 | - | 帧号；最多支持 10 个标记帧，一次标记 1 帧 |
| `points` | array | 是 | - | 点选坐标 `[{ "x": 0.77, "y": 0.29 }]`，取值 0–1 的画面比例，左上角为原点；一帧最多 10 个点 |
## 响应
| 字段 | 类型 | 说明 |
| ------------------------------------ | ------- | ---------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.status` | integer | 拒识码，非 `0` 为识别失败 |
| `data.session_id` | string | 会话 ID |
| `data.res.frame_index` | integer | 帧号 |
| `data.res.rle_mask_list[].object_id` | integer | 选区对象编号 |
| `data.res.rle_mask_list[].rle_mask` | object | RLE 编码的掩码，`size` 为 \[高, 宽]，`counts` 为编码串 |
| `data.res.rle_mask_list[].png_mask` | object | PNG 掩码，`base64` 为图片数据 |
## 计费
目前不单独计费。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | --------------------------------------------- | ------------------------- |
| 400 | `1201` | `session_id is required and must be a string` | 传初始化返回的 `session_id` |
| 400 | `1201` | `session_id not found` | 会话不存在或不属于当前账号，重新初始化/识别后再用 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。选区、帧号、点坐标等字段由上游校验，上游的参数类错误（`1200`–`1203`、`1300`、`1301`）按其 HTTP、`code`、`message` 原样返回。
## 注意事项
* **会话归属** → 只能操作自己初始化得到的会话。
# 清除视频选区
Source: https://looptoken.vibelab.me/docs/video/kling/multi-elements-clear-selection
> POST /v1/videos/multi-elements/clear-selection：清除视频选区，同步
| 项 | 值 |
| -- | ------- |
| 模式 | 同步 |
| 计费 | 目前不单独计费 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/multi-elements/clear-selection \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session_id": "847570360458960960"
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"status": 0,
"session_id": "847570360458960960"
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | ------ | -- | -- | -------- |
| `session_id` | string | 是 | - | 初始化返回的会话 |
## 响应
| 字段 | 类型 | 说明 |
| ----------------- | ------- | --------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.status` | integer | 拒识码，非 `0` 为识别失败 |
| `data.session_id` | string | 会话 ID |
## 计费
目前不单独计费。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | --------------------------------------------- | ------------------------- |
| 400 | `1201` | `session_id is required and must be a string` | 传初始化返回的 `session_id` |
| 400 | `1201` | `session_id not found` | 会话不存在或不属于当前账号，重新初始化/识别后再用 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **会话归属** → 只能操作自己初始化得到的会话。
# 创建多模态编辑任务
Source: https://looptoken.vibelab.me/docs/video/kling/multi-elements-create
> POST /v1/videos/multi-elements：对视频增加、替换或删除元素，异步
对视频增加、替换或删除元素。
| 项 | 值 |
| -- | ---------------------------------------------------------------------------------------------- |
| 模式 | 异步（提交 → 轮询 `GET /v1/videos/multi-elements/{id}`，见[查询多模态编辑任务](/video/kling/multi-elements-get)） |
| 计费 | 按输出视频实际时长（秒）结算，提交时按请求的 `duration` 预冻结 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/multi-elements \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session_id": "847570360458960960",
"edit_mode": "removal",
"prompt": "删除<<>>中的【小鸡】",
"mode": "std",
"duration": "5"
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"task_id": "893605946402811985",
"task_status": "submitted",
"task_info": {
"external_task_id": "your-id"
},
"created_at": 1722769557708,
"updated_at": 1722769557708
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------------ | ------- | --- | ------- | ---------------------------------------------------------------------------------------- |
| `session_id` | string | 是 | - | 初始化返回的会话，只能使用自己初始化得到的会话 |
| `edit_mode` | string | 是 | - | `addition`（增加元素，`image_list` 1–2 张）、`swap`（替换元素，1 张）、`removal`（删除元素，不传） |
| `image_list` | array | 视模式 | - | `[{ "image": "URL 或不带前缀的 Base64" }]`；jpg/jpeg/png，不超过 10MB，宽高不小于 300px，宽高比 1:2.5 到 2.5:1 |
| `prompt` | string | 是 | - | 用 `<<>>`、`<<>>` 指代素材，不超过 2500 个字符 |
| `negative_prompt` | string | 否 | - | 不超过 2500 个字符 |
| `mode` | string | 否 | `std` | `std` 或 `pro` |
| `duration` | string | 否 | `"5"` | `"5"` 或 `"10"`；输入视频 2–5 秒对应 5，7–10 秒对应 10 |
| `watermark_info.enabled` | boolean | 否 | `false` | 是否同时生成含水印结果 |
| `callback_url` | string | 否 | - | 任务状态变化时的 HTTPS 回调地址，见[概览](/video/kling#回调) |
| `external_task_id` | string | 否 | - | 自定义任务 ID，同一账号下不可重复 |
## 响应
| 字段 | 类型 | 说明 |
| ----------------------------------- | ------- | ------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.task_id` | string | 任务 ID |
| `data.task_status` | string | `submitted`、`processing`、`succeed`、`failed` |
| `data.task_info.external_task_id` | string | 创建时传入的自定义任务 ID |
| `data.created_at`、`data.updated_at` | integer | Unix 毫秒时间戳 |
## 计费
按输出视频实际时长（秒）结算。提交时按请求的 `duration` 预冻结额度，任务结束后多退少补；失败全额退回。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | -------------------------------------------------------------------------------------------- | ------------------------- |
| 400 | `1201` | `session_id is required and must be a string` | 传初始化返回的 `session_id` |
| 400 | `1201` | `session_id not found` | 会话不存在或不属于当前账号，重新初始化/识别后再用 |
| 400 | `1201` | `edit_mode must be addition, swap or removal` | 传三者之一 |
| 400 | `1201` | `image_list must be an array` | `image_list` 传数组 |
| 400 | `1201` | `image_list must contain 1-2 images for addition`（`swap` 为 `1-1`，`removal` 为 `0-0`） | 按模式调整 `image_list` 数量 |
| 400 | `1201` | `image_list[].image is required` | 每项补 `image` |
| 400 | `1201` | `prompt is required and must be a string` | 传非空 `prompt` |
| 400 | `1201` | `prompt must not exceed 2500 characters` / `negative_prompt must not exceed 2500 characters` | 缩短文本 |
| 400 | `1201` | `mode must be std or pro` | 传 `std` 或 `pro` |
| 400 | `1201` | `duration must be 5 or 10` | 传 `"5"` 或 `"10"` |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **前置步骤** → 先[初始化视频](/video/kling/multi-elements-init-selection)，替换或删除元素时再标记选区。
* **继续编辑** → 任务成功后结果视频里的 `session_id` 也归你所有，可以继续编辑。
* **与官方的差别** → 响应不返回 `final_unit_deduction`、`final_balance_deduction`；`callback_url` 由 LoopToken 投递，`external_task_id` 在你的账号范围内去重。
# 删减视频选区
Source: https://looptoken.vibelab.me/docs/video/kling/multi-elements-delete-selection
> POST /v1/videos/multi-elements/delete-selection：删减视频选区，同步
| 项 | 值 |
| -- | ------- |
| 模式 | 同步 |
| 计费 | 目前不单独计费 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/multi-elements/delete-selection \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session_id": "847570360458960960",
"frame_index": 0,
"points": [
{
"x": 0.7738,
"y": 0.2971
}
]
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"status": 0,
"session_id": "847570360458960960",
"res": {
"frame_index": 0,
"rle_mask_list": [
{
"object_id": 0,
"rle_mask": {
"size": [
720,
1280
],
"counts": "…"
},
"png_mask": {
"size": [
720,
1280
],
"base64": "…"
}
}
]
}
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------- | ------- | -- | -- | ---------------------------------------------------------------------------- |
| `session_id` | string | 是 | - | 初始化返回的会话 |
| `frame_index` | integer | 是 | - | 帧号 |
| `points` | array | 是 | - | 点选坐标 `[{ "x": 0.77, "y": 0.29 }]`，取值 0–1 的画面比例，左上角为原点；一帧最多 10 个点，须与增加选区时完全一致 |
## 响应
| 字段 | 类型 | 说明 |
| ------------------------------------ | ------- | ---------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.status` | integer | 拒识码，非 `0` 为识别失败 |
| `data.session_id` | string | 会话 ID |
| `data.res.frame_index` | integer | 帧号 |
| `data.res.rle_mask_list[].object_id` | integer | 选区对象编号 |
| `data.res.rle_mask_list[].rle_mask` | object | RLE 编码的掩码，`size` 为 \[高, 宽]，`counts` 为编码串 |
| `data.res.rle_mask_list[].png_mask` | object | PNG 掩码，`base64` 为图片数据 |
## 计费
目前不单独计费。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | --------------------------------------------- | ------------------------- |
| 400 | `1201` | `session_id is required and must be a string` | 传初始化返回的 `session_id` |
| 400 | `1201` | `session_id not found` | 会话不存在或不属于当前账号，重新初始化/识别后再用 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。选区、帧号、点坐标等字段由上游校验，上游的参数类错误（`1200`–`1203`、`1300`、`1301`）按其 HTTP、`code`、`message` 原样返回。
## 注意事项
* **会话归属** → 只能操作自己初始化得到的会话。
# 查询多模态编辑任务
Source: https://looptoken.vibelab.me/docs/video/kling/multi-elements-get
> GET /v1/videos/multi-elements/{id}：按 task_id 或 external_task_id 查询多模态编辑任务
| 项 | 值 |
| -- | ----- |
| 模式 | 同步查询 |
| 计费 | 查询不收费 |
## 快速开始
```bash
curl "https://api.vibelab.me/v1/videos/multi-elements/893605946402811985" \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"task_id": "893605946402811985",
"task_status": "succeed",
"task_status_msg": "",
"task_info": {
"external_task_id": "your-id"
},
"task_result": {
"videos": [
{
"id": "893605946402811986",
"session_id": "847570360458961111",
"url": "https://example.com/result.mp4",
"watermark_url": "https://example.com/result-wm.mp4",
"duration": "5.0"
}
]
},
"created_at": 1722769557708,
"updated_at": 1722769600000
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
### 路径参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---- | ------ | -- | -- | --------------------------------------------- |
| `id` | string | 是 | - | 多模态编辑任务的 `task_id`，或创建时传入的 `external_task_id` |
## 响应
| 字段 | 类型 | 说明 |
| ----------------------------------------- | ------- | ------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.task_id` | string | 任务 ID |
| `data.task_status` | string | `submitted`、`processing`、`succeed`、`failed` |
| `data.task_status_msg` | string | 失败原因 |
| `data.task_info.external_task_id` | string | 自定义任务 ID |
| `data.task_result.videos[].id` | string | 视频 ID |
| `data.task_result.videos[].session_id` | string | 结果视频的会话 ID，可继续编辑 |
| `data.task_result.videos[].url` | string | 视频地址，30 天后清理，请及时转存 |
| `data.task_result.videos[].watermark_url` | string | 含水印视频地址，仅请求了水印时有值 |
| `data.task_result.videos[].duration` | string | 视频时长，单位秒 |
| `data.created_at`、`data.updated_at` | integer | Unix 毫秒时间戳 |
## 计费
查询不收费。
## 错误
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | --------------------------------------- | ------- |
| 404 | `1203` | `task not found`：任务不存在、不属于当前账号或已超过 30 天 | 核对 `id` |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
# 初始化待编辑视频
Source: https://looptoken.vibelab.me/docs/video/kling/multi-elements-init-selection
> POST /v1/videos/multi-elements/init-selection：多模态视频编辑第一步，初始化视频并得到 session_id，同步
编辑视频前先初始化，得到 `session_id`（24 小时有效）。
| 项 | 值 |
| -- | ------- |
| 模式 | 同步 |
| 计费 | 目前不单独计费 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/multi-elements/init-selection \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/source.mp4"
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"status": 0,
"session_id": "847570360458960960",
"fps": 30,
"original_duration": 5000,
"width": 720,
"height": 1280,
"total_frame": 150,
"normalized_video": "https://example.com/normalized.mp4"
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------ | -- | -- | ---------------------------------------------------------------------- |
| `video_url` | string | 是 | - | 视频地址；mp4/mov，时长 2–5 秒或 7–10 秒，边长 720–2160px，24/30/60fps。不支持 `video_id` |
## 响应
| 字段 | 类型 | 说明 |
| -------------------------- | ------- | --------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.status` | integer | 拒识码，非 `0` 为识别失败 |
| `data.session_id` | string | 会话 ID，24 小时有效 |
| `data.fps` | number | 解析后视频帧率 |
| `data.original_duration` | integer | 解析后视频时长 |
| `data.width`、`data.height` | integer | 解析后视频宽高 |
| `data.total_frame` | integer | 总帧数 |
| `data.normalized_video` | string | 初始化后的视频地址 |
## 计费
目前不单独计费。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | -------------------------------------------- | -------------- |
| 400 | `1201` | `request body must be a JSON object` | 请求体传 JSON 对象 |
| 400 | `1201` | `video_url is required and must be a string` | 传 `video_url` |
| 400 | `1201` | `video_id is not supported, use video_url` | 改传 `video_url` |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **会话归属** → 只能操作自己初始化得到的会话。
* **替换或删除元素** → 初始化后还要用选区接口标记元素。
* **会话有效期** → `session_id` 24 小时有效。
# 多模态编辑任务列表
Source: https://looptoken.vibelab.me/docs/video/kling/multi-elements-list
> GET /v1/videos/multi-elements：分页列出多模态编辑任务
| 项 | 值 |
| -- | ----- |
| 模式 | 同步查询 |
| 计费 | 查询不收费 |
## 快速开始
```bash
curl "https://api.vibelab.me/v1/videos/multi-elements?pageNum=1&pageSize=30" \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": [
{
"task_id": "893605946402811985",
"task_status": "succeed",
"task_status_msg": "",
"task_info": {
"external_task_id": "your-id"
},
"task_result": {
"videos": [
{
"id": "893605946402811986",
"session_id": "847570360458961111",
"url": "https://example.com/result.mp4",
"watermark_url": "https://example.com/result-wm.mp4",
"duration": "5.0"
}
]
},
"created_at": 1722769557708,
"updated_at": 1722769600000
}
]
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
### 查询参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ------- | -- | ---- | ---------- |
| `pageNum` | integer | 否 | `1` | 页码，1–1000 |
| `pageSize` | integer | 否 | `30` | 每页数量，1–500 |
## 响应
| 字段 | 类型 | 说明 |
| ------------ | ------- | ---------------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data[]` | array | 任务列表，字段同[查询多模态编辑任务](/video/kling/multi-elements-get) |
## 计费
查询不收费。
## 错误
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ------------------------------------ | ----------- |
| 400 | `1201` | `pageNum must be between 1 and 1000` | 页码传 1–1000 |
| 400 | `1201` | `pageSize must be between 1 and 500` | 每页数量传 1–500 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
# 预览已选区视频
Source: https://looptoken.vibelab.me/docs/video/kling/multi-elements-preview-selection
> POST /v1/videos/multi-elements/preview-selection：预览已选区视频，同步
| 项 | 值 |
| -- | ------- |
| 模式 | 同步 |
| 计费 | 目前不单独计费 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/videos/multi-elements/preview-selection \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session_id": "847570360458960960"
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"status": 0,
"session_id": "847570360458960960",
"res": {
"video": "https://example.com/masked.mp4",
"video_cover": "https://example.com/cover.png",
"tracking_output": "https://example.com/tracking.json"
}
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | ------ | -- | -- | -------- |
| `session_id` | string | 是 | - | 初始化返回的会话 |
## 响应
| 字段 | 类型 | 说明 |
| -------------------------- | ------- | --------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.status` | integer | 拒识码，非 `0` 为识别失败 |
| `data.session_id` | string | 会话 ID |
| `data.res.video` | string | 含选区掩码的视频 |
| `data.res.video_cover` | string | 该视频的封面 |
| `data.res.tracking_output` | string | 每一帧的掩码结果 |
## 计费
目前不单独计费。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | --------------------------------------------- | ------------------------- |
| 400 | `1201` | `session_id is required and must be a string` | 传初始化返回的 `session_id` |
| 400 | `1201` | `session_id not found` | 会话不存在或不属于当前账号，重新初始化/识别后再用 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **会话归属** → 只能操作自己初始化得到的会话。
# 创建文生音效任务
Source: https://looptoken.vibelab.me/docs/video/kling/text-to-audio-create
> POST /v1/audio/text-to-audio：用文字描述生成 3–10 秒音效，异步
用文字描述生成 3–10 秒的音效。
| 项 | 值 |
| -- | ------------------------------------------------------------------------------------------ |
| 模式 | 异步（提交 → 轮询 `GET /v1/audio/text-to-audio/{id}`，见[查询文生音效任务](/video/kling/text-to-audio-get)） |
| 计费 | 每次成功计费一次 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/audio/text-to-audio \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "春节庆祝时的烟花声",
"duration": 3
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"task_id": "893605946402811985",
"task_status": "submitted",
"task_info": {
"external_task_id": "your-id"
},
"created_at": 1722769557708,
"updated_at": 1722769557708
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------ | ------ | -- | -- | -------------------- |
| `prompt` | string | 是 | - | 音效描述，不超过 200 个字符 |
| `duration` | number | 是 | - | 时长，3.0–10.0 秒，最多一位小数 |
| `callback_url` | string | 否 | - | 任务状态变化时的 HTTPS 回调地址 |
| `external_task_id` | string | 否 | - | 自定义任务 ID，同一账号下不可重复 |
## 响应
| 字段 | 类型 | 说明 |
| ----------------------------------- | ------- | ------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.task_id` | string | 任务 ID |
| `data.task_status` | string | `submitted`、`processing`、`succeed`、`failed` |
| `data.task_info.external_task_id` | string | 创建时传入的自定义任务 ID |
| `data.created_at`、`data.updated_at` | integer | Unix 毫秒时间戳 |
## 计费
每次成功计费一次；任务失败全额退回。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ------------------------------------------------------------------------- | --------------------- |
| 400 | `1201` | `prompt is required and must be a string` | 传非空 `prompt` |
| 400 | `1201` | `prompt must not exceed 200 characters` | 缩短描述 |
| 400 | `1201` | `duration must be a number between 3.0 and 10.0 with at most one decimal` | 传 `3.0`–`10.0`，最多一位小数 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **与官方的差别** → 响应不返回 `final_unit_deduction`、`final_balance_deduction`；`callback_url` 由 LoopToken 投递，`external_task_id` 在你的账号范围内去重。
# 查询文生音效任务
Source: https://looptoken.vibelab.me/docs/video/kling/text-to-audio-get
> GET /v1/audio/text-to-audio/{id}：按 task_id 或 external_task_id 查询文生音效任务
| 项 | 值 |
| -- | ----- |
| 模式 | 同步查询 |
| 计费 | 查询不收费 |
## 快速开始
```bash
curl "https://api.vibelab.me/v1/audio/text-to-audio/893605946402811985" \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"task_id": "893605946402811985",
"task_status": "succeed",
"task_status_msg": "",
"task_info": {
"external_task_id": "your-id"
},
"task_result": {
"audios": [
{
"id": "893605946402811987",
"url_mp3": "https://example.com/result.mp3",
"url_wav": "https://example.com/result.wav",
"duration_mp3": "3.0",
"duration_wav": "3.0"
}
]
},
"created_at": 1722769557708,
"updated_at": 1722769600000
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
### 路径参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---- | ------ | -- | -- | -------------------------------------------- |
| `id` | string | 是 | - | 文生音效任务的 `task_id`，或创建时传入的 `external_task_id` |
## 响应
| 字段 | 类型 | 说明 |
| ------------------------------------------------------- | ------- | ------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.task_id` | string | 任务 ID |
| `data.task_status` | string | `submitted`、`processing`、`succeed`、`failed` |
| `data.task_status_msg` | string | 失败原因 |
| `data.task_info.external_task_id` | string | 自定义任务 ID |
| `data.task_result.audios[].id` | string | 音频 ID |
| `data.task_result.audios[].url_mp3` | string | MP3 地址，30 天后清理，请及时转存 |
| `data.task_result.audios[].url_wav` | string | WAV 地址 |
| `data.task_result.audios[].duration_mp3`、`duration_wav` | string | 音频时长，单位秒 |
| `data.created_at`、`data.updated_at` | integer | Unix 毫秒时间戳 |
## 计费
查询不收费。
## 错误
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | --------------------------------------- | ------- |
| 404 | `1203` | `task not found`：任务不存在、不属于当前账号或已超过 30 天 | 核对 `id` |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
# 文生音效任务列表
Source: https://looptoken.vibelab.me/docs/video/kling/text-to-audio-list
> GET /v1/audio/text-to-audio：分页列出文生音效任务
| 项 | 值 |
| -- | ----- |
| 模式 | 同步查询 |
| 计费 | 查询不收费 |
## 快速开始
```bash
curl "https://api.vibelab.me/v1/audio/text-to-audio?pageNum=1&pageSize=30" \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY"
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": [
{
"task_id": "893605946402811985",
"task_status": "succeed",
"task_status_msg": "",
"task_info": {
"external_task_id": "your-id"
},
"task_result": {
"audios": [
{
"id": "893605946402811987",
"url_mp3": "https://example.com/result.mp3",
"url_wav": "https://example.com/result.wav",
"duration_mp3": "3.0",
"duration_wav": "3.0"
}
]
},
"created_at": 1722769557708,
"updated_at": 1722769600000
}
]
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
### 查询参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ------- | -- | ---- | ---------- |
| `pageNum` | integer | 否 | `1` | 页码，1–1000 |
| `pageSize` | integer | 否 | `30` | 每页数量，1–500 |
## 响应
| 字段 | 类型 | 说明 |
| ------------ | ------- | -------------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data[]` | array | 任务列表，字段同[查询文生音效任务](/video/kling/text-to-audio-get) |
## 计费
查询不收费。
## 错误
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ------------------------------------ | ----------- |
| 400 | `1201` | `pageNum must be between 1 and 1000` | 页码传 1–1000 |
| 400 | `1201` | `pageSize must be between 1 and 500` | 每页数量传 1–500 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
# 文生视频
Source: https://looptoken.vibelab.me/docs/video/kling/text-to-video
> POST /text-to-video/{model}：可灵 3.0 / 3.0 Turbo 文生视频，异步，用 GET /tasks 查询
用提示词生成视频。
| 项 | 值 |
| -- | -------------------------------------------------------- |
| 模型 | `kling-3.0-turbo` / `kling-3.0` |
| 模式 | 异步（提交 → 轮询 `GET /tasks`，见[查询任务](/video/kling/get-tasks)） |
| 计费 | 按输出视频时长（秒）结算 |
## 快速开始
```bash
curl https://api.vibelab.me/text-to-video/kling-3.0-turbo \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "一只金色的猫咪在阳光下的草地上奔跑，慢动作，电影质感",
"settings": {
"resolution": "720p",
"duration": 5,
"aspect_ratio": "16:9"
}
}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"id": "893605946402811985",
"status": "submitted",
"create_time": 1781080778802,
"update_time": 1781080778802,
"external_id": "your-id"
}
}
```
## 请求参数
### 请求头
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | -- | --------------------------- |
| `Authorization` | string | 是 | - | `Bearer $LOOPTOKEN_API_KEY` |
| `Content-Type` | string | 是 | - | `application/json` |
### 路径参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ------ | -- | -- | ------------------------------------------------------------------- |
| `model` | string | 是 | - | `kling-3.0-turbo`（固定有声，720p/1080p）或 `kling-3.0`（720p/1080p/4k，声音可选） |
### 请求体
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------------------------- | ------- | -- | ------- | --------------------------------------------------------- |
| `prompt` | string | 是 | - | 提示词，不超过 3072 个字符 |
| `settings.resolution` | string | 否 | `720p` | `720p`、`1080p`；仅 `kling-3.0` 支持 `4k` |
| `settings.aspect_ratio` | string | 否 | `16:9` | `16:9`、`9:16`、`1:1` |
| `settings.duration` | integer | 否 | `5` | `3`–`15` 秒 |
| `settings.audio` | string | 否 | `off` | 仅 `kling-3.0`：`native` 或 `off`；`kling-3.0-turbo` 固定有声，不可传 |
| `settings.multi_shot` | boolean | 否 | `true` | 仅 `kling-3.0` |
| `options.callback_url` | string | 否 | - | 任务状态变化时的 HTTPS 回调地址，见[概览](/video/kling#回调) |
| `options.external_task_id` | string | 否 | - | 自定义任务 ID，同一账号下不可重复 |
| `options.watermark_info.enabled` | boolean | 否 | `false` | 是否同时生成含水印结果 |
## 响应
| 字段 | 类型 | 说明 |
| ------------------------------------- | ------- | --------------------------------------------- |
| `code` | integer | `0` 表示成功，其余见[错误](/video/kling#错误) |
| `message` | string | 错误信息 |
| `request_id` | string | 请求 ID，排查问题时提供 |
| `data.id` | string | 任务 ID |
| `data.status` | string | `submitted`、`processing`、`succeeded`、`failed` |
| `data.create_time`、`data.update_time` | integer | Unix 毫秒时间戳 |
| `data.external_id` | string | 创建时传入的 `options.external_task_id`，没传则无此字段 |
## 计费
按输出视频时长（秒）结算，价格以[定价页](/pricing)为准；任务失败全额退回。
## 错误
本页参数校验返回 `400 / 1201`，`message` 原文如下：
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | ---------------------------------------------------- | --------------------------------------------------------------------- |
| 404 | `1203` | `model not found`（路径 `{model}` 不是已上架的可灵模型） | 路径写 `kling-3.0-turbo` 或 `kling-3.0` |
| 400 | `1201` | `prompt is required and must be a string` | 传非空字符串 `prompt` |
| 400 | `1201` | `prompt must not exceed 3072 characters` | 缩短提示词 |
| 400 | `1201` | `settings must be an object` | `settings` 传对象 |
| 400 | `1201` | `settings.resolution "..." is not supported for ...` | `kling-3.0-turbo` 只支持 `720p`/`1080p`；`4k` 仅 `kling-3.0` |
| 400 | `1201` | `settings.duration must be an integer` | 传整数 |
| 400 | `1201` | `settings.duration must be between 3 and 15` | 传 `3`–`15` |
| 400 | `1201` | `settings.audio "..." is not supported for ...` | `kling-3.0` 只接受 `native`/`off`；`kling-3.0-turbo` 不能传 `settings.audio` |
| 400 | `1201` | `options must be an object` | `options` 传对象 |
通用错误（鉴权、余额、并发、回调地址、上游错误）见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **路径写 `kling-4.0`** → 按 4.0 规则校验，见 [Kling 4.0 视频生成](/video/kling/kling-4)。
* **多镜头** → 写在提示词里：`镜头 1, 3, 提示词; 镜头 2, 2, 提示词;`，最多 6 个分镜，分镜时长之和等于 `duration`。
# 音色管理
Source: https://looptoken.vibelab.me/docs/video/kling/voices
> /v1/general/*：创建、查询和删除 Kling 音色，以及查询官方音色库；创建异步，用 GET /v1/general/custom-voices/{id} 查询
创建可在 [Kling 4.0](/video/kling/kling-4) 全能参考中以 `voice` 素材引用的音色（`voice_id`），也可绑定到主体的 `element_voice_id`；并查询、删除自己的音色，查询官方音色库。属于[旧版风格](/video/kling#接口清单)（响应字段 `task_id` / `task_status`）。
| 项 | 值 |
| -- | ---------------------------------------------------------------- |
| 模型 | `kling-custom-voices` |
| 模式 | 创建为异步（提交 → 轮询 `GET /v1/general/custom-voices/{id}`）；列表、官方库、删除为同步 |
| 计费 | 创建按次计费，价格以[定价页](/pricing)为准；查询、列表和删除不向用户计费 |
## 快速开始
```bash
curl https://api.vibelab.me/v1/general/custom-voices \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"voice_name":"旁白","voice_url":"https://example.com/voice.mp3","external_task_id":"my-narrator"}'
```
响应示例：
```json
{
"code": 0,
"message": "SUCCEED",
"request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
"data": {
"task_id": "893605946402811985",
"task_status": "submitted",
"task_info": {
"external_task_id": "my-narrator"
},
"created_at": 1722769557708,
"updated_at": 1722769557708
}
}
```
`data.task_id` 是创建任务 ID，**不是音色 ID**。轮询见[响应](#响应)。
## 请求参数
### 创建音色请求体
认证为 `Authorization: Bearer $LOOPTOKEN_API_KEY`，`Content-Type: application/json`。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------ | ------ | -- | -- | ------------------------------------------------------------ |
| `voice_name` | string | 是 | - | 不超过 20 个字符 |
| `voice_url` | string | 是 | - | 音视频地址，支持 MP3/WAV/MP4/MOV，要求干净单人声、5–30 秒；不支持上游历史作品 `video_id` |
| `callback_url` | string | 否 | - | 任务状态变化时的 HTTPS 回调地址（顶层字段），见[回调](/video/kling#回调) |
| `external_task_id` | string | 否 | - | 自定义任务 ID，当前用户范围内唯一（顶层字段） |
### 其他接口参数
| 接口 | 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------------------------------------ | ---------- | ------- | -- | ---- | ----------------- |
| `GET .../custom-voices/{id}` | `id`（路径） | string | 是 | - | 创建任务 ID 或自定义任务 ID |
| `GET .../custom-voices`、`GET .../presets-voices` | `pageNum` | integer | 否 | `1` | `1`–`1000` |
| 同上 | `pageSize` | integer | 否 | `30` | `1`–`1000` |
| `POST .../delete-voices` | `voice_id` | string | 是 | - | 要删除的音色 ID |
## 响应
轮询单个查询，`data.task_status` 为 `submitted`、`processing`、`succeed`（终态）、`failed`（终态）。
| 字段 | 类型 | 说明 |
| -------------------------------------- | ------ | --------- |
| `data.task_id` | string | 创建任务 ID |
| `data.task_status` | string | 任务状态 |
| `data.task_info.external_task_id` | string | 自定义任务 ID |
| `data.task_result.voices[].voice_id` | string | 成功后的音色 ID |
| `data.task_result.voices[].voice_name` | string | 音色名称 |
| `data.task_result.voices[].trial_url` | string | 试听地址 |
* 自定义音色列表只返回当前用户的创建任务记录，不受 30 天限制；官方列表实时查询上游。
* 首次引用预置音色前，须查询包含该 ID 的官方列表页。
* 删除成功后 LoopToken 停止允许引用该音色，原创建任务保留历史快照。
* 不返回上游成本字段。
## 计费
创建时预扣一次，失败任务退款；查询、列表和删除不收费。
## 错误
| HTTP | `code` | 触发场景 | 处理 |
| ---- | ------ | -------------------------------------------------------------------------------------------- | --------------------------- |
| 400 | `1201` | `voice_name is required and must be a string` / `voice_url is required and must be a string` | 补齐必填字段 |
| 400 | `1201` | `voice_name must not exceed 20 characters` | 缩短名称 |
| 400 | `1201` | `video_id is not supported, use voice_url` | 改传 `voice_url` |
| 400 | `1201` | `invalid pageNum` / `invalid pageSize`（列表） | 页码 `1`–`1000`，每页 `1`–`1000` |
| 400 | `1201` | `invalid JSON body` / `asset ID is required`（删除） | 请求体传 `{"voice_id":"..."}` |
| 404 | `1203` | `asset not found`（删除）：不是自己创建的音色，或渠道不可用 | 官方音色不能删除，核对 `voice_id` |
| 404 | `1203` | `task not found`（查询） | 核对任务 ID |
通用错误见 [Kling 错误](/video/kling#错误)。
## 注意事项
* **引用音色** → 通过 Omni 的 `voice` 素材或主体的 `element_voice_id` 引用，只能引用自己创建的音色，或已通过官方列表核实的预置音色。
* **删除** → 只能删除自己的定制音色。
* **渠道绑定** → 音色与主体都绑定到原上游渠道账号，不能跨渠道账号引用。