WanAPIs 开发者文档

快速接入 WanAPIs

使用一个 OpenAI 兼容 API Key 调用 GPT、Claude、Gemini、DeepSeek、图像、视频和语音模型。现有项目通常只需要替换 base_url 和 API Key。

介绍

WanAPIs 是统一 AI API 网关,提供 OpenAI 兼容接口、多渠道路由、失败转移、模型市场、调用日志和透明计费。你可以把不同上游的模型统一放在一个 endpoint 下管理。

兼容 OpenAI

支持常用 SDK、Chat Completions、Responses 和工具调用。

统一模型市场

在一个页面查看模型能力、供应商、价格和调用入口。

生产级稳定性

通过多渠道、分组、重试和日志降低上游波动影响。

快速开始

  1. 注册账号进入控制台创建账号并完成邮箱验证。
  2. 创建 API Key在令牌页面生成密钥,并按项目设置额度。
  3. 替换 Base URL把 OpenAI SDK 的 baseURL 改成 https://api.wanapis.com/v1。
  4. 选择模型从模型市场或定价页选择模型 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 URLOpenAI 兼容 API 根地址https://api.wanapis.com/v1
Header请求认证方式Authorization: Bearer sk-...
Content-TypeJSON 请求体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。

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,避免旧配置继续驻留在进程环境中。

Magpie(供应商与模型管理)

和 CC Switch 类似,先添加 WanAPIs,再给 Claude Code / Codex 选择模型。Magpie 通过本地网关转发请求,使用期间需保持运行。

Magpie 手动配置

入口供应商 → 添加供应商 → 自定义供应商
NameWanAPIs
OpenAI / Responseshttps://api.wanapis.com/v1
Anthropichttps://api.wanapis.com
API Keysk-xxx
启用在 Agent 页选模型,再重启或新开会话

公开导入只预填地址,不携带密钥。在 Magpie 中粘贴自己的 Key 并保存后,还需为目标 Agent 选择模型。导入与控制台免费自检都不调用模型;真实请求可能收费。

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. 1. 安装并打开 Codex 桌面端,在认证方式里选择 API Key,不使用 ChatGPT 账号登录模式。
  2. 2. 创建上面的 config.toml 文件,把模型和 provider 指向 WanAPIs。
  3. 3. 设置 WANAPIS_API_KEY 后重启 Codex 桌面端;如果同时使用 VS Code/Cursor,也一起重启。
  4. 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 && codex

5. 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-pro

Continue

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
      - apply

Roo 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。

DX-OS 生图与视频

在 DX-OS 桌面端导入 WanAPIs 媒体协议,即可在画布里配置图片和视频模型。

下载 DX-OS 媒体协议(JSON)
  1. 在 DX-OS 打开「API 设置 → 自定义 API 协议 → 一键导入」,选择下载好的 JSON,再点「导入并添加协议」。找不到入口时,请先更新 DX-OS。
  2. 点击「添加 API」,连接协议选择「WanAPIs 媒体」。Base URL 填 https://api.wanapis.com,API Key 填自己的 WanAPIs 令牌。
  3. 手动添加图片模型 gpt-image-2-official,将「独立协议(可选)」保持为「默认协议」。保存后在画布的「API 生成」节点选择该连接和模型,用 low / 1K / 1:1 先生成一张文生图。

上述生图配置的网关提交、轮询和下载已实测通过。视频可手动添加 minimax-h3 或 seedance-2-5-flash,在画布中发起任务。视频配置尚未完成端到端实测。

遇到报错时,请提供 DX-OS 版本、模型名和脱敏后的报错。

生图与视频工具

下载适配包,解压后按包内的安装说明配置 WanAPIs 令牌。

  • FlyReq Image Studio

    自托管版的源代码补丁。安装包内注明了适用的上游版本。

    下载 ZIP
  • T8 企鹅画布

    自托管版的源代码补丁。安装后按包内说明添加 WanAPIs 连接。

    下载 ZIP
  • ComfyUI

    自定义节点。解压到 ComfyUI 的 custom_nodes 目录,并在启动环境中设置 WANAPIS_API_KEY。

    下载 ZIP

各适配包包含适用版本、支持的模型和验证范围。

异步任务

图片、视频和其它长耗时任务建议走异步任务接口或控制台任务能力,避免公网入口超时。任务创建后通过任务 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 是大写:NOT_START | SUBMITTED | QUEUED | IN_PROGRESS | SUCCESS | FAILURE
# 完成后图片在 data.result.image_urls(数组,可能是 data URL/base64)

# 视频任务:改用视频专用接口
GET /v1/video/generations/{task_id}   # 地址在 data.result_url(平铺字符串)

长任务建议

视频生成、图片编辑、Midjourney 类任务通常耗时较长。业务侧应保存 task id,并为 QUEUED、IN_PROGRESS、SUCCESS、FAILURE 状态分别处理(注意状态值是大写)。

图片生成

图片生成走 OpenAI 兼容的同步入口 POST /v1/images/generations,模型名放在请求体 model 字段。gpt-image-2 用 prompt 出图,加 image_urls 即变图生图(图像编辑)。响应同步返回,图片在 data[0].b64_json(base64 PNG)。

