WanAPIs developer docs

Get started with WanAPIs

Call GPT, Claude, Gemini, DeepSeek, image, video and audio models with one OpenAI-compatible API key. Most projects only need to swap base_url and the API key.

Introduction

WanAPIs is a unified AI API gateway with an OpenAI-compatible interface, multi-channel routing, failover, a model marketplace, request logs and transparent billing. You can manage models from different upstreams under a single endpoint.

OpenAI-compatible

Works with common SDKs, Chat Completions, Responses and tool calling.

Unified marketplace

See model capabilities, vendors, prices and entry points on one page.

Production-grade reliability

Multi-channel, groups, retries and logs reduce the impact of upstream hiccups.

Quickstart

  1. Create an accountOpen the console, create an account and verify your email.
  2. Create an API keyGenerate a key on the Tokens page and set per-project quota.
  3. Swap the Base URLPoint your OpenAI SDK baseURL to https://api.wanapis.com/v1.
  4. Pick a modelChoose a model ID from the marketplace or pricing page.
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": "Explain RAG in three sentences" }
    ]
  }'

Authentication

Every request must carry a Bearer token in the header. Never put your API key in front-end browser code — proxy requests through your own backend.

FieldDescriptionExample
Base URLOpenAI-compatible API roothttps://api.wanapis.com/v1
HeaderRequest authAuthorization: Bearer sk-...
Content-TypeJSON bodyapplication/json

Key management

Create a separate API key per project with quota limits. After launch, watch model, group, latency and charges on the Logs page.

Chat Completions

Compatible with /v1/chat/completions — for most existing OpenAI SDKs, chatbots, agents and tool-calling projects.

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: "Write a TypeScript retry function" }],
});

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": "Give me a product launch checklist"}],
)

print(response.choices[0].message.content)

Responses API

For the next-gen Responses workflow, call /v1/responses. On upstream 503 or high load, add exponential-backoff retries on your side.

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": "Analyze this log and give troubleshooting steps"
  }'

Model marketplace

The marketplace syncs from the WanAPIs pricing API and shows capabilities, vendors and prices by category: video, image, LLM and audio.

Clients / IDE

A key section. Any OpenAI / Anthropic-compatible client that supports a custom base_url can use WanAPIs. We recommend getting the local CLI working first, then the VS Code extensions: Claude Code → CC Switch → Codex Desktop → Codex CLI → VS Code.

1. Claude Code (recommended)

Anthropic's official CLI agent. With WanAPIs you can use claude-opus-4-7、claude-sonnet-4-6 and other Claude models.
Claude Code
# 1. Install (requires Node.js >= 18)
npm i -g @anthropic-ai/claude-code

# 2. Set env vars; add to ~/.zshrc or ~/.bashrc
export ANTHROPIC_BASE_URL="https://api.wanapis.com"
export ANTHROPIC_AUTH_TOKEN="sk-xxx"

# 3. Start in your project directory
cd your-project && claude

On first launch it asks you to pick a model. Verify the install with claude --version.

2. CC Switch (desktop GUI switcher)

CC Switch manages providers for agents like Claude Code / Codex / Gemini CLI, switching base_url and token in one click.

CC Switch setup

Entrycodex / claude group -> + at top right
NameWanAPIs
Base URLhttps://api.wanapis.com
API Keysk-xxx
EnableAfter saving, click Enable / Switch to
CC Switch
# Download from GitHub Releases:
# https://github.com/farion1231/cc-switch/releases

# 1. Open CC Switch
# 2. Go to the codex or claude group
# 3. Click + on the right to add WanAPIs
# 4. After saving, click Enable / Switch to
# 5. Restart Codex, VS Code or Claude Code
One-click import (if CC Switch is installed)

Click a button below to import the WanAPIs preset (no key included); then paste your API key in CC Switch.

After saving, restart Codex, VS Code or Claude Code so stale config doesn't linger in the process environment.

Magpie (providers and models)

Add WanAPIs, then select a model for Claude Code / Codex, as you would with CC Switch. Magpie forwards requests through a local gateway and must keep running.

Magpie manual setup

EntryProviders → Add provider → Custom provider
NameWanAPIs
OpenAI / Responseshttps://api.wanapis.com/v1
Anthropichttps://api.wanapis.com
API Keysk-xxx
EnableChoose a model in Agents, then restart or open a new session

Public import fills endpoints without a key. Enter your key and save in Magpie, then select a model for the target agent. Import and the free console setup check do not call a model; real requests may be billed.

3. Codex Desktop (macOS / Windows)

OpenAI's official Codex desktop app. Desktop, CLI and IDE extensions share ~/.codex/config.toml; the native Windows path is %USERPROFILE%\.codex\config.toml.

Codex Desktop settings

Auth methodAPI Key
Config file~/.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"
Environment variables
# macOS / Linux: add to ~/.zshrc or ~/.bashrc, then reopen the terminal
export WANAPIS_API_KEY="sk-xxx"

# Windows PowerShell: persist to the current user's environment variables
[Environment]::SetEnvironmentVariable("WANAPIS_API_KEY", "sk-xxx", "User")
  1. 1. Install and open Codex Desktop, choose API Key as the auth method instead of ChatGPT account login.
  2. 2. Create the config.toml above and point the model and provider at WanAPIs.
  3. 3. Set WANAPIS_API_KEY, then restart Codex Desktop; restart VS Code/Cursor too if you use them.
  4. 4. Native Windows Codex and WSL Codex don't share the same home; in WSL write a separate ~/.codex/config.toml, or set CODEX_HOME to point at the same directory.

Model choice

For coding tasks prefer gpt-5.5 or claude-sonnet-4.7. If a model doesn't support the Responses format or tool calling, switch to a tool-calling-capable model from the marketplace to verify first.

4. Codex CLI

OpenAI's official coding agent. We recommend the responses wire API, and writing the provider into ~/.codex/config.toml.
Codex CLI
# 1. Install
npm i -g @openai/codex

# 2. Edit ~/.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. Set the token
export WANAPIS_API_KEY="sk-xxx"

# 4. Start in your project directory; it reads the same ~/.codex/config.toml
cd your-project && codex

5. VS Code extensions

Two kinds: official Codex / Claude Code extensions usually reuse your local CLI config; third-party ones like Cline, Continue and Roo Code take the URL, key and model directly in their settings.

Official Codex extension (openai.chatgpt)

Install openai.chatgpt from the VS Code extension marketplace. It doesn't take a Base URL in the chat box; first set up ~/.codex/config.toml, then restart VS Code. The official Codex extension reuses the model and provider settings from your local Codex config.

