WanAPIs 开发者文档
快速接入 WanAPIs
使用一个 OpenAI 兼容 API Key 调用 GPT、Claude、Gemini、DeepSeek、图像、视频和语音模型。现有项目通常只需要替换 base_url 和 API Key。
介绍
WanAPIs 是统一 AI API 网关，提供 OpenAI 兼容接口、多渠道路由、失败转移、模型市场、调用日志和透明计费。你可以把不同上游的模型统一放在一个 endpoint 下管理。
兼容 OpenAI
支持常用 SDK、Chat Completions、Responses 和工具调用。
统一模型市场
在一个页面查看模型能力、供应商、价格和调用入口。
生产级稳定性
通过多渠道、分组、重试和日志降低上游波动影响。
快速开始
- 注册账号进入控制台创建账号并完成邮箱验证。
- 创建 API Key在令牌页面生成密钥，并按项目设置额度。
- 替换 Base URL把 OpenAI SDK 的 baseURL 改成 https://api.wanapis.com/v1。
- 选择模型从模型市场或定价页选择模型 ID。
cURL
curl https://api.wanapis.com/v1/chat/completions \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-pro",
"messages": [
{ "role": "user", "content": "用三句话解释 RAG" }
]
}'认证
所有请求都需要在 Header 中携带 Bearer Token。不要把 API Key 放在前端浏览器代码里，建议通过你的后端服务转发请求。
| 项目 | 说明 | 示例 |
|---|---|---|
| Base URL | OpenAI 兼容 API 根地址 | https://api.wanapis.com/v1 |
| Header | 请求认证方式 | Authorization: Bearer sk-... |
| Content-Type | JSON 请求体 | application/json |
密钥管理
推荐按项目创建不同 API Key，设置额度上限。上线后通过日志页观察模型、分组、耗时和扣费。
Chat Completions
兼容 /v1/chat/completions，适合多数现有 OpenAI SDK、聊天机器人、Agent 和工具调用项目。
Node.js
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.WANAPIS_API_KEY,
baseURL: "https://api.wanapis.com/v1",
});
const response = await client.chat.completions.create({
model: "deepseek-v4-pro",
messages: [{ role: "user", content: "写一个 TypeScript 重试函数" }],
});
console.log(response.choices[0].message.content);Python
from openai import OpenAI
client = OpenAI(
api_key=os.environ["WANAPIS_API_KEY"],
base_url="https://api.wanapis.com/v1",
)
response = client.chat.completions.create(
model="gemini-3.5-flash",
messages=[{"role": "user", "content": "给我一个产品发布清单"}],
)
print(response.choices[0].message.content)Responses API
需要使用新一代 Responses 工作流时，可以调用 /v1/responses。如果遇到上游 503 或高负载，建议在业务侧增加指数退避重试。
Responses
curl https://api.wanapis.com/v1/responses \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": "分析这段日志并给出排障步骤"
}'模型市场
模型市场会从 WanAPIs 定价接口同步数据，按视频、图像、LLM、音频分类展示能力、供应商和价格。
客户端 / IDE 集成
这是重点内容。所有支持自定义 base_url 的 OpenAI / Anthropic 兼容客户端都可以接入 WanAPIs。推荐先把本机配置跑通，再接 VS Code 插件: Claude Code → CC Switch → Codex Desktop → Codex CLI → VS Code。
Claude Code 接入教程 →Codex 接入教程 →Cursor 接入教程 →ccswitch 一键切换 →Cline 接入教程 →Roo Code 接入教程 →Continue 接入教程 →Aider 接入教程 →Cherry Studio 接入教程 →Chatbox 接入教程 →
1. Claude Code（推荐）
Anthropic 官方 CLI agent。配 WanAPIs 后可使用 claude-opus-4-7、claude-sonnet-4-6 等 Claude 系列模型。
Claude Code
# 1. 安装，需要 Node.js >= 18
npm i -g @anthropic-ai/claude-code
# 2. 配环境变量，建议写入 ~/.zshrc 或 ~/.bashrc
export ANTHROPIC_BASE_URL="https://api.wanapis.com"
export ANTHROPIC_AUTH_TOKEN="sk-xxx"
# 3. 在项目目录启动
cd your-project && claude首次进入会让你选择模型。确认安装可运行 claude --version。
2. CC Switch（桌面 GUI 切换器）
CC Switch 可以统一管理 Claude Code / Codex / Gemini CLI 等 agent 的 provider，一键切换 base_url 和 token。
CC Switch 配置示意
入口codex / claude 分组 -> 右上角 +
NameWanAPIs
Base URLhttps://api.wanapis.com
API Keysk-xxx
启用保存后点击启用 / Switch to
CC Switch
# 从 GitHub Releases 下载:
# https://github.com/farion1231/cc-switch/releases
# 1. 打开 CC Switch
# 2. 进入 codex 或 claude 分组
# 3. 点击右侧 + 添加 WanAPIs
# 4. 保存后点击启用 / Switch to
# 5. 重启 Codex、VS Code 或 Claude Code一键导入(装了 CC Switch 就能用)
点下面按钮直接导入 WanAPIs 预设(不含密钥),导入后在 CC Switch 里粘贴你的 API Key 即可。
保存后请重启 Codex、VS Code 或 Claude Code，避免旧配置继续驻留在进程环境中。
3. Codex 桌面端（macOS / Windows）
OpenAI 官方 Codex 桌面应用。桌面端、CLI 和 IDE 扩展共用 ~/.codex/config.toml；Windows 原生路径是 %USERPROFILE%\.codex\config.toml。
Codex Desktop 配置项
认证方式API Key
配置文件~/.codex/config.toml
Windows%USERPROFILE%\.codex\config.toml
Providermodel_provider = "wanapis"
Base URLhttps://api.wanapis.com/v1
Wire APIresponses
~/.codex/config.toml
model = "gpt-5.5"
model_provider = "wanapis"
[model_providers.wanapis]
name = "WanAPIs"
base_url = "https://api.wanapis.com/v1"
wire_api = "responses"
env_key = "WANAPIS_API_KEY"环境变量
# macOS / Linux，写入 ~/.zshrc 或 ~/.bashrc 后重开终端
export WANAPIS_API_KEY="sk-xxx"
# Windows PowerShell，持久写入当前用户环境变量
[Environment]::SetEnvironmentVariable("WANAPIS_API_KEY", "sk-xxx", "User")- 1. 安装并打开 Codex 桌面端，在认证方式里选择 API Key，不使用 ChatGPT 账号登录模式。
- 2. 创建上面的 config.toml 文件，把模型和 provider 指向 WanAPIs。
- 3. 设置 WANAPIS_API_KEY 后重启 Codex 桌面端；如果同时使用 VS Code/Cursor，也一起重启。
- 4. Windows 原生 Codex 和 WSL Codex 不共用同一个 home；WSL 里需要单独写 ~/.codex/config.toml，或设置 CODEX_HOME 指向同一目录。
模型选择
推荐代码任务优先用 gpt-5.5 或 claude-sonnet-4.7。如果某个模型不支持 Responses 格式或工具调用，先在模型市场换一个支持工具调用的模型验证。
4. Codex CLI
OpenAI 官方代码 agent。推荐使用 responses wire API，并把 provider 写入 ~/.codex/config.toml。
Codex CLI
# 1. 安装
npm i -g @openai/codex
# 2. 编辑 ~/.codex/config.toml
cat > ~/.codex/config.toml <<'EOF'
model = "gpt-5.5"
model_provider = "wanapis"
[model_providers.wanapis]
name = "WanAPIs"
base_url = "https://api.wanapis.com/v1"
wire_api = "responses"
env_key = "WANAPIS_API_KEY"
EOF
# 3. 设置 token
export WANAPIS_API_KEY="sk-xxx"
# 4. 在项目目录启动；它会读取同一个 ~/.codex/config.toml
cd your-project && codex5. VS Code 插件
分两类:官方 Codex / Claude Code 插件通常复用本机 CLI 配置;Cline、Continue、Roo Code 等第三方插件直接在插件设置里填 URL、Key 和模型。
官方 Codex 插件（openai.chatgpt）
在 VS Code 扩展市场安装 openai.chatgpt 这个插件不在聊天框里填 Base URL；先把 ~/.codex/config.toml 配好，然后重启 VS Code。官方 Codex 扩展会复用本机 Codex 配置中的 model 和 provider 设置。
官方 Codex 插件配置路径
安装入口VS Code -> openai.chatgpt
配置文件~/.codex/config.toml
base_urlhttps://api.wanapis.com/v1
env_keyWANAPIS_API_KEY
生效方式保存配置后重启 VS Code
~/.codex/config.toml
model = "gpt-5.5"
model_provider = "wanapis"
[model_providers.wanapis]
name = "WanAPIs"
base_url = "https://api.wanapis.com/v1"
wire_api = "responses"
env_key = "WANAPIS_API_KEY"Claude Code VS Code 插件
在 VS Code 扩展市场安装 Claude Code 核心不是在插件里单独填 URL，而是先确认终端里的 claude 已经能正常连接 WanAPIs；插件会复用本机 ~/.claude 配置。改完配置后重启 VS Code。
Claude Code 插件检查项
CLI 验证终端运行 claude 能正常对话
环境变量ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN
配置目录~/.claude/settings.json / config.json
常见动作修改配置后重启 VS Code
Cline（原 Claude Dev，推荐）
打开 Cline 侧边栏，点击设置齿轮，Provider 选择 OpenAI Compatible 然后填写 Base URL、API Key 和 Model ID。
Cline 设置面板
API ProviderOpenAI Compatible
Base URLhttps://api.wanapis.com/v1
API Keysk-xxx
Model IDclaude-opus-4-7
验证点击 Verify 或发起一次对话
Cline settings
API Provider: OpenAI Compatible
Base URL: https://api.wanapis.com/v1
API Key: sk-xxx
Model: claude-opus-4-7
# 也可以使用 gpt-5.5 / gemini-3.5-flash / deepseek-v4-proContinue
Continue 当前推荐使用 YAML 配置。打开 Continue 设置里的配置文件，给 models 增加一个 provider: openai 模型，并通过 apiBase 指向 WanAPIs。
~/.continue/config.yaml
name: WanAPIs
version: 0.0.1
schema: v1
models:
- name: WanAPIs Claude Opus 4.7
provider: openai
model: claude-opus-4-7
apiBase: https://api.wanapis.com/v1
apiKey: sk-xxx
roles:
- chat
- edit
- applyRoo Code
打开 Roo Code 侧边栏设置，API Provider 选择 OpenAI Compatible Roo Code 官方文档说明这里需要填 Base URL、API Key 和 Model ID；如果模型不支持工具调用，需要换成支持 tool calling 的模型。
Roo Code 设置面板
API ProviderOpenAI Compatible
Base URLhttps://api.wanapis.com/v1
API Keysk-xxx
Modelgpt-5.5 / claude-opus-4-7
注意优先选择支持工具调用的模型
6. 桌面客户端 / 浏览器扩展
通用配置：Provider 选 OpenAI 兼容 Base URL 填 https://api.wanapis.com/v1，API Key 填 sk-xxx。
- CherryStudio：中文圈常用桌面 LLM 客户端，适合多 provider 切换。
- ChatBox：跨平台桌面客户端，设置简单。
- NextChat / ChatGPT-Next-Web：Web / 桌面双形态，支持自部署。
- LobeChat：Web 客户端，支持插件生态。
- Page Assist / Sider：浏览器扩展侧边栏 LLM。
异步任务
图片、视频和其它长耗时任务建议走异步任务接口或控制台任务能力，避免公网入口超时。任务创建后通过任务 ID 轮询状态，或配置回调地址接收结果。
提交图片任务
POST /v1/images/gpt-image-2/generation
# 模型名放在 URL 路径;body 与同步接口一致
# {"prompt": "...", "size": "1024x1024", "image_urls": [...]}
# 立即返回: {"data":[{"status":"submitted","task_id":"task_xxx"}]}提交视频任务
POST /v1/video/generations
# 模型名放在请求体的 model 字段(OpenAI 兼容)
# {"model": "seedance-2.0", ...}查询任务 / 下载结果
# 图片任务:轮询通用任务接口
GET /v1/tasks/{task_id}
# status: submitted | processing | completed | failed
# 完成后图片在 data.result.image_urls(数组,可能是 data URL/base64)
# 视频任务:改用视频专用接口
GET /v1/video/generations/{task_id} # 地址在 metadata.url长任务建议
视频生成、图片编辑、Midjourney 类任务通常耗时较长。业务侧应保存 task id，并为 pending、running、failed、completed 状态分别处理。
图片生成
图片生成走 OpenAI 兼容的同步入口 POST /v1/images/generations，模型名放在请求体 model 字段。gpt-image-2 用 prompt 出图,加 image_urls 即变图生图(图像编辑)。响应同步返回,图片在 data[0].b64_json(base64 PNG)。
同步 vs 异步官方版
上面的 gpt-image-2 是同步入口,直接返 base64,但总分辨率固定约 1.5MP。要真正的 1K / 2K / 4K 高清、更多比例、以及不怕超时的异步任务,用官方渠道模型 gpt-image-2-official —— 见本节末尾「官方版 · 异步高清」。
gpt-image-2
通用图片模型，文生图 + 图生图(图像编辑),参考图最多 16 张。
flux / imagen / seedream
其它图片模型请以模型市场实际显示为准。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 固定 gpt-image-2。 |
| prompt | string | 是 | 图片描述或改写指令,中英文均可。 |
| image_urls | string[] | 否 | 图生图/图像编辑的参考图:公网 URL 或 base64 data URL(可混用),最多 16 张。 |
| size | string | 否 | 像素格式 WxH 只决定画面比例(如 1024x1024 方图、1536x1024 横图);比例字符串如 16:9 不认。输出总分辨率固定约 1.5MP(约 1254×1254),更大尺寸 / 4k 不会得到更多像素。 |
| n | integer | 否 | 生成张数,默认 1。 |
文生图(Text-to-image)
curl https://api.wanapis.com/v1/images/generations \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "一只橘猫坐在窗台上看夕阳，水彩画风格",
"size": "1024x1024"
}'图生图(图像编辑):同一入口,加上 image_urls 传参考图(公网 URL 或 data:image/png;base64,... 内联图,可多张),prompt 作为改写指令。
图生图 / 图像编辑(Image-to-image)
curl https://api.wanapis.com/v1/images/generations \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "把这张图改成夜景霓虹赛博朋克风格，保留猫的主体",
"image_urls": [
"https://example.com/cat.png"
]
}'响应(同步返回)
{
"created": 1783144062,
"data": [
{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...<base64 PNG>" }
]
}实测要点
① 图片以 base64 返回在 data[0].b64_json,base64 解码即得 PNG。② 单张约 40–60 秒,接近 Cloudflare 100 秒上限;更慢/更大的任务建议走异步任务入口避免超时(见「异步任务」)。③ size 用像素格式(如 1536x1024)才生效,比例格式(16:9)当前会被忽略。
Seedream(即梦)
字节 Seedream 系列，写实质感与提示词遵循度都很强。在售四个:seedream-5-0-pro(最强，支持 1K/2K 两档分辨率)、seedream-5-0-lite、seedream-4-5、seedream-4-0。
| 项目 | 说明 | 示例 |
|---|---|---|
| model | 四选一。只有 seedream-5-0-pro 有分辨率分档，其余单一价格。 | seedream-5-0-pro |
| prompt | 必填。图像描述。 | string |
| size | 画面比例。1:1 / 16:9 / 9:16 / 4:3 / 3:4 等。 | 1:1 |
| resolution | 输出分辨率。seedream-5-0-pro 支持 1K / 2K，价格随档位变化。 | 2K |
| image_urls | 图生图参考图数组。 | ["https://...jpg"] |
Nano Banana(香蕉)
Google Gemini 图像模型的通称。语义理解和角色一致性强，文字渲染也好。在售 nano-banana-pro(即 Gemini 3 Pro Image，支持 1K/2K/4K)与 nano-banana-2(即 Gemini 3.1 Flash Image)。
| 项目 | 说明 | 示例 |
|---|---|---|
| model | nano-banana-pro(质量优先) 或 nano-banana-2(速度与价格优先)。 | nano-banana-pro |
| prompt | 必填。最长约 1000 字符。 | string |
| size | 画面比例。auto / 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 21:9 等。 | auto |
| resolution | 输出分辨率。nano-banana-pro 支持 1K / 2K / 4K,4K 单价更高。 | 1K |
| image_urls | 图生图参考图，最多 14 张，支持 URL 或 base64。 | ["https://...jpg"] |
| n | 生成数量。当前仅支持 1。 | 1 |
Midjourney
Midjourney 走**异步任务**接口:提交 POST /v1/images/tasks 拿到 task_id，再轮询 GET /v1/images/tasks/{task_id}。一次生成返回 4 张图(MJ 的 2×2 四宫格会拆成 4 个 URL)。
不要走同步图片接口
Midjourney 只有异步接口。误用同步的 /v1/images/generations 会被直接拒绝并提示改用异步接口——这是有意为之:那条路会拿到任务信封而不是图片，却照常扣费。
| 项目 | 说明 | 示例 |
|---|---|---|
| model | 固定填 midjourney。 | midjourney |
| prompt | 必填。支持 MJ 原生参数后缀，如 --ar 16:9(比例)、--q .25(低画质省钱)、--niji(动漫风)。 | --ar 16:9 --q .25 |
| image_urls | 图生图参考图。也可直接把图片 URL 写在 prompt 开头(MJ 原生写法)。 | ["https://...jpg"] |
| speed | 速度模式。relax / fast / turbo，默认 relax。 | relax |
| version | 模型版本。如 v8.2 / v8.1 / v7 / v6.1。 | v8.2 |
文生图
curl https://api.wanapis.com/v1/images/tasks \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "midjourney",
"prompt": "a small red apple on a white table --ar 1:1 --q .25"
}'图生图
curl https://api.wanapis.com/v1/images/tasks \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "midjourney",
"prompt": "turn this into watercolor style --ar 1:1",
"image_urls": ["https://example.com/source.jpg"]
}'GPT Image 2 官方版 · 异步高清
gpt-image-2-official 是 OpenAI 官方渠道的 GPT Image 2,支持 1K / 2K / 4K 分辨率档、15 种比例、单次最多 4 张、参考图最多 16 张。它是异步任务:提交 POST /v1/images/tasks 立即返回 task_id,再轮询 GET /v1/images/tasks/{task_id} 获取结果。
提交与轮询路径
提交 POST /v1/images/tasks,模型名放请求体 model 字段。轮询 GET /v1/images/tasks/{task_id};状态到 SUCCESS 后,图片 URL 在响应的 data.data.data.result.images[].url[] 里(url 是数组)。⚠️ 图片 URL 约 24 小时后过期,请及时下载保存。
| 项目 | 说明 | 示例 |
|---|---|---|
| model | 固定 gpt-image-2-official。 | gpt-image-2-official |
| prompt | 图片描述或改写指令,中英文均可(必填)。 | "星空下的城堡" |
| size | 比例(不是像素!)。支持 15 种,如 1:1 / 16:9 / 9:16 / 4:3 / 3:4。 | 16:9 |
| resolution | 分辨率档 1k / 2k / 4k。不传时上游按最低档处理。 | 2k |
| quality | 质量 low / medium / high,不传默认 low。和 resolution 一起决定价格(见下),质量越高越贵。 | low |
| n | 生成张数,1–4,默认 1。 | 1 |
| image_urls | 图生图/编辑的参考图:公网 URL 或 base64 data URL,最多 16 张。 | ["https://...png"] |
提交(文生图)
curl https://api.wanapis.com/v1/images/tasks \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-official",
"prompt": "星空下的古老城堡，电影感",
"size": "16:9",
"resolution": "2k",
"quality": "low"
}'轮询任务
curl https://api.wanapis.com/v1/images/tasks/task_xxxxxxxxxxxxxxxxxxxxxxxxxx \
-H "Authorization: Bearer $WANAPIS_API_KEY"completed result
{
"code": "success",
"data": {
"task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"status": "SUCCESS",
"progress": "100%",
"data": {
"code": 200,
"data": {
"status": "completed",
"result": {
"images": [
{
"url": ["https://.../image.png"],
"expires_at": 1784819826
}
]
}
}
}
}
}计费与要点
按 质量 × 分辨率 计费,价差很大:低质低分(low / 1k)最便宜,高质 4K(high / 4k)最贵——精确价格以模型市场为准。状态为 SUBMITTED / IN_PROGRESS 时每 3 到 5 秒轮询一次,通常 20 到 60 秒完成。图生图请在请求体加 image_urls(公网 HTTPS 图 URL,便于上游拉取)。
视频生成
视频生成统一归到视频能力目录下。模型配置方法放在本目录下，例如 Seedance 2.5/2.0、Veo 3.1、Kling、Vidu Q3、HappyHorse 等。所有视频模型默认使用异步任务模式：提交 POST /v1/video/generations(模型名放请求体 model 字段)，再轮询任务结果。
Seedance 2.0
字节豆包视频生成，支持文生视频、图生视频、首尾帧和参考素材。
Veo 3.1
Google，4K/60fps 与单次生成同步音频，画面最精致。quality / fast / lite 三档。
Kling
快手，人物动作最自然。v3 与 v2-6 两代，支持 pro / sound 等档位。
Vidu Q3
生数科技，性价比高，含 pro / turbo / mix 变体。
HappyHorse 1.0
阿里 ATH，2026-04 发布，综合榜排名靠前。
Grok Video
xAI，固定 6 秒短视频，单价最低。
全部视频模型与参数
下表列出当前在售的视频模型。所有模型都走同一个异步接口 POST /v1/video/generations，差别只在模型名和支持的参数档位。价格以模型广场显示为准(按秒计费的模型会显示各分辨率的每秒价)。
| 项目 | 说明 | 示例 |
|---|---|---|
| seedance-2.5 | 字节豆包最新一代。480p / 720p / 1080p，时长 4~15 秒，画质与一致性最好。 | 按秒 |
| seedance-2.0 | 标准版，质量优先。480p / 720p / 1080p，时长 4~15 秒。 | 按秒 |
| seedance-2.0-fast | 速度版，适合草稿与批量预览。 | 按秒 |
| seedance-2.0-mini | 轻量版，价格最低，适合大批量试稿。 | 按秒 |
| veo3.1-quality | Google Veo 3.1 高质量档，支持 4K 与同步音频。 | 按次 |
| veo3.1-fast | Veo 3.1 速度档。 | 按次 |
| veo3.1-lite | Veo 3.1 轻量档，价格最低。 | 按次 |
| kling-v3 | 快手可灵 v3，人物动作自然，支持 pro / sound / 4k 档位。 | 按秒 |
| kling-v2-6 | 可灵 2.6，性价比档。 | 按秒 |
| viduq3 | 生数 Vidu Q3，另有 pro / turbo / mix 变体。540p / 720p / 1080p。 | 按秒 |
| happyhorse-1.0 | 阿里 ATH，2026-04 发布。720p / 1080p。 | 按秒 |
| grok-video | xAI Grok，固定 6 秒短视频，单价最低。 | 按秒 |
参数写法有两种，建议都带上
不同上游对参数位置的要求不一样:一部分读顶层的 resolution 和 duration，另一部分读 metadata.resolution 和顶层 seconds。同一个模型可能由多个上游供给，所以最稳妥的做法是两套都写上——多余的字段会被忽略，不会报错。不传时默认 720p、5 秒。
Kling(可灵)
快手可灵，人物动作与肢体连贯性最好。注意它的参数体系和 Seedance 不同:清晰度用 mode(不是 resolution)，比例用 aspect_ratio(不是 size)。
| 项目 | 说明 | 示例 |
|---|---|---|
| model | kling-v3 或 kling-v2-6。 | kling-v3 |
| prompt | 必填。视频提示词。 | string |
| negative_prompt | 反向提示词，排除不想要的元素。 | string |
| mode | 画质档位。std 标准 / pro 高质 / 4k 超清。价格随档位上升。 | std |
| duration | 时长(秒)，3~15，默认 5。 | 5 |
| aspect_ratio | 画面比例。16:9 / 9:16 / 1:1，默认 16:9。 | 16:9 |
| image_urls | 图生视频参考图数组。 | ["https://...jpg"] |
| audio | 是否生成同步音频，默认 false。 | false |
| multi_shot | 多镜头模式，配合 shot_type 与 multi_prompt 使用。 | false |
| watermark | 是否加水印。 | false |
文生视频
curl https://api.wanapis.com/v1/video/generations \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3",
"prompt": "a cat walking through a neon-lit alley, cinematic",
"mode": "pro",
"duration": 5,
"aspect_ratio": "16:9"
}'Veo 3.1
Google Veo 3.1，支持 4K 与单次生成同步音频，画面最精致。三个档位对应三个模型名:veo3.1-quality / veo3.1-fast / veo3.1-lite。这三个是按次计费(不按秒)，所以时长参数不影响单价。
| 项目 | 说明 | 示例 |
|---|---|---|
| model | veo3.1-quality(质量优先) / veo3.1-fast(速度) / veo3.1-lite(最低价)。 | veo3.1-fast |
| prompt | 必填。视频提示词。 | string |
| resolution | 输出清晰度。720p / 1080p / 4k，价格随之上升。 | 1080p |
| duration | 时长(秒)。按次计费，时长不改变单价。 | 5 |
| image_urls | 图生视频参考图数组。 | ["https://...jpg"] |
Vidu Q3 / HappyHorse / Grok Video
| 项目 | 说明 | 示例 |
|---|---|---|
| viduq3 | 生数科技。分辨率 540p / 720p / 1080p，另有 viduq3-pro(更高质量)、viduq3-turbo(更便宜)、viduq3-mix 变体。 | 按秒 |
| happyhorse-1.0 | 阿里 ATH，2026-04 发布。支持 720p / 1080p。 | 按秒 |
| grok-video | xAI。固定 6 秒，无时长参数，单价最低。 | 按秒 |
任务状态与结果
所有视频模型共用同一套任务状态机。提交后立即拿到 task_id，随后轮询直到终态。
| 项目 | 说明 | 示例 |
|---|---|---|
| status | pending 排队 / processing 生成中 / completed 完成 / failed 失败 / cancelled 已取消。只有 completed 才有 result。 | completed |
| progress | 进度百分比 0~100。 | 100 |
| result.videos[].url | 视频地址数组。注意是**数组**，取第一个元素。 | ["https://...mp4"] |
| result.videos[].expires_at | 链接过期时间戳。约 24 小时后失效，需要长期保存请自行转存。 | 1763174708 |
| estimated_time | 预计耗时(秒)，提交后即可用于展示进度。 | 60 |
| actual_time | 实际耗时(秒)，仅完成后存在。 | 19 |
| error | 失败时存在，含 code / message / type。 | object |
视频链接约 24 小时过期
完成结果里的视频地址由上游托管，expires_at 之后失效。需要长期保留请在拿到结果后立即转存到自己的存储。
Seedance 2.0
Seedance 2.0 是字节豆包视频生成模型，适合文生视频、图生视频、首尾帧过渡和参考素材驱动的视频任务。WanAPIs 使用异步任务接口封装长耗时调用：提交任务立即返回 task_id 立即返回，再轮询 /v1/video/generations/{task_id} 获取结果。
提交路径(OpenAI 兼容)
WanAPIs 视频提交入口是 POST /v1/video/generations(单数 video)，模型名放在请求体的 model 字段，不放在 URL。轮询 GET /v1/video/generations/{task_id}；完成后视频可经 GET /v1/videos/{task_id}/content 下载。
请求参数约定(重要)
清晰度、比例、首尾帧/参考素材等参数放在 metadata 对象里(resolution / ratio / content / generate_audio)，时长用顶层 seconds(字符串，如 "5")，简单图生视频可直接用顶层 images 传参考图。把 resolution 写在顶层会被忽略，导致按默认 720p 出图。首尾帧用 metadata.content 数组，每项带 role(first_frame / last_frame / reference_image)。
seedance-2.5
最新一代，画质与一致性最好，按秒计费中价格最高。
seedance-2.0
标准版，画面质量优先，适合正式素材生成。
seedance-2.0-fast
速度版，适合草稿、批量预览和低延迟场景。
seedance-2.0-mini
轻量版，价格最低，适合大批量试稿。
文生视频
curl https://api.wanapis.com/v1/video/generations \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0",
"prompt": "一只橘猫在清晨的窗边伸懒腰,镜头缓慢推进,柔和自然光,电影感",
"seconds": "5",
"metadata": {
"resolution": "720p",
"ratio": "16:9",
"generate_audio": true
}
}'图生视频
curl https://api.wanapis.com/v1/video/generations \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0-fast",
"prompt": "让照片中的人物自然转身看向镜头,微风吹动头发,背景保持一致",
"images": ["https://example.com/portrait.jpg"],
"seconds": "5",
"metadata": {
"resolution": "720p",
"ratio": "adaptive"
}
}'首尾帧过渡
curl https://api.wanapis.com/v1/video/generations \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0",
"prompt": "从白天城市街景平滑过渡到夜晚霓虹灯街景,镜头向前移动",
"seconds": "5",
"metadata": {
"resolution": "720p",
"ratio": "16:9",
"content": [
{"type": "image_url", "role": "first_frame", "image_url": {"url": "https://example.com/day.jpg"}},
{"type": "image_url", "role": "last_frame", "image_url": {"url": "https://example.com/night.jpg"}}
]
}
}'| 项目 | 说明 | 示例 |
|---|---|---|
| prompt | 视频生成提示词。写清主体、动作、场景、镜头、风格和限制条件。 | "电影感推镜" |
| seconds | 视频时长(秒),顶层字段,字符串。常用 "5" / "10",具体上限以模型实际返回为准。 | "5" |
| images | 图生视频参考图(顶层数组)。通常传 1 张;不带角色时默认作首帧/参考图。 | ["https://...jpg"] |
| metadata.resolution | 输出清晰度,放在 metadata 里。480p / 720p / 1080p,具体以模型市场和上游返回为准。 | 720p |
| metadata.ratio | 视频比例(metadata)。常用 16:9、9:16、1:1;图生视频也可用 adaptive。 | 16:9 |
| metadata.content | 首尾帧/参考素材数组(metadata),每项 type=image_url 并带 role:first_frame / last_frame / reference_image。 | first_frame |
| metadata.generate_audio | 是否生成同步音频(metadata)。开启后耗时可能更长。 | true |
| metadata.return_last_frame | 是否返回末帧(metadata),方便做连续镜头或下一段视频的首帧。 | true |
提交响应
response
{
"id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"object": "video",
"model": "seedance-2.0",
"status": "queued",
"progress": 0,
"created_at": 1780000000
}轮询任务
poll
curl https://api.wanapis.com/v1/video/generations/task_xxxxxxxxxxxxxxxxxxxxxxxxxx \
-H "Authorization: Bearer $WANAPIS_API_KEY"completed result
{
"id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"object": "video",
"model": "seedance-2.0",
"status": "completed",
"progress": 100,
"created_at": 1780000000,
"completed_at": 1780000180,
"metadata": {
"url": "https://api.wanapis.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxx/content"
},
"error": null
}生产建议
任务状态为 queued 或 in_progress 时每 5 到 10 秒轮询一次即可；遇到 failed 时记录 task id、模型名和错误信息。图生视频请使用公网可访问的 HTTPS 图片 URL，避免上游无法拉取素材。
音乐生成
音乐生成基于 Suno 模型,采用异步任务模式:提交 POST /v1/music/generations 立即返回 task_id,再轮询 GET /v1/music/tasks/{task_id} 获取结果。每次生成返回 2 首候选,含可直接播放的音频、封面图与歌词。
提交与轮询路径
提交 POST /v1/music/generations,模型名放请求体 model 字段(当前为 suno)。轮询 GET /v1/music/tasks/{task_id};状态到 SUCCESS 后,歌曲位于响应的 data.data.data.result.music[] 数组里,每首带 audio_url(可直接播放/下载的 mp3)、封面与歌词。
两种模式
灵感模式 custom: false:只给一句 prompt 描述,模型自动写词编曲。自定义模式 custom: true:用 prompt 作为歌词、style 指定风格、title 指定标题。两种模式都可加 instrumental: true 生成纯器乐。
灵感模式(一句话)
curl https://api.wanapis.com/v1/music/generations \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno",
"custom": false,
"version": "v5",
"prompt": "深夜城市 lo-fi 钢琴与雨声"
}'自定义模式(歌词+风格)
curl https://api.wanapis.com/v1/music/generations \
-H "Authorization: Bearer $WANAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno",
"custom": true,
"version": "v5",
"title": "City Lights",
"style": "lo-fi, chill, piano",
"prompt": "[Verse]\nNeon rain on empty streets\n[Chorus]\nCity lights ...",
"instrumental": false
}'| 项目 | 说明 | 示例 |
|---|---|---|
| model | 音乐模型名,当前为 suno。 | suno |
| version | Suno 版本(必填)。v3.5 / v4 / v4.5 / v4.5+ / v5 / v5.5,越新质量越高。 | v5 |
| custom | 模式开关。false=灵感模式(只给 prompt);true=自定义模式(歌词+风格)。 | false |
| prompt | 灵感模式=音乐描述;自定义模式=歌词。纯器乐(instrumental=true)时可留空。 | "深夜 lo-fi 钢琴" |
| instrumental | 是否纯器乐(无人声),两种模式都可用。 | true |
| title | 歌曲标题(仅自定义模式)。 | "City Lights" |
| style | 风格/标签(仅自定义模式),如 lo-fi, chill, piano。 | "lo-fi, chill" |
| vocal_gender | 人声性别偏好(可选)。male / female。 | female |
| negative_tags | 负面风格标签,排除不想要的风格(仅自定义模式)。 | "heavy metal" |
提交响应
response
{
"code": "success",
"data": {
"task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"status": "submitted"
}
}轮询任务
poll
curl https://api.wanapis.com/v1/music/tasks/task_xxxxxxxxxxxxxxxxxxxxxxxxxx \
-H "Authorization: Bearer $WANAPIS_API_KEY"completed result
{
"code": "success",
"data": {
"task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"status": "SUCCESS",
"progress": "100%",
"data": {
"code": 200,
"data": {
"status": "completed",
"progress": 100,
"result": {
"music": [
{
"title": "City Lights",
"audio_url": "https://.../song.mp3",
"image_url": "https://.../cover.jpg",
"lyrics": "[Verse] Neon rain on empty streets ...",
"duration": 153.8,
"tags": "lo-fi, chill, piano"
}
]
}
}
}
}
}生产建议
状态为 SUBMITTED / IN_PROGRESS 时每 3 到 5 秒轮询一次,通常 30 到 120 秒完成。audio_url 是上游托管的 mp3,可直接喂给 <audio> 播放,无需二次代理。任务失败时状态为 FAILURE,原因在 data.fail_reason。
计费与额度
WanAPIs 按模型倍率和实际 token 或任务计费。文本模型可按输入和输出分别计算，任务类模型通常按次或按规格计费。
| 项目 | 说明 | 示例 |
|---|---|---|
| 输入价格 | model_ratio × $2 / 1M tokens | input_tokens |
| 输出价格 | model_ratio × completion_ratio × $2 / 1M tokens | output_tokens |
| 额度单位 | 控制台余额实时扣减，可在日志中核对 | $1 = 500,000 quota |
错误与重试
API 返回标准 HTTP 状态码。建议对 429、500、502、503、504 做有限重试，对 400、401、403 直接提示配置或权限问题。
| 项目 | 说明 | 示例 |
|---|---|---|
| 401 | API Key 缺失或无效 | 检查 Authorization Header |
| 429 | 触发限流或额度保护 | 降低并发或更换分组 |
| 503 | 上游或系统负载过高 | 等待后重试，使用退避策略 |
迁移指南
从 OpenAI 官方或其它聚合平台迁移时，通常保留 SDK 和请求结构，只替换以下两项：
环境变量
OPENAI_API_KEY=$WANAPIS_API_KEY
OPENAI_BASE_URL=https://api.wanapis.com/v1然后把模型 ID 改为 WanAPIs 模型市场中可用的模型。上线前建议先在低并发环境做 10 到 20 次请求，确认响应格式、token 统计和扣费符合预期。
支持
如果遇到渠道、计费、模型或响应格式问题，请带上请求时间、模型 ID、request id 和错误信息联系支持。