部分模型只能走异步接口

Seedream、Flux、Imagen、Qwen Image、WAN、Z-Image、Midjourney 以及各官方版(-official)模型只有异步接口。对它们调用同步的 /v1/images/generations 会返回 400 并提示改用异步接口——这是有意为之,那条路只会拿到任务信封而不是图片。完整清单和用法见本节末尾「异步专用模型」。

同步 vs 异步官方版

上面的 gpt-image-2 是同步入口,直接返 base64,但总分辨率固定约 1.5MP。要真正的 1K / 2K / 4K 高清、更多比例、以及不怕超时的异步任务,用官方渠道模型 gpt-image-2-official —— 见本节末尾「官方版 · 异步高清」。

gpt-image-2

通用图片模型,文生图 + 图生图(图像编辑),参考图最多 16 张。

flux / imagen / seedream

其它图片模型请以模型市场实际显示为准。

参数类型必填说明
modelstring是固定 gpt-image-2。
promptstring是图片描述或改写指令,中英文均可。
image_urlsstring[]否图生图/图像编辑的参考图:公网 URL 或 base64 data URL(可混用),最多 16 张。
sizestring否像素格式 WxH 只决定画面比例(如 1024x1024 方图、1536x1024 横图);比例字符串如 16:9 不认。输出总分辨率固定约 1.5MP(约 1254×1254),更大尺寸 / 4k 不会得到更多像素。
ninteger否生成张数,默认 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 5.5 · 生成与图层拆解

使用模型 seedream-5-5,将模型名放在请求体 model 中,通过 POST /v1/images/tasks 提交,再用同一把密钥轮询 GET /v1/images/tasks/{task_id}。普通生成与图层拆解使用同一个模型。

项目说明示例
prompt普通生成必填;图层拆解可省略。string
image_urls普通生成可传 0–10 张参考图;图层拆解必须恰好 1 张。["https://.../source.png"]
n仅支持 1。1
size普通生成:支持 1K / 1.5K / 2K(默认 2K)、比例(如 1:1)或精确像素;精确像素总面积须为 921600–4624220,宽高比为 1/16–16,且不能同时传 resolution。图层拆解:仅支持 auto / 1K / 1.5K / 2K,不接受比例或精确像素。1K
output_format普通生成支持 png / jpeg;透明背景须选 png。图层结果为透明 PNG。png
background普通生成可用 transparent 输出透明 PNG;图层拆解必须完全省略此字段,连 auto 也不能传。transparent
layer_decomposition设为 true 开启图层拆解。true
layer_decomposition_options.max_images2–100,含第一张 base 底图,默认 30;是返回图片数量上限。2
layer_decomposition_options.text_recognition可选,true 时请求 OCR 文本识别,不保证识别出文字。true
普通生成 · 透明 PNG
curl https://api.wanapis.com/v1/images/tasks \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-5",
    "prompt": "a single white ceramic mug, isolated on a transparent background",
    "size": "1K",
    "n": 1,
    "output_format": "png",
    "background": "transparent"
  }'
图层拆解 · 1K,最多 2 张(含 base)
curl https://api.wanapis.com/v1/images/tasks \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-5",
    "image_urls": ["https://example.com/source.png"],
    "size": "1K",
    "n": 1,
    "layer_decomposition": true,
    "layer_decomposition_options": {"max_images": 2, "text_recognition": true}
  }'

获取图片与图层信息

提交响应的 data.task_id 用于轮询。SUCCESS 后,图片 URL 仍在 data.data.data.result.images[].url[],第一张是 base 底图。若结果提供 layers 元数据,可读取 z_index、name、bounding_box 及 OCR 信息;layers 可能缺失,不能作为取图的必要条件。透明 PNG 的实际尺寸可能不同于 bounding_box,合成时应按边界框缩放、定位,再按 z_index 排序。OCR 不保证有结果;接口不承诺提供 PSD 或 ZIP。

预扣与等待时间

提交时预扣是估算的额度上限/保留金,完成后按实际消耗多退少补;不代表固定每张价格。图层拆解可能等待约 13 分钟,请继续轮询原 task_id,不要因等待而重复提交。结果是临时链接,请尽快下载保存。

Seedream(即梦)

Seedream 5.5 请按上方专节配置;以下为四个旧版模型的参数: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)。

项目说明示例
modelnano-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,便于上游拉取)。

GPT Image 2.5 · 分档高清

GPT Image 2.5 有两个版本:gpt-image-2.5-flare 适合日常快速出图,gpt-image-2.5-sunburst 编辑精度更高。两者都是异步任务,提交 POST /v1/images/tasks,轮询 GET /v1/images/tasks/{task_id},都支持参考图。

项目说明示例
model必填。两个版本任选。gpt-image-2.5-flare
prompt必填。画面描述。a white ceramic mug
quality质量档,直接决定价格,见下表。不传时由上游按画面自动选档,可能直接落到 high 这类高档,按实际消耗计费。想要价格可预期,请显式传。low
resolution分辨率档 1k / 2k / 4k,与 quality 相乘计价。不传等同 1k。1k
size画幅比例,如 1:1、16:9、3:2。1:1
image_urls参考图,传了就是图生图 / 图像编辑。参考图计入消耗,同一档位下比文生图贵。["https://.../a.jpg"]
n出图张数,默认 1,按张计费。1