Official Codex extension config path

Install fromVS Code -> openai.chatgpt
Config file~/.codex/config.toml
base_urlhttps://api.wanapis.com/v1
env_keyWANAPIS_API_KEY
How to applyRestart VS Code after saving
~/.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 extension

Install Claude Code from the VS Code extension marketplace. The key isn't entering a URL in the extension; first confirm that claude in your terminal already connects to WanAPIs. The extension reuses your local ~/.claude config. Restart VS Code after changing the config.

Claude Code extension checklist

CLI checkRunning claude in the terminal works
Env varsANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN
Config dir~/.claude/settings.json / config.json
Common actionRestart VS Code after changing config

Cline (formerly Claude Dev, recommended)

Open the Cline sidebar, click the settings gear, choose OpenAI Compatible as the provider, then fill in Base URL, API Key and Model ID.

Cline settings panel

API ProviderOpenAI Compatible
Base URLhttps://api.wanapis.com/v1
API Keysk-xxx
Model IDclaude-opus-4-7
VerifyClick Verify or start a conversation
Cline settings
API Provider: OpenAI Compatible
Base URL: https://api.wanapis.com/v1
API Key:  sk-xxx
Model:    claude-opus-4-7
# You can also use gpt-5.5 / gemini-3.5-flash / deepseek-v4-pro

Continue

Continue currently recommends YAML config. Open the config file in Continue's settings and add a models entry with provider: openai, then point apiBase at 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

Open Roo Code's sidebar settings and choose OpenAI Compatible as the API Provider. Roo Code's docs note you need to fill in Base URL, API Key and Model ID here; if a model doesn't support tool calling, switch to one that does.

Roo Code settings panel

API ProviderOpenAI Compatible
Base URLhttps://api.wanapis.com/v1
API Keysk-xxx
Modelgpt-5.5 / claude-opus-4-7
NotePrefer a model that supports tool calling

6. Desktop clients / browser extensions

General setup: choose OpenAI Compatible as the provider, set Base URL to https://api.wanapis.com/v1 and API Key to sk-xxx.
  • CherryStudio: a popular desktop LLM client, good for switching between providers.
  • ChatBox: cross-platform desktop client, simple to set up.
  • NextChat / ChatGPT-Next-Web: web and desktop, supports self-hosting.
  • LobeChat: web client with a plugin ecosystem.
  • Page Assist / Sider: browser-extension sidebar LLMs.

Async tasks

For images, video and other long-running jobs, use the async task endpoints or the console's task feature to avoid public-gateway timeouts. After creating a task, poll its status by task ID, or configure a callback URL to receive the result.

Submit an image task
POST /v1/images/gpt-image-2/generation

# Model goes in the URL path; body is the same as the sync endpoint
# {"prompt": "...", "size": "1024x1024", "image_urls": [...]}
# Returns immediately: {"data":[{"status":"submitted","task_id":"task_xxx"}]}
Submit a video task
POST /v1/video/generations

# Put the model name in the request body's model field (OpenAI-compatible)
# {"model": "seedance-2.0", ...}
Query task / download result
# Image tasks: poll the generic task endpoint
GET /v1/tasks/{task_id}

# status is upper-case: NOT_START | SUBMITTED | QUEUED | IN_PROGRESS | SUCCESS | FAILURE
# When done, images are in data.result.image_urls (array; may be data URL/base64)

# Video tasks: use the video-specific endpoint
GET /v1/video/generations/{task_id}   # URL in data.result_url (a flat string)

Long-task tips

Video generation, image editing and Midjourney-style tasks usually take a while. Save the task id and handle the QUEUED, IN_PROGRESS, SUCCESS and FAILURE states separately - note the values are upper-case.

Image generation

Image generation uses the OpenAI-compatible synchronous endpoint POST /v1/images/generations; the model name goes in the request body's model field. gpt-image-2 takes a prompt to generate; add an image_urls to do image-to-image (editing). The response is synchronous, with the image in data[0].b64_json (base64 PNG).

Some models are async-only

Seedream, Flux, Imagen, Qwen Image, WAN, Z-Image, Midjourney and the official-channel (-official) models are async-only. Calling the synchronous /v1/images/generations endpoint returns a 400 telling you to switch. That is deliberate: the sync path would only ever return a task envelope, not an image. See the full list and usage in Async-only models at the end of this section.

Sync vs async (Official)

The gpt-image-2 above is synchronous (returns base64) but capped at ~1.5MP total. For true 1K / 2K / 4K resolution, more aspect ratios, and timeout-proof async jobs, use the official-channel model gpt-image-2-official — see “Official · async HD” at the end of this section.

gpt-image-2

General image model: text-to-image + image-to-image (editing); up to 16 reference images.

flux / imagen / seedream

For other image models, refer to what the marketplace shows.

ParameterTypeRequiredDescription
modelstringYesFixed: gpt-image-2.
promptstringYesImage description or edit instruction; Chinese or English.
image_urlsstring[]NoReference images for image-to-image: public URLs or base64 data URLs (mixable), up to 16.
sizestringNoPixel WxH sets only the aspect ratio (e.g. 1024x1024 square, 1536x1024 landscape); ratio strings like 16:9 are not recognized. Total output is fixed at ~1.5MP (~1254×1254); larger sizes / 4k do not yield more pixels.
nintegerNoNumber of images, default 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": "An orange cat on a windowsill at sunset, watercolor style",
    "size": "1024x1024"
  }'

For image-to-image (editing), use the same endpoint and add image_urls with your reference image (a public URL or a data:image/png;base64,... data URL; multiple allowed); prompt is the edit instruction.

Image-to-image (editing)
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": "Repaint this into a neon cyberpunk night scene, keep the cat as the subject",
    "image_urls": [
      "https://example.com/cat.png"
    ]
  }'
Response (synchronous)
{
  "created": 1783144062,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...<base64 PNG>" }
  ]
}

Tested notes

① The image is returned as base64 in data[0].b64_json; base64-decode it to get the PNG. ② A single image takes ~40–60s, close to Cloudflare's 100s limit; for slower/larger jobs use the async task endpoint to avoid timeouts (see “Async tasks”). ③ size only takes effect in pixel format (e.g. 1536x1024); ratio format (16:9) is currently ignored.

Seedream 5.5 · generation and layer decomposition