价格按档位相乘,跨度很大

以 low + 1k 为基准价 1 倍,quality 依次是 medium 2.25 倍、high 9 倍、xhigh 16 倍、max 36 倍;resolution 的 2k 是 2 倍、4k 是 3.4 倍,两者相乘。也就是说 max + 4k 大约是基准价的 122 倍。批量跑图前请先确认档位,精确价格以模型广场为准。

档位价是预扣,完成后按实际消耗结算

上游按实际消耗计费:不传 quality、带参考图、画幅大、提示词长,都会让一张图的实际消耗高于所选档位价。所以提交时先按档位预扣,任务完成后再按实际消耗结算,最终扣费取两者中较高的一个,差额自动补扣,使用日志里会多一条「按实际消耗补扣」。例如一张不传 quality、带一张参考图的 sunburst 编辑,实际消耗约是 low 档价的 10 倍。批量调用请显式传 quality 和 resolution。
提交(最便宜档,显式传 low + 1k)
curl https://api.wanapis.com/v1/images/tasks \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "一只白色陶瓷马克杯,置于白色桌面,产品图",
    "size": "1:1",
    "quality": "low",
    "resolution": "1k"
  }'
图像编辑(带参考图)
curl https://api.wanapis.com/v1/images/tasks \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "把背景换成纯白影棚",
    "image_urls": ["https://example.com/source.jpg"],
    "quality": "low"
  }'
# 编辑类任务用 sunburst;参考图计入消耗,同档下比文生图贵
# 轮询方式与其它异步模型一致,结果地址约 24 小时过期

GPT Image 2.6 · 分档生成

GPT Image 2.6 有两个版本:gpt-image-2.6-flare 面向速度优先的日常出图,gpt-image-2.6-sunburst 面向细节与编辑精度要求更高的场景。两者使用异步任务接口,提交 POST /v1/images/tasks,轮询 GET /v1/images/tasks/{task_id},都支持参考图和图像编辑。

项目说明示例
model必填。两个版本任选。gpt-image-2.6-flare
output_formatpng / jpeg / webp / gif / svg;GIF / SVG 的专属参数与结算规则见下文。png
prompt必填。画面描述。a white ceramic mug
quality质量档 low / medium / high / xhigh / max,也接受 auto。不传时按画面自动选档;建议显式传 low,最终金额仍按实际消耗结算。low
resolution分辨率档 1k / 2k / 4k,与 quality 相乘计价。不传等同 1k。1k
size画幅比例,如 1:1、16:9、3:2;也接受精确像素尺寸。1:1
image_urls参考图,传了就是图生图 / 图像编辑;参考图计入消耗。["https://.../a.jpg"]
n出图张数,默认 1,按张计费。1

2.6 的档位价差比 2.5 平缓

普通图片生成以 low + 1k 为基准价 1 倍,quality 依次是 medium 1.76 倍、high 2.14 倍、xhigh 3.8 倍、max 8.55 倍;resolution 的 2k 是 2 倍、4k 是 3.4 倍,两者相乘。不要套用 2.5 的倍率表。精确价格以模型广场为准;GIF / SVG 另按下文的实际消耗规则结算。

预扣按档位,完成后按实际消耗结算

普通 PNG / JPEG / WebP 生成按所选档位预扣,完成后按实际消耗结算,不足时补扣;参考图、画幅与提示词长度都会影响消耗。批量调用请显式传 quality 和 resolution。GIF / SVG 的预扣与结算规则见下文。
提交(最便宜档,显式传 low + 1k)
curl https://api.wanapis.com/v1/images/tasks \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "一只白色陶瓷马克杯,置于白色桌面,产品图",
    "size": "1:1",
    "quality": "low",
    "resolution": "1k"
  }'

GIF 动图 · output_format: gif

项目说明示例
gif.frame_count2–16 帧,默认 9。2
gif.frame_duration_ms每帧至少 20 毫秒,默认 200。200
sizeauto 或像素尺寸,默认 512x512;不能传 1:1 等比例。512x512
image_urls / n参考图最多 16 张;n 为 1–4。不支持 mask、markup 或压缩参数。1
GIF · 2 帧最小示例
curl https://api.wanapis.com/v1/images/tasks \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "a small red ball gently bouncing, seamless loop",
    "output_format": "gif",
    "gif": {"frame_count": 2, "frame_duration_ms": 200},
    "size": "512x512",
    "quality": "low",
    "n": 1
  }'

SVG 矢量图 · output_format: svg

SVG 先生成中间图,再由作者模型生成矢量内容。n 必须为 1,参考图 image_urls 最多 16 张;不支持 mask、markup 或压缩参数。complexity 是顶层字段,示例用 low;作者配置放在 svg 中,使用 gpt-5.4-mini 与 reasoning.effort: low。

SVG · mini 作者模型
curl https://api.wanapis.com/v1/images/tasks \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "a simple blue mountain icon, clean vector shapes",
    "output_format": "svg",
    "complexity": "low",
    "svg": {"model": "gpt-5.4-mini", "reasoning": {"effort": "low"}},
    "size": "1:1",
    "quality": "low",
    "n": 1
  }'

GIF / SVG 按实际消耗结算

预扣是估算的额度上限/保留金,完成后按实际消耗多退少补。SVG 费用包含中间图生成与作者模型 token,作者模型不是免费附赠,也不是固定每张价;reasoning token 已计入 output,不需重复相加。SVG 任务可能等待约 22 分钟,GIF 沿用普通任务的轮询方式;请持续轮询原 task_id,不要重发生成请求。
GIF / SVG 轮询与下载
curl https://api.wanapis.com/v1/images/tasks/task_xxx \
  -H "Authorization: Bearer $WANAPIS_API_KEY"
# task_xxx 取提交响应的 data.task_id,每 3–5 秒轮询一次
# SUCCESS 后取 data.data.data.result.images[].url[]
# 文件链接是临时地址,请尽快下载保存

异步专用模型

下面这些图片模型只提供异步任务接口。请统一用 POST /v1/images/tasks 提交、GET /v1/images/tasks/{task_id} 轮询,不要用 /v1/images/generations。普通图片任务按张预扣,完成后核对实际消耗,预扣不足时补扣;Seedream 5.5 与 GPT Image 2.6 GIF / SVG 的预扣是估算保留金,按实际消耗多退少补,见各自专节。

项目说明示例
Seedream含 5.5 生成与图层拆解,以及 Lite / Pro;5.5 参数见专节。seedream-5-5 / seedream-5-0-lite / seedream-5-0-pro
FluxFLUX.2 系列,含 Kontext 图像编辑。flux-2-pro / flux-kontext-pro
ImagenGoogle Imagen 4。imagen-4.0-apimart
Qwen Image通义万相图像,Pro 档细节更好。qwen-image-2.0 / qwen-image-2.0-pro
WAN万相 2.7 图像,Pro 档分辨率更高。wan2.7-image / wan2.7-image-pro
Z-Image轻量快速档,单价最低。z-image-turbo
Midjourney一次返回 4 张图,参数见上文 Midjourney 小节。midjourney
官方版OpenAI 官方渠道,支持 1K / 2K / 4K,参数见上文小节。gpt-image-2-official

请求参数

Seedream 5.5、Midjourney 和官方版请按各自专节配置;以下为其余模型的通用字段。GPT Image 2.6 的 GIF / SVG 也有专属参数,不能套用通用尺寸与计费说明。

项目说明示例
model必填。模型名,取值见上表。qwen-image-2.0
prompt必填。画面描述,中英文都可以。留空会直接报 400。a white ceramic mug
size可选。控制画幅。像素格式与比例格式的支持情况按模型不同,见下表。16:9
image_urls可选。参考图,传了就是图生图(以原图为基础按提示词改写,主体和构图保留)。支持公网 HTTPS 图片地址,也支持 data:image/png;base64,... 内联图。["https://.../a.jpg"]
n可选。出图张数,默认 1。按张计费:n=2 就是两倍价钱,响应里会返回两个 URL。1

size 的实测行为

各家上游对 size 的处理并不一致,下面是实测结果(不传 size 时用各自默认值):

项目说明示例
Qwen Image两种格式都生效。像素格式按你给的尺寸精确出图;比例格式也认。默认 1024×1024。1280x720 → 1280×720 / 16:9 → 1280×720
Seedream 5.0 Lite(不含 5.5)只认比例格式,像素格式会被忽略并回落到默认的 2048×2048。要换画幅请传 16:9 这类比例。16:9 → 2848×1600 / 1792x1024 → 2048×2048
其它模型Flux / Imagen / WAN / Z-Image 建议优先用比例格式,并以实际返回的图片尺寸为准。16:9

quality 和 resolution 对这些模型无效

只有官方版(-official)模型有 quality / resolution 档位并按档位计价。上面这些模型的上游会忽略这两个字段——传 quality: "high" 出图和价格都不会变,所以不用传。要换画幅请用 size。

密钥限制了可用模型时,轮询也要放行

如果密钥开了「可用模型限制」,轮询 GET /v1/images/tasks/{task_id} 用的是任务本身记录的模型名。所以只要提交时那个模型在白名单里,轮询就能通过,不需要额外配置。若仍收到 403,请确认提交和轮询用的是同一把密钥。
文生图
curl https://api.wanapis.com/v1/images/tasks \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "一只白色陶瓷马克杯,置于白色桌面,产品图",
    "size": "16:9"
  }'
# => {"code":"success","data":{"status":"submitted","task_id":"task_xxx"}}
图生图 / 参考图
curl https://api.wanapis.com/v1/images/tasks \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "把这张照片改成水彩画风格",
    "image_urls": ["https://example.com/source.jpg"]
  }'
# 参考图要能被上游公网访问;也可以传 data:image/png;base64,... 内联图
# 图像编辑类任务用 flux-kontext-pro 效果更贴近原图
轮询取结果
curl https://api.wanapis.com/v1/images/tasks/task_xxx \
  -H "Authorization: Bearer $WANAPIS_API_KEY"