Use model seedream-5-5 in the request body's model field. Submit with POST /v1/images/tasks and poll with the same key at GET /v1/images/tasks/{task_id}. Generation and layer decomposition use the same model.

FieldDescriptionExample
promptRequired for normal generation; optional for layer decomposition.string
image_urls0–10 reference images for normal generation; exactly 1 for layer decomposition.["https://.../source.png"]
nOnly 1 is supported.1
sizeNormal generation: accepts 1K / 1.5K / 2K (default 2K), aspect ratios such as 1:1, or exact pixel dimensions; exact dimensions require an area of 921600–4624220 pixels and an aspect ratio of 1/16–16, and must not be combined with resolution. Layer decomposition: only auto / 1K / 1.5K / 2K; ratios and exact pixel dimensions are not accepted.1K
output_formatGeneration supports png / jpeg; choose png for a transparent background. Layer outputs are transparent PNGs.png
backgroundUse transparent for transparent PNG generation. For decomposition, omit this field entirely, including auto.transparent
layer_decompositionSet true to decompose an image into layers.true
layer_decomposition_options.max_images2–100, including the first base image; default 30. Sets the maximum number of returned images.2
layer_decomposition_options.text_recognitionOptional. Set true to request OCR; text recognition is not guaranteed.true
Generation · transparent 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"
  }'
Layer decomposition · 1K, up to 2 images including 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}
  }'

Images and layer metadata

Poll using data.task_id from the submission response. On SUCCESS, image URLs remain at data.data.data.result.images[].url[]; the first image is the base. When layers metadata is present, it can include z_index, name, bounding_box and OCR information. Metadata may be absent, so do not require layers to retrieve images. A transparent PNG's dimensions may differ from its bounding_box: scale and position it to that box, then order by z_index for compositing. OCR may return no text; PSD and ZIP exports are not promised.

Reservation and wait time

The initial pre-charge reserves an estimated upper amount; completion settles actual usage, refunding excess or charging any shortfall. It is not a fixed per-image price. Decomposition may take around 13 minutes. Keep polling the original task_id instead of resubmitting while waiting. Result links are temporary; download and save them promptly.

Seedream

For Seedream 5.5, use the dedicated section above. The parameters below apply to four earlier models: seedream-5-0-pro (the strongest, with 1K/2K resolution tiers), seedream-5-0-lite, seedream-4-5 and seedream-4-0.

FieldDescriptionExample
modelOne of the four. Only seedream-5-0-pro has resolution tiers; the rest have a single price.seedream-5-0-pro
promptRequired. The image description.string
sizeAspect ratio: 1:1 / 16:9 / 9:16 / 4:3 / 3:4 and more.1:1
resolutionOutput resolution. seedream-5-0-pro supports 1K / 2K, and the price follows the tier.2K
image_urlsReference images for image-to-image.["https://...jpg"]

Nano Banana

The nickname for Google's Gemini image models: strong semantic understanding, character consistency and text rendering. Available: nano-banana-pro (Gemini 3 Pro Image, supporting 1K/2K/4K) and nano-banana-2 (Gemini 3.1 Flash Image).

FieldDescriptionExample
modelnano-banana-pro (quality-first) or nano-banana-2 (speed and price first).nano-banana-pro
promptRequired. Up to about 1000 characters.string
sizeAspect ratio: auto / 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 21:9 and more.auto
resolutionOutput resolution. nano-banana-pro supports 1K / 2K / 4K, with 4K priced higher.1K
image_urlsReference images for image-to-image, up to 14, as URLs or base64.["https://...jpg"]
nNumber of images. Currently only 1 is supported.1

Midjourney

Midjourney uses the async task API: submit to POST /v1/images/tasks to get a task_id, then poll GET /v1/images/tasks/{task_id}. One generation returns four images (Midjourney's 2x2 grid is split into four URLs).

Do not use the synchronous image endpoint

Midjourney is async-only. Calling the synchronous /v1/images/generations endpoint is rejected outright with a hint to switch. That is deliberate: the sync path would return a task envelope instead of an image while still charging you.
FieldDescriptionExample
modelAlways midjourney.midjourney
promptRequired. Supports native Midjourney flags such as --ar 16:9 (ratio), --q .25 (low quality to save cost) and --niji (anime style).--ar 16:9 --q .25
image_urlsReference images for image-to-image. You can also put the image URL at the start of the prompt, the native Midjourney way.["https://...jpg"]
speedSpeed mode: relax / fast / turbo, default relax.relax
versionModel version, e.g. v8.2 / v8.1 / v7 / v6.1.v8.2
Text-to-image
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"
                }'
Image-to-image
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 Official · async HD

gpt-image-2-official is the OpenAI official-channel GPT Image 2, with 1K / 2K / 4K resolution tiers, 15 aspect ratios, up to 4 images per call and up to 16 reference images. It is an async task: submit POST /v1/images/tasks to immediately get a task_id, then poll GET /v1/images/tasks/{task_id} for the result.

Submit & poll paths

Submit POST /v1/images/tasks with the model name in the request body's model field. Poll GET /v1/images/tasks/{task_id}; once the status reaches SUCCESS, the image URLs live at data.data.data.result.images[].url[] in the response (url is an array). ⚠️ These image URLs expire after ~24h, so download and store them promptly.
FieldDescriptionExample
modelFixed: gpt-image-2-official.gpt-image-2-official
promptImage description or edit instruction, Chinese or English (required)."a starry-sky castle"
sizeAspect ratio (NOT pixels). 15 supported, e.g. 1:1 / 16:9 / 9:16 / 4:3 / 3:4.16:9
resolutionResolution tier 1k / 2k / 4k. If omitted, the upstream defaults to the lowest tier.2k
qualityQuality low / medium / high; defaults to low if omitted. Together with resolution it drives the price (see below) — higher quality costs more.low
nNumber of images, 1–4, default 1.1
image_urlsReference images for image-to-image / editing: public URLs or base64 data URLs, up to 16.["https://...png"]
Submit (text-to-image)
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": "An ancient castle beneath a starry sky, cinematic",
    "size": "16:9",
    "resolution": "2k",
    "quality": "low"
  }'
Poll task
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
            }
          ]
        }
      }
    }
  }
}

Billing & notes

Billed by quality × resolution, and the spread is large: low quality + low resolution (low / 1k) is cheapest, high quality 4K (high / 4k) the most expensive — see the model marketplace for exact prices. When a task finishes we check it against actual usage once; with many reference images or a complex image, actual usage can exceed the tier price, and the difference is charged automatically. While the status is SUBMITTED / IN_PROGRESS, poll every 3 to 5 seconds; it usually completes in 20 to 60 seconds. For image-to-image, add image_urls (publicly accessible HTTPS image URLs so the upstream can fetch them).

GPT Image 2.5 · tiered HD

GPT Image 2.5 comes in two variants: gpt-image-2.5-flare for fast everyday generation and gpt-image-2.5-sunburst for higher editing precision. Both are async tasks: submit POST /v1/images/tasks and poll GET /v1/images/tasks/{task_id}. Both accept reference images.

FieldDescriptionExample
modelRequired. Either variant.gpt-image-2.5-flare
promptRequired. The description of the image.a white ceramic mug
qualityQuality tier; it drives the price directly, see the table below. If you omit it, the upstream picks a tier from the content itself, possibly a high one, and you are billed for actual usage. Pass it explicitly if you want a predictable price.low
resolutionResolution tier 1k / 2k / 4k, multiplied with quality for pricing. Omitting it is the same as 1k.1k
sizeAspect ratio such as 1:1, 16:9 or 3:2.1:1
image_urlsReference images; providing them switches to image-to-image editing. Reference images count as billable input, so editing costs more than text-to-image at the same tier.["https://.../a.jpg"]
nNumber of images, default 1, billed per image.1

Price multiplies across tiers, and the spread is large

Taking low + 1k as the 1x baseline: quality medium is 2.25x, high 9x, xhigh 16x and max 36x, while resolution 2k is 2x and 4k 3.4x, and the two multiply. So max + 4k lands around 122x the baseline. Check your tier before running a batch, and see the model marketplace for exact prices.

The tier price is a pre-charge; tasks settle on actual usage

The upstream bills on actual usage: omitting quality, adding reference images, a large size or a long prompt all push an image's actual usage above the tier price you picked. So we pre-charge by tier on submit and settle on actual usage when the task finishes. You pay whichever of the two is higher, and any shortfall is charged automatically as a separate entry in your usage logs (labelled 「按实际消耗补扣」). For example, a sunburst edit with one reference image and no quality set uses about 10x the low-tier price. Pass quality and resolution explicitly for batch jobs.
Submit (cheapest tier: pass low + 1k explicitly)
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": "a plain white ceramic mug on a white table, product photo",
    "size": "1:1",
    "quality": "low",
    "resolution": "1k"
  }'
Editing (with a reference image)
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": "replace the background with a clean white studio",
    "image_urls": ["https://example.com/source.jpg"],
    "quality": "low"
  }'
# Use sunburst for editing. Reference images are billable input, so this costs
# more than text-to-image at the same tier. Polling works the same as the other
# async models, and result URLs expire after about 24 hours.

GPT Image 2.6 · tiered generation

GPT Image 2.6 comes in two variants: gpt-image-2.6-flare for speed-first everyday generation and gpt-image-2.6-sunburst for workflows that need more detail and editing precision. Both use the async task API: submit POST /v1/images/tasks and poll GET /v1/images/tasks/{task_id}. Both accept reference images and image editing.

FieldDescriptionExample
modelRequired. Either variant.gpt-image-2.6-flare
output_formatpng / jpeg / webp / gif / svg; see below for GIF / SVG parameters and settlement rules.png
promptRequired. The description of the image.a white ceramic mug
qualityQuality tier low / medium / high / xhigh / max; auto is also accepted. If omitted, a tier is chosen from the content. Pass low explicitly; final charges still follow actual usage.low
resolutionResolution tier 1k / 2k / 4k, multiplied with quality for pricing. Omitting it is the same as 1k.1k
sizeAspect ratio such as 1:1, 16:9 or 3:2; exact pixel dimensions are also accepted.1:1
image_urlsReference images; providing them switches to image-to-image editing and counts as billable input.["https://.../a.jpg"]
nNumber of images, default 1, billed per image.1

2.6 tiers are flatter than 2.5

For normal image generation, taking low + 1k as the 1x baseline: quality medium is 1.76x, high 2.14x, xhigh 3.8x and max 8.55x, while resolution 2k is 2x and 4k 3.4x, and the two multiply. Do not reuse the 2.5 multipliers. See the model marketplace for exact prices; GIF / SVG settle under the actual-usage rules below.

Tier pre-charge, settled on actual usage

Normal PNG / JPEG / WebP generation pre-charges by tier and settles actual usage on completion, charging any shortfall. Reference images, canvas size and prompt length affect usage. Pass quality and resolution explicitly for batch jobs. GIF / SVG reservation and settlement rules are below.
Submit (cheapest tier: pass low + 1k explicitly)
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 plain white ceramic mug on a white table, product photo",
    "size": "1:1",
    "quality": "low",
    "resolution": "1k"
  }'

Animated GIF · output_format: gif

FieldDescriptionExample
gif.frame_count2–16 frames; default 9.2
gif.frame_duration_msAt least 20 milliseconds per frame; default 200.200
sizeauto or pixel dimensions; default 512x512. Ratios such as 1:1 are not accepted.512x512
image_urls / nUp to 16 reference images; n is 1–4. Mask, markup and compression parameters are unsupported.1
GIF · minimal two-frame example
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
  }'

Vector SVG · output_format: svg

SVG first generates an intermediate image, then an author model produces the vector content. n must be 1, and image_urls accepts up to 16 references. Mask, markup and compression parameters are unsupported. complexity is a top-level field; the example uses low. Put author settings inside svg, using gpt-5.4-mini and reasoning.effort: low.

SVG · mini author model
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 settle on actual usage

The pre-charge reserves an estimated upper amount; actual usage at completion refunds excess or charges any shortfall. SVG includes intermediate-image generation and author-model tokens. The author is billable, and SVG has no fixed per-image price. Reasoning tokens are already included in output tokens: do not add them again. SVG tasks may take around 22 minutes; GIF uses the normal task polling flow. Keep polling the original task_id instead of resubmitting.
GIF / SVG polling and download
curl https://api.wanapis.com/v1/images/tasks/task_xxx \
  -H "Authorization: Bearer $WANAPIS_API_KEY"
# Use data.task_id from submission; poll every 3–5 seconds.
# On SUCCESS read data.data.data.result.images[].url[].
# File links are temporary; download and save them promptly.

Async-only models

The image models below use an async task API. Always submit with POST /v1/images/tasks and poll GET /v1/images/tasks/{task_id}. Do not use /v1/images/generations. Normal image tasks pre-charge per image and reconcile actual usage on completion, charging any shortfall. Seedream 5.5 and GPT Image 2.6 GIF / SVG reserve an estimate and refund excess or charge a shortfall; see their dedicated sections.