# 每 3-5 秒轮询一次,通常 10-30 秒完成
# status 变成 SUCCESS 后,图片地址在 data.data.data.result.images[].url[]
# 该地址约 24 小时后过期,请及时下载保存

视频生成

视频生成统一归到视频能力目录下。模型配置方法放在本目录下,例如 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 三档。

MiniMax H3

海螺03,原生音轨,480p / 768P / 1080p / 2K;多图、首尾帧、视频和音频参考、再生成与提示词优化按当前能力开放。完整协议与收费示例见下方H3专节。

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-flashSeedance 2.5 Flash:480p / 720p,4–30 秒或自动时长,支持图片、视频与音频参考。详见 Flash 专节。预扣后按实际消耗结算
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-qualityGoogle Veo 3.1 高质量档,支持 4K 与同步音频。按次
veo3.1-fastVeo 3.1 速度档。按次
veo3.1-liteVeo 3.1 轻量档,价格最低。按次
minimax-h3MiniMax 海螺03,480p / 768P / 1080p / 2K,4–30秒(2K最长15秒)。兼容旧单图请求,扩展content承载多参考素材;支持范围和费用见H3专节及实时能力。输出+素材+可选IR
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-videoxAI Grok,只能 6 秒,单价最低。时长必填(seconds 或 duration,值固定 6),不传会被上游 400 拒绝。按秒
grok-imagine-videoxAI Grok 的正式视频模型,比 grok-video 强:1~15 秒任选、480P/720P 可指定、自带音轨,也支持图生视频。按秒
grok-imagine-video-1.5xAI 目前最新的视频模型(Aurora-2)。在 grok-imagine-video 基础上多了 1080P,音画同一遍生成。按分辨率分档计价。按秒

部分模型有两种参数写法

不同模型的字段位置和默认值不同,请按各自参数表提交,不要机械地把同一参数同时放到顶层和metadata,也不要依赖未知字段会被忽略。H3按严格类型解析;resolution、ratio及seconds建议写在顶层,重复别名必须一致。

上述兜底写法与默认值不适用于 minimax-h3。普通 H3 默认 4 秒、768P、9:16;重复参数有冲突会返回 400,请按下方 H3 专属表填写。

Kling(可灵)

快手可灵,人物动作与肢体连贯性最好。注意它的参数体系和 Seedance 不同:清晰度用 mode(不是 resolution),比例用 aspect_ratio(不是 size)。

项目说明示例
modelkling-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。这三个是按次计费(不按秒),所以时长参数不影响单价。

项目说明示例
modelveo3.1-quality(质量优先) / veo3.1-fast(速度) / veo3.1-lite(最低价)。veo3.1-fast
prompt必填。视频提示词。string
resolution输出清晰度。720p / 1080p / 4k,价格随之上升。1080p
duration时长(秒)。按次计费,时长不改变单价。5
image_urls图生视频参考图数组。["https://...jpg"]

MiniMax H3(海螺03)

H3提供原生音轨与480p / 768P / 1080p / 2K输出,兼容旧式文本/单图输入,并通过content描述多参考图、首尾帧、参考视频和音频。高级能力是否开放,请读取当前模型能力,不要把缺失的配置当作免费或已支持。

完整H3教程:上传、生成、查询、下载、IR与再生成

默认规格与严格输入

默认4秒、768P、9:16、fast_mode=false、context_ir_enabled=true。4–30秒,2K最长15秒。seconds/duration接受整数数字或整数字符串;布尔字段只能true/false。未知字段、重复JSON键和冲突别名会被拒绝。content与旧式prompt/图片输入不要混用。
项目说明示例
model必填的公开模型名。minimax-h3
prompt / content使用旧式 prompt+可选单图,或使用有类型的 content 数组;content 不与旧媒体别名混用。text / image_url / video_url / audio_url
resolution480p / 768P / 1080p / 2K;档位不保证确切输出像素。768P
seconds / duration4–30 的整数,2K 最长15秒;接受整数数字或整数字符串,别名冲突会拒绝。4
ratio21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16;adaptive 仅用于支持的素材请求。9:16
fast_mode严格 JSON 布尔值。true 将输出与收费参考素材费乘2,不影响 IR。false
context_ir_enabled严格 JSON 布尔值,控制生成内提示词优化。复用单独优化过的提示词时显式关闭。true
input_reference兼容单图:URL 字符串或 {image_url: URL} 对象。它是参考图,不等于明确首帧。{"image_url":"https://…"}
content[].role图片:reference_image / first_frame / last_frame;视频:reference_video;音频:reference_audio。reference_image
media sourceimage_url / video_url / audio_url 内 url 与 asset_id 二选一;本地文件先上传取得本人素材句柄。{"asset_id":"asset_…"}
size兼容旧档位和方向选择器;新请求优先 resolution+ratio,冲突返回400。1280x720
最小文本请求
curl https://api.wanapis.com/v1/videos \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3",
  "prompt": "A paper boat crosses a calm lake, slow cinematic tracking shot",
  "resolution": "768P",
  "ratio": "16:9",
  "seconds": 4,
  "fast_mode": false,
  "context_ir_enabled": true
}'
多参考素材:先替换本人上传的asset_id
curl https://api.wanapis.com/v1/videos \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3",
  "resolution": "768P",
  "ratio": "16:9",
  "seconds": 4,
  "fast_mode": false,
  "context_ir_enabled": false,
  "content": [
    {
      "type": "text",
      "text": "A paper boat crosses a calm lake, slow cinematic tracking shot"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "asset_id": "asset_image_example"
      }
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {
        "asset_id": "asset_video_example"
      }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {
        "asset_id": "asset_audio_example"
      }
    }
  ]
}'