FieldDescriptionExample
SeedreamIncludes 5.5 generation and layer decomposition plus Lite / Pro; see the dedicated 5.5 parameters.seedream-5-5 / seedream-5-0-lite / seedream-5-0-pro
FluxThe FLUX.2 family, including Kontext for image editing.flux-2-pro / flux-kontext-pro
ImagenGoogle Imagen 4.imagen-4.0-apimart
Qwen ImageQwen image generation; the Pro tier has finer detail.qwen-image-2.0 / qwen-image-2.0-pro
WANWAN 2.7 image models; the Pro tier renders at higher resolution.wan2.7-image / wan2.7-image-pro
Z-ImageLightweight and fast, the cheapest tier.z-image-turbo
MidjourneyReturns four images per generation; see the Midjourney subsection above for its parameters.midjourney
OfficialOpenAI official channel with 1K / 2K / 4K support; see the subsection above for its parameters.gpt-image-2-official

Request parameters

Follow the dedicated sections for Seedream 5.5, Midjourney and Official models; the fields below apply to the remaining models. GPT Image 2.6 GIF / SVG also have dedicated parameters and their own size and settlement rules.

FieldDescriptionExample
modelRequired. The model name, from the table above.qwen-image-2.0
promptRequired. The description of the image, in any language. Leaving it empty returns a 400.a white ceramic mug
sizeOptional. Controls the frame. Support for pixel format versus ratio format varies by model — see the table below.16:9
image_urlsOptional. Reference images; providing them switches to image-to-image, rewriting the source per your prompt while keeping the subject and composition. Accepts public HTTPS image URLs or inline data:image/png;base64,... images.["https://.../a.jpg"]
nOptional. Number of images, default 1. Billed per image: n=2 costs twice as much and returns two URLs.1

How size actually behaves

Upstreams do not handle size consistently. The following is measured behaviour; omitting size falls back to each model's default:

FieldDescriptionExample
Qwen ImageBoth formats work. Pixel format renders at exactly the size you ask for, and ratio format is accepted too. Default 1024x1024.1280x720 → 1280×720 / 16:9 → 1280×720
Seedream 5.0 Lite (excluding 5.5)Only ratio format is honoured; pixel format is ignored and falls back to the default 2048x2048. Pass a ratio such as 16:9 to change the frame.16:9 → 2848×1600 / 1792x1024 → 2048×2048
Other modelsFor Flux / Imagen / WAN / Z-Image, prefer ratio format and trust the dimensions of the image you actually get back.16:9

quality and resolution do nothing for these models

Only the Official (-official) models have quality / resolution tiers and are priced by tier. The upstreams behind the models above ignore both fields: passing quality: "high" changes neither the image nor the price, so there is no reason to send it. Use size to change the frame instead.

If your key restricts models, allow the model for polling too

If your key has a model allow-list enabled, polling GET /v1/images/tasks/{task_id} resolves the model name recorded on the task itself. So as long as the model you submitted with is on the allow-list, polling works with no extra configuration. If you still get a 403, check that you are submitting and polling with the same key.
Text-to-image
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": "a plain white ceramic mug on a white table, product photo",
    "size": "16:9"
  }'
# => {"code":"success","data":{"status":"submitted","task_id":"task_xxx"}}
Image-to-image / reference image
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": "turn this photo into a watercolor painting",
    "image_urls": ["https://example.com/source.jpg"]
  }'
# The reference image must be reachable from the public internet; inline
# data:image/png;base64,... images work too.
# For editing tasks, flux-kontext-pro stays closer to the source image.
Poll for the result
curl https://api.wanapis.com/v1/images/tasks/task_xxx \
  -H "Authorization: Bearer $WANAPIS_API_KEY"
# Poll every 3-5 seconds; most jobs finish in 10-30 seconds.
# Once status is SUCCESS, image URLs live at data.data.data.result.images[].url[]
# Those URLs expire after ~24h, so download and store them promptly.

Video generation

Video generation lives under the video capability category, with per-model setup guides for Seedance 2.5/2.0, Veo 3.1, Kling, Vidu Q3, HappyHorse and more. All video models use async task mode by default: submit POST /v1/video/generations (model name in the request body's model field), then poll for the task result.

Seedance 2.0

ByteDance Doubao video generation: text-to-video, image-to-video, first/last frame and reference assets.

Veo 3.1

Google. 4K/60fps with synced audio in one pass, the most polished output. Three tiers: quality / fast / lite.

MiniMax H3

Hailuo 03 with native audio at 480p / 768P / 1080p / 2K. Multiple images, first/last frames, video/audio references, regeneration and prompt optimization follow current capabilities. See the H3 section for protocol and pricing examples.

Kling

Kuaishou. The most natural human motion. Two generations (v3, v2-6) with pro / sound tiers.

Vidu Q3

Shengshu. Good value, with pro / turbo / mix variants.

HappyHorse 1.0

Alibaba ATH, released April 2026, ranks near the top overall.

Grok Video

xAI. Fixed 6-second clips at the lowest price.

All video models and parameters

The table below lists the video models currently on sale. They all use the same async endpoint POST /v1/video/generations; only the model name and the supported parameter tiers differ. Prices follow the model marketplace, where per-second models show a price for each resolution.

FieldDescriptionExample
seedance-2.5ByteDance's latest generation. 480p / 720p / 1080p, 4-15s, best quality and consistency.per second
seedance-2.0Standard version, quality-first. 480p / 720p / 1080p, 4-15s.per second
seedance-2.0-fastFast version for drafts and batch previews.per second
seedance-2.0-miniLightweight and cheapest, good for high-volume drafts.per second
veo3.1-qualityGoogle Veo 3.1 quality tier, supports 4K and synced audio.per call
veo3.1-fastVeo 3.1 fast tier.per call
veo3.1-liteVeo 3.1 lite tier, the cheapest.per call
minimax-h3MiniMax Hailuo 03 at 480p / 768P / 1080p / 2K, 4–30s (2K up to 15s). Legacy single-image requests remain compatible; typed content carries multiple references. See the H3 section and live capabilities for support and pricing.output + references + optional IR
kling-v3Kuaishou Kling v3, natural human motion, with pro / sound / 4k tiers.per second
kling-v2-6Kling 2.6, the value tier.per second
viduq3Shengshu Vidu Q3, with pro / turbo / mix variants. 540p / 720p / 1080p.per second
happyhorse-1.0Alibaba ATH, released April 2026. 720p / 1080p.per second
grok-videoxAI Grok, 6 seconds only, at the lowest price. Duration is required (seconds or duration, and the value must be 6); omitting it gets a 400 from the upstream.per second
grok-imagine-videoxAI Grok's proper video model and a step up from grok-video: any length from 1 to 15 seconds, selectable 480P/720P, a native audio track, and image-to-video support.per second
grok-imagine-video-1.5xAI's newest video model (Aurora-2). Everything grok-imagine-video does, plus 1080P, with audio generated in the same pass as the picture. Priced by resolution tier.per second

Some models accept two parameter styles

Parameter locations and defaults differ by model. Follow each model's table rather than duplicating fields at the top level and in metadata, or assuming unknown fields are ignored. H3 validates strict types; resolution, ratio and seconds belong at the top level, and duplicate aliases must agree.

This fallback advice and these defaults do not apply to minimax-h3. Standard H3 defaults to 4 seconds, 768P and 9:16; conflicting duplicate parameters return 400. Follow the H3-specific table below.

Kling

Kuaishou's Kling has the most natural human motion. Note its parameters differ from Seedance: quality is selected with mode (not resolution), and the aspect ratio uses aspect_ratio (not size).

FieldDescriptionExample
modelkling-v3 or kling-v2-6.kling-v3
promptRequired. The video prompt.string
negative_promptNegative prompt to exclude unwanted elements.string
modeQuality tier: std / pro / 4k. Price rises with the tier.std
durationDuration in seconds, 3-15, default 5.5
aspect_ratioAspect ratio: 16:9 / 9:16 / 1:1, default 16:9.16:9
image_urlsReference images for image-to-video.["https://...jpg"]
audioWhether to generate synced audio, default false.false
multi_shotMulti-shot mode, used with shot_type and multi_prompt.false
watermarkWhether to add a watermark.false
Text-to-video
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 supports 4K and synced audio in one pass, with the most polished output. Three tiers map to three model names: veo3.1-quality / veo3.1-fast / veo3.1-lite. These three are billed per call (not per second), so duration does not change the unit price.

FieldDescriptionExample
modelveo3.1-quality / veo3.1-fast / veo3.1-lite.veo3.1-fast
promptRequired. The video prompt.string
resolutionOutput resolution: 720p / 1080p / 4k; price rises accordingly.1080p
durationDuration in seconds. Billed per call, so duration does not change the unit price.5
image_urlsReference images for image-to-video.["https://...jpg"]

MiniMax H3 (Hailuo 03)

H3 generates native audio at 480p / 768P / 1080p / 2K. Legacy text/single-image input remains compatible; content describes multiple images, first/last frames and video/audio references. Check current capabilities for enabled operations; missing settings do not mean free or supported.

Complete H3 guide: uploads, generation, polling, downloads, IR and regeneration

Defaults and strict input

Defaults are 4 seconds, 768P, 9:16, fast_mode=false and context_ir_enabled=true. Duration is 4–30 seconds, or up to 15 at 2K. seconds/duration accepts integer numbers or digit strings; boolean fields accept only true/false. Unknown fields, duplicate JSON keys and conflicting aliases are rejected. Do not mix content with legacy prompt/image inputs.
FieldDescriptionExample
modelRequired public model ID.minimax-h3
prompt / contentUse legacy prompt with an optional image, or a typed content array. Do not mix content with legacy media aliases.text / image_url / video_url / audio_url
resolution480p / 768P / 1080p / 2K. A tier is not a guarantee of exact output pixels.768P
seconds / durationInteger 4–30; 2K up to 15. An integer number or digit string is accepted. Conflicting aliases are rejected.4
ratio21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16; adaptive is available only for supported media requests.9:16
fast_modeJSON boolean. true doubles output and billable reference material fees; it does not double IR.false
context_ir_enabledJSON boolean for built-in prompt optimization. Disable when deliberately reusing a separately optimized prompt.true
input_referenceLegacy single-image input: a URL string or {image_url: URL}. It is a reference image; do not assume it enforces a first frame.{"image_url":"https://…"}
content[].roleImages: reference_image / first_frame / last_frame. Video: reference_video. Audio: reference_audio.reference_image
media sourceExactly one of url or asset_id inside image_url / video_url / audio_url. Use an owned upload handle for local files.{"asset_id":"asset_…"}
sizeLegacy tier/orientation selector. Prefer resolution + ratio. Conflicting selections return 400.1280x720
Minimal text request
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
}'
Multiple references: replace with your uploaded asset IDs
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"
      }
    }
  ]
}'

References and separate operations

Up to 9 images, 3 reference videos and 3 reference audio clips. Keep combined reference video at 15 seconds or less; single-clip tolerance follows capabilities. Audio totals at most 15 seconds. Upload local files with POST /v1/videos/assets and bind subsequent uploads using binding_asset_id. Each source has exactly one of url or asset_id. Use explicit frame roles; legacy input_reference is a reference image, not an enforced first frame.

Eligible successful 768P originals can create 2K jobs with POST /v1/videos/{id}/regenerations. mode=content requires the original final prompt and all original references; use mode=source only when listed as available. This is not arbitrary-video upscaling. POST /v1/videos/prompt-optimizations returns a text task. Explicitly disable context_ir_enabled when using its result to avoid another optimization charge.

Base retail rates (CNY, group multiplier 1)

FieldDescriptionExample
480pOutput and reference video CNY 0.078/secondper second
768POutput and reference video CNY 0.117/secondper second
1080pOutput and reference video CNY 0.182/secondper second
2KOutput and reference video CNY 0.195/secondper second

Itemized reservation and frozen-rate settlement

Normal total = [output rate × output seconds + reference-video rate × ceil(combined input seconds) + CNY 0.065 × max(images−5,0)] × duration multiplier × priority multiplier + IR; apply the effective group ratio to the entire amount. Duration multiplier 2 at 16–30s and priority multiplier 2 for fast=true apply to output and billable materials. Default IR is CNY 0.065 per request and is not doubled. The first five images and audio add no material fee. References of 1.2 + 1.2 seconds are billed as 3 combined seconds, not 4 from rounding each clip.

Reference-video requests reserve the maximum possible input charge, then refund the difference using verified usage and rates frozen at submission. billing.status=pending_usage means charged_quota remains unknown; reserved_quota is not final spending. Accepted failed tasks receive a full credit refund. Without paid references, 4s at 768P costs CNY 0.533 including default IR, or 0.468 with IR disabled.