素材和独立操作

最多9图、3参考视频、3参考音频。参考视频合计建议≤15秒,单片容忍上限按能力执行;音频总长≤15秒。本地文件先POST /v1/videos/assets,后续文件用binding_asset_id与第一份素材绑定;每项来源url与asset_id二选一。首尾帧使用明确role;旧input_reference是参考图,并不强制首帧。

本人成功的768P原任务可按资格POST /v1/videos/{id}/regenerations输出2K;mode=content须原样重传原最终prompt及全部参考素材,mode=source仅在可用模式列出时使用,不是任意视频放大。独立提示词优化使用POST /v1/videos/prompt-optimizations,结果为文本;将其用于生成时显式关闭context_ir_enabled,避免再次优化计费。

基础零售价(人民币,分组倍率1)

项目说明示例
480p输出和参考视频 ¥0.078/秒按秒
768P输出和参考视频 ¥0.117/秒按秒
1080p输出和参考视频 ¥0.182/秒按秒
2K输出和参考视频 ¥0.195/秒按秒

分项预扣与冻结费率退差

普通费用=[输出秒价×输出秒数+参考视频秒价×ceil(参考视频合计秒数)+¥0.065×max(图数−5,0)]×长时倍率×优先倍率+IR,最后整体乘有效分组倍率。16–30秒长时倍率2,fast=true优先倍率2,两者作用于输出与收费素材;IR默认每次¥0.065,不随这两项翻倍。前5图和音频不加素材费。1.2+1.2秒参考视频合并后按3秒,不是逐片取整成4秒。

带参考视频时按最大可能输入量足额预留,核实用量后以提交时冻结费率退差。billing.status=pending_usage表示仍待核定,charged_quota尚未知,不能把reserved_quota当最终消费。已受理失败全退额度。无收费参考素材时,4秒768P默认含IR为¥0.533,关闭IR为¥0.468。

2K再生成独立按输出¥0.078/秒+原参考视频¥0.078/计费秒+超5图部分¥0.052/张计价,再乘分组倍率;原片本体不重复算参考输入,不继承原任务的IR、长时或优先附加项。独立IR仅按次收费。实时价格与能力以模型广场和/api/pricing为准。

OpenAI风格查询
curl https://api.wanapis.com/v1/videos/task_example \
  -H "Authorization: Bearer $WANAPIS_API_KEY"
认证下载
curl https://api.wanapis.com/v1/videos/task_example/content \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  --output result.mp4

顶层status=completed后取metadata.url;通用GET /v1/video/generations/{id}则读data.status=SUCCESS及data.result_url。视频完成和账单结算独立。POST结果不明时先查询已知ID,不要盲目重新提交;关闭页面不会取消已受理任务。结果不承诺统一24小时保留,请及时保存。

Vidu Q3 / HappyHorse / Grok Video

项目说明示例
viduq3生数科技。分辨率 540p / 720p / 1080p,另有 viduq3-pro(更高质量)、viduq3-turbo(更便宜)、viduq3-mix 变体。按秒
happyhorse-1.0阿里 ATH,2026-04 发布。支持 720p / 1080p。按秒
grok-videoxAI。只能 6 秒,单价最低,支持图生视频。⚠️ 时长必填:传 seconds: "6"(字符串)或 duration: 6(数字),两者都行,都不传会被上游以 400 duration required 拒绝。参考图用 reference_images(URL 数组);⚠️ 不认 input_reference,传了会 400。size 不被采纳:文生视频成片 720x405,图生视频 1280x720。按秒
grok-imagine-videoxAI Grok 正式视频模型。时长 1~15 秒(14 档),resolution 可选 480p / 720p 且真的生效(实测 480p 出 848x480),比例 1:1 / 16:9 / 9:16 / 3:2 / 4:3 / 3:4 / 2:3,成片自带音轨。图生视频同样用 reference_images。⚠️ 时长请显式传:不传会按上游默认 8 秒出片并照 8 秒计费。按秒
grok-imagine-video-1.5xAI 最新视频模型(Aurora-2 引擎)。时长 1~15 秒,resolution 可选 480p / 720p / 1080p 且三档都是真的(实测分别出 848x480 / 1280x720 / 1920x1088),三档都带 aac 音轨。图生视频同样用 reference_images。⚠️ 按分辨率分档计价:以 480p 为基准,720p 是 1.25 倍、1080p 是 1.875 倍,时长再乘上去。⚠️ 时长请显式传,不传会按上游默认 8 秒出片并照 8 秒计费。按秒