2K regeneration is charged separately at CNY 0.078/output second + CNY 0.078/original reference-video billable second + CNY 0.052/image beyond five, then the group multiplier. Do not count the base clip again as reference input or inherit the original IR/duration/priority surcharges. Standalone IR has a fixed per-operation fee. Live marketplace and /api/pricing prices and capabilities take precedence.

OpenAI-style query
curl https://api.wanapis.com/v1/videos/task_example \
  -H "Authorization: Bearer $WANAPIS_API_KEY"
Authenticated download
curl https://api.wanapis.com/v1/videos/task_example/content \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  --output result.mp4

For OpenAI-style queries, read metadata.url after top-level status=completed. Generic GET /v1/video/generations/{id} instead uses data.status=SUCCESS and data.result_url. Video completion and billing settlement are independent. Query known IDs after an uncertain POST instead of blindly resubmitting. Closing the page does not cancel accepted work. There is no universal 24-hour result-retention guarantee; save results promptly.

Vidu Q3 / HappyHorse / Grok Video

FieldDescriptionExample
viduq3Shengshu. Resolutions 540p / 720p / 1080p, with viduq3-pro (higher quality), viduq3-turbo (cheaper) and viduq3-mix variants.per second
happyhorse-1.0Alibaba ATH, released April 2026. Supports 720p / 1080p.per second
grok-videoxAI. 6 seconds only, at the lowest price, and it does support image-to-video. Duration is required: pass either seconds: "6" (string) or duration: 6 (number) - both work, but omitting both gets a 400 duration required from the upstream. Reference images go in reference_images (an array of URLs); note it does not accept input_reference and will 400 on it. size is not honoured: text-to-video comes back 720x405 and image-to-video 1280x720.per second
grok-imagine-videoxAI Grok's proper video model. Length 1-15 seconds (14 steps); resolution takes 480p / 720p and is actually honoured (measured: 480p returns 848x480); ratios 1:1 / 16:9 / 9:16 / 3:2 / 4:3 / 3:4 / 2:3, and clips carry a native audio track. Image-to-video uses reference_images here too. Pass the duration explicitly: leave it out and the upstream defaults to 8 seconds and bills for 8.per second
grok-imagine-video-1.5xAI's newest video model (Aurora-2). Length 1-15 seconds; resolution takes 480p / 720p / 1080p and all three are real (measured: 848x480, 1280x720 and 1920x1088 respectively), each with an aac audio track. Image-to-video uses reference_images here too. Billing is tiered by resolution: 480p is the base, 720p costs 1.25x and 1080p 1.875x, then multiplied by duration. Pass the duration explicitly - leave it out and the upstream defaults to 8 seconds and bills for 8.per second

grok-video needs the duration spelled out

It only renders 6-second clips, but the duration is still required: the upstream will not default it for you. seconds takes a string and duration takes a number; either works, but leaving both out returns 400 duration required. For image-to-video pass reference_images (an array of publicly reachable HTTPS image URLs); input_reference - the Sora-style field - is rejected with a 400 here. It is also a web-proxy upstream and occasionally fails with grok auth failed; those failures are refunded automatically, so just retry.
grok-video, 6-second clip
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 image-to-video (reference image)
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 (choose length and resolution, with audio)
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, image-to-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-1.5",
    "prompt": "slow cinematic push in",
    "duration": 6,
    "resolution": "1080p",
    "reference_images": ["https://example.com/first.jpg"]
  }'

Task status and result

Generic GET /v1/video/generations/{id} uses the data fields below. OpenAI-style GET /v1/videos/{id} instead uses top-level status and metadata.url. Status spelling and URL location differ; parse the selected endpoint and save the public task ID after acceptance.

FieldDescriptionExample
data.statusThis table describes the generic format: NOT_START / SUBMITTED / QUEUED / IN_PROGRESS / SUCCESS / FAILURE. OpenAI-style queries use top-level queued/in_progress/completed/failed.SUCCESS
data.result_urlThe video URL - a flat string field, neither an array nor nested under metadata. Reading the wrong field typically looks like the task being stuck in processing forever when it actually finished upstream.https://.../content
data.progressProgress - a string including the percent sign, not a number."100%"
data.fail_reasonFailure reason as a string; an empty string when the task succeeded.string
data.submit_time / start_time / finish_timeSubmit / start / finish timestamps in seconds; subtract them to get queue time and render time.1790087400
data.quotaQuota recorded for the task. It may be a reservation before completion or while billing is pending. For H3 final billing, read billing.charged_quota. Divide quota by 500000 for CNY.234000
data.dataModel-specific supplemental results. Their structure differs by model; prefer the documented public status and result fields.object

Save completed results promptly

Result retention varies by task; there is no universal 24-hour guarantee. Use expires_at when provided and do not invent an expiry when it is absent. Downloads remain authenticated to the owner. Save results to your own storage for long-term retention.

Seedance 2.0

Seedance 2.0 is ByteDance's Doubao video generation model, suited to text-to-video, image-to-video, first/last-frame transitions and reference-driven video tasks. WanAPIs wraps these long-running calls in an async task API: submitting a task returns a task_id immediately, then you poll /v1/video/generations/{task_id} for the result.

Submit path (OpenAI-compatible)

The WanAPIs video submit endpoint is POST /v1/video/generations (singular video), with the model name in the request body's model field, not the URL. Poll GET /v1/video/generations/{task_id}; when done, download the video via GET /v1/videos/{task_id}/content.

Request parameter conventions (important)

Prefer the unified top-level fields: duration duration (number, 4-15s), ratio size, resolution resolution, audio generate_audio, last frame return_last_frame, seed seed. Put reference images in image_urls (up to 9 including frames); when roles are needed use image_with_roles (each item has url + role: first_frame / last_frame / reference_image); the two are mutually exclusive. Reference videos go in video_urls, reference audio in audio_urls. Older clients may still send seconds / images / metadata.content; the gateway normalizes them, but new code should not use them.

seedance-2.5

Latest generation with the best quality and consistency; the priciest per second.

seedance-2.0

Standard version, quality-first, suited to production assets.

seedance-2.0-fast

Fast version, good for drafts, batch previews and low-latency scenarios.

seedance-2.0-mini

Lightweight and cheapest, good for high-volume drafts.

Text-to-video
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": "An orange cat stretches by the window at dawn, slow push-in, soft natural light, cinematic",
    "duration": 5,
    "size": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'