grok-video 的时长必须显式传

它只出 6 秒片,但时长仍是必填 —— 上游不会替你默认。seconds 传字符串、duration 传数字都可以,两者漏掉会拿到 400 duration required。图生视频用 reference_images(公网 HTTPS 图 URL 数组),input_reference 这个 Sora 写法它不认,传了直接 400。另外它是网页反代,偶发会以 grok auth failed 失败,这种失败会自动退费,重试即可。
grok-video 6 秒片
curl https://api.wanapis.com/v1/video/generations \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video",
    "prompt": "a paper plane glides over a neon city at night",
    "seconds": "6"
  }'
grok-video 图生视频(参考图)
curl https://api.wanapis.com/v1/video/generations \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video",
    "prompt": "slow cinematic push in",
    "seconds": "6",
    "reference_images": ["https://example.com/first.jpg"]
  }'
grok-imagine-video(可选时长 / 分辨率 / 带音轨)
curl https://api.wanapis.com/v1/video/generations \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "a paper plane glides over a neon city at night",
    "duration": 6,
    "resolution": "720p"
  }'
grok-imagine-video-1.5(1080P + 图生视频)
curl https://api.wanapis.com/v1/video/generations \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "slow cinematic push in",
    "duration": 6,
    "resolution": "1080p",
    "reference_images": ["https://example.com/first.jpg"]
  }'

任务状态与结果

通用任务查询GET /v1/video/generations/{id}使用下表的data字段;OpenAI风格GET /v1/videos/{id}则使用顶层status和metadata.url。两者状态拼写与地址位置不同,请按实际查询路径解析,提交受理后保存公开任务ID。

项目说明示例
data.status本表为通用格式:NOT_START / SUBMITTED / QUEUED / IN_PROGRESS / SUCCESS / FAILURE。OpenAI格式使用顶层queued/in_progress/completed/failed。SUCCESS
data.result_url视频地址。⚠️ 是平铺的字符串字段,既不是数组、也不在 metadata 里。取错字段的典型表现是「上游其实早就成功了,你这边却永远停在 processing」。https://.../content
data.progress进度,是带百分号的字符串,不是数字。"100%"
data.fail_reason失败原因,字符串;成功时是空串。string
data.submit_time / start_time / finish_time提交 / 开始 / 完成的时间戳(秒),相减即得排队与生成耗时。1790087400
data.quota任务记录的额度。非终态或账单pending时可能为预留;H3最终收费读billing.charged_quota。额度除以500000为人民币元。234000
data.data模型特定的补充结果,不能假定各模型结构一致;优先使用本文明确的公共状态和结果字段。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 下载。

旧型号参数约定(Flash 见下方专节)

推荐使用统一后的顶层字段:时长 duration(数字,4~15 秒)、比例 size、清晰度 resolution、音频 generate_audio、末帧 return_last_frame、随机种子 seed。参考图放 image_urls(最多 9 张,含首尾帧);需要明确角色时改用 image_with_roles(每项 url + role:first_frame / last_frame / reference_image),两者互斥。参考视频放 video_urls,参考音频放 audio_urls。旧客户端的 seconds / images / metadata.content 会被网关兼容归一,新代码不要再使用。

seedance-2-5-flash

Seedance 2.5 Flash:480p / 720p,4–30 秒或自动时长,按下方专属规则预扣与结算。

seedance-2.5

最新一代,画质与一致性最好,按秒计费中价格最高。

seedance-2.0

标准版,画面质量优先,适合正式素材生成。

seedance-2.0-fast

速度版,适合草稿、批量预览和低延迟场景。

seedance-2.0-mini

轻量版,价格最低,适合大批量试稿。

Seedance 2.5 Flash

模型名为 seedance-2-5-flash(全连字符),default / svip 分组可调用。Flash 使用本节参数,不沿用旧型号的 4–15 秒与素材数量限制。

项目说明示例
resolution / duration480p / 720p;时长为整数 4–30 秒或 -1 自动时长。默认 720p、5 秒。不支持 1080p、draft 或 draft_task_id。4
size / generate_audiosize 默认 adaptive,也可选 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9;generate_audio 默认 true,false 生成静音视频。adaptive
image_urls / image_with_roles最多 10 图;两字段互斥。角色可用 first_frame / last_frame / reference_image。last_frame 需同时提供 first_frame;纯首尾帧任务使用 adaptive。10
video_urls / audio_urls各最多 5 段,每段 2–30 秒;参考视频和音频的总时长各自不超过 30 秒。5 / 5
omni_reference_task_typeauto / reference / edit / extend;edit、extend 需参考视频和 adaptive。edit 省略 duration 或传 -1,时长跟随源视频。output_format 支持 mp4 / mov。auto

Flash 预扣与最终结算

普通文生视频或图生视频的预扣费率为 480p ¥0.574392/秒、720p ¥1.291472/秒。含参考视频使用 input 档:480p ¥0.34944/秒、720p ¥0.78624/秒,计费时长含参考视频与输出视频。以上为 1 倍分组价格,实际乘令牌生效分组倍率。