Image-to-video
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": "Have the person in the photo turn naturally toward the camera, breeze moving their hair, background stays consistent",
    "image_urls": ["https://example.com/portrait.jpg"],
    "duration": 5,
    "size": "adaptive",
    "resolution": "720p"
  }'
First/last-frame transition
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": "Smoothly transition from a daytime city street to a neon-lit night street, camera moving forward",
    "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"}
    ]
  }'

Local asset upload

The upstream only accepts public URLs. To use a local image, video or audio file, first call POST /v1/media (multipart), then pass the returned url into image_urls / video_urls / audio_urls. Uploading is free and does not create a task; the URL expires after 6 hours by default, so upload again after that.

Upload
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]"
Upload response
{
  "id": "media_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "url": "https://api.wanapis.com/v1/media/media_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx?expires=1790000000&signature=xxxxxxxx",
  "media_type": "image",
  "bytes": 48213,
  "expires_at": 1790000000
}

Upload limits

Per-file limit: image 30 MiB, video 31 MiB, audio 15 MiB; request body limit 32 MiB. The returned URL is signed and intended for the upstream; it is not a permanent asset library. H3 uses a different endpoint, POST /v1/videos/assets, which returns an asset_id; the two ID types cannot be mixed.
FieldDescriptionExample
promptVideo prompt. Describe the subject, action, scene, camera, style and constraints."cinematic dolly-in"
durationVideo duration in seconds, top-level number, 4-15. Defaults to 5. The legacy seconds field is still accepted.5
sizeVideo ratio, top-level. 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / adaptive.16:9
resolutionOutput resolution, top-level. 480p / 720p / 1080p / 4k; the supported range varies by model.720p
image_urlsReference image array, up to 9 including frames. Mutually exclusive with image_with_roles.["https://...jpg"]
image_with_rolesReference images with roles, each {url, role}; role is first_frame / last_frame / reference_image.[{url, role}]
video_urlsReference video array, up to 3; combined duration must be over 1.8s and under 15.2s, and cannot be combined with first/last frames.["https://...mp4"]
audio_urlsReference audio array, up to 3, total length at most 15s; requires a reference image or video and cannot be combined with first/last frames.["https://...mp3"]
generate_audioWhether to generate synced audio, top-level boolean. Enabling it may take longer.true
return_last_frameWhether to return the last frame, top-level boolean, handy for continuous shots.true
seedRandom seed, top-level integer, for reproducible results.42

Submit response

response
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "seedance-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1780000000
}

Poll task

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"
    }
  }
}

Production tips

While the task status is QUEUED or IN_PROGRESS, poll every 5 to 10 seconds; the terminal states are SUCCESS and FAILURE (note they are upper-case). On failure, record the task id, the model name and fail_reason. Assets can be public HTTPS URLs, or you can upload local files with POST /v1/media and use the returned URL.

Music generation

Music generation is powered by the Suno model in async task mode: submit POST /v1/music/generations to immediately get a task_id, then poll GET /v1/music/tasks/{task_id} for the result. Each run returns 2 candidate songs with directly playable audio, cover art and lyrics.

Submit & poll paths

Submit POST /v1/music/generations with the model name in the request body's model field (currently suno). Poll GET /v1/music/tasks/{task_id}; once the status reaches SUCCESS, the songs live at data.data.data.result.music[] in the response — each carrying an audio_url (a directly playable / downloadable mp3), a cover and lyrics.

Two modes

Inspiration mode custom: false: pass a single prompt description and the model writes the lyrics and arrangement for you. Custom mode custom: true: use prompt as the lyrics, plus style for the style and title for the title. Both modes accept instrumental: true to produce an instrumental (no vocals).
Inspiration mode
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": "late-night city lo-fi piano with rain"
  }'
Custom mode (lyrics + style)
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
  }'
FieldDescriptionExample
modelMusic model name; currently suno.suno
versionSuno version (required). v3.5 / v4 / v4.5 / v4.5+ / v5 / v5.5; newer is higher quality.v5
customMode switch. false = inspiration (prompt only); true = custom (lyrics + style).false
promptInspiration mode = music description; custom mode = lyrics. May be empty when instrumental is true."lo-fi piano"
instrumentalWhether to produce an instrumental (no vocals); works in both modes.true
titleSong title (custom mode only)."City Lights"
styleStyle / tags (custom mode only), e.g. lo-fi, chill, piano."lo-fi, chill"
vocal_genderPreferred vocal gender (optional). male / female.female
negative_tagsNegative style tags to exclude unwanted styles (custom mode only)."heavy metal"

Submit response

response
{
  "code": "success",
  "data": {
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "submitted"
  }
}

Poll task

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"
            }
          ]
        }
      }
    }
  }
}

Production tips

While the status is SUBMITTED / IN_PROGRESS, poll every 3 to 5 seconds; it usually completes in 30 to 120 seconds. audio_url is an upstream-hosted mp3 you can feed straight to an <audio> element without re-proxying. On failure the status is FAILURE, with the reason in data.fail_reason.

Billing & quota

WanAPIs bills by model ratio and actual tokens or tasks. Text models are charged for input and output separately; task-style models are usually billed per call or per spec.

FieldDescriptionExample
Input pricemodel_ratio × CNY 2 / 1M tokensinput_tokens
Output pricemodel_ratio × completion_ratio × CNY 2 / 1M tokensoutput_tokens
Quota unitQuota is anchored to CNY. Reconcile reservations, charges and refunds in the logs; a display symbol does not change this conversion.CNY 1 = 500,000 quota

Errors & retries

The API returns standard HTTP status codes. GET queries may use limited backoff for 429 and temporary 5xx; fix parameters, authentication or permissions for 400/401/403. If a charged video/image POST times out or has an uncertain outcome, query known task/request IDs before resubmitting to avoid duplicate paid work.

FieldDescriptionExample
401API key missing or invalidCheck the Authorization header
429Rate limit or quota protection triggeredLower concurrency or switch group
503Upstream or system overloadedWait and retry with backoff

Migration

When migrating from the official OpenAI or another aggregator, you usually keep the SDK and request structure and only swap these two:

Environment variables
OPENAI_API_KEY=$WANAPIS_API_KEY
OPENAI_BASE_URL=https://api.wanapis.com/v1

Then change the model ID to one available in the WanAPIs marketplace. Before launch, make 10 to 20 requests in a low-concurrency environment to confirm the response format, token counts and charges match expectations.

Support

For channel, billing, model or response-format issues, contact support with the request time, model ID, request id and error message.