预扣不是最终消费。完成后按实际消耗多退少补;自动输出时长按 30 秒预扣,含参考视频时还按参考视频总长上限 30 秒保守预扣。等待费用结算期间继续轮询,不要重复提交。

提交 POST /v1/video/generations;轮询 GET /v1/video/generations/{task_id},成功后下载 GET /v1/videos/{task_id}/content。本地素材先用 POST /v1/media 上传,再传返回的 URL。

Flash:4 秒、480p 文生视频
curl https://api.wanapis.com/v1/video/generations \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5-flash",
    "prompt": "Gentle waves on a beach, static camera, natural light",
    "duration": 4,
    "resolution": "480p",
    "size": "adaptive",
    "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",
    "prompt": "一只橘猫在清晨的窗边伸懒腰,镜头缓慢推进,柔和自然光,电影感",
    "duration": 5,
    "size": "16:9",
    "resolution": "720p",
    "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": "让照片中的人物自然转身看向镜头,微风吹动头发,背景保持一致",
    "image_urls": ["https://example.com/portrait.jpg"],
    "duration": 5,
    "size": "adaptive",
    "resolution": "720p"
  }'
首尾帧过渡
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": "从白天城市街景平滑过渡到夜晚霓虹灯街景,镜头向前移动",
    "duration": 5,
    "size": "16:9",
    "resolution": "720p",
    "image_with_roles": [
      {"url": "https://example.com/day.jpg", "role": "first_frame"},
      {"url": "https://example.com/night.jpg", "role": "last_frame"}
    ]
  }'

本地素材上传

上游只接受公网 URL。需要传本地图片、视频或音频时,先调用 POST /v1/media(multipart),拿到返回的 url 后放进 image_urls / video_urls / audio_urls。上传免费,不创建任务;URL 默认 6 小时后过期,过期后重新上传即可。

上传
curl https://api.wanapis.com/v1/media \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -F "model=seedance-2.0-mini" \
  -F "media_type=image" \
  -F "[email protected]"
上传响应
{
  "id": "media_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "url": "https://api.wanapis.com/v1/media/media_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx?expires=1790000000&signature=xxxxxxxx",
  "media_type": "image",
  "bytes": 48213,
  "expires_at": 1790000000
}

上传限制

单文件上限:图片 30 MiB、视频 31 MiB、音频 15 MiB;请求体上限 32 MiB。返回的 URL 带签名,只能由拿到它的上游读取;不要把它当永久素材库。H3 的本地素材走另一条 POST /v1/videos/assets,返回的是 asset_id,两种 ID 不能混用。
项目说明示例
prompt视频生成提示词。写清主体、动作、场景、镜头、风格和限制条件。"电影感推镜"
duration视频时长(秒),顶层数字,4~15。默认 5。旧字段 seconds 仍兼容。5
size视频比例,顶层字段。16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / adaptive。16:9
resolution输出清晰度,顶层字段。480p / 720p / 1080p / 4k,具体支持范围随模型变化。720p
image_urls参考图数组,最多 9 张(含首尾帧)。与 image_with_roles 互斥。["https://...jpg"]
image_with_roles带角色的参考图,每项 {url, role};role 可为 first_frame / last_frame / reference_image。[{url, role}]
video_urls参考视频数组,最多 3 个;总时长需大于 1.8 秒且小于 15.2 秒,不能与首尾帧同用。["https://...mp4"]
audio_urls参考音频数组,最多 3 个,总长≤15 秒;必须同时有参考图或参考视频,不能与首尾帧同用。["https://...mp3"]
generate_audio是否生成同步音频,顶层布尔值。开启后耗时可能更长。true
return_last_frame是否返回末帧,顶层布尔值,方便做连续镜头。true
seed随机种子,顶层整数,用于复现结果。42

提交响应

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
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://api.wanapis.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxx/content",
    "fail_reason": "",
    "quota": 234000,
    "submit_time": 1790087400,
    "start_time": 1790087406,
    "finish_time": 1790087421,
    "properties": {
      "origin_model_name": "seedance-2.0"
    }
  }
}

生产建议

任务状态为 QUEUED 或 IN_PROGRESS 时每 5 到 10 秒轮询一次即可;终态是 SUCCESS 和 FAILURE(注意都是大写),失败时记录 task id、模型名和 fail_reason。素材可以是公网 HTTPS URL,也可以用 POST /v1/media 上传本地文件后使用返回的 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
versionSuno 版本(必填)。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 × CNY 2 / 1M tokensinput_tokens
输出价格model_ratio × completion_ratio × CNY 2 / 1M tokensoutput_tokens
额度单位额度以人民币锚定,按日志中的预扣、消费和退还核对;界面货币符号不改变该换算。CNY 1 = 500,000 quota

错误与重试

API返回标准HTTP状态码。GET查询可对429和临时5xx有限退避重试;400/401/403应先修参数、认证或权限。视频、图片等付费POST若超时或结果不明,先查已有任务ID和请求ID,不要盲目重新提交,以免创建重复付费任务。

项目说明示例
401API 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 和错误信息联系支持。