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
- Create an accountOpen the console, create an account and verify your email.
- Create an API keyGenerate a key on the Tokens page and set per-project quota.
- Swap the Base URLPoint your OpenAI SDK baseURL to https://api.wanapis.com/v1.
- Pick a modelChoose a model ID from the marketplace or pricing page.
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.
| Field | Description | Example |
|---|---|---|
| Base URL | OpenAI-compatible API root | https://api.wanapis.com/v1 |
| Header | Request auth | Authorization: Bearer sk-... |
| Content-Type | JSON body | application/json |
Key management
Chat Completions
Compatible with /v1/chat/completions — for most existing OpenAI SDKs, chatbots, agents and tool-calling projects.
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);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.
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)
# 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 && claudeOn first launch it asks you to pick a model. Verify the install with claude --version.
2. CC Switch (desktop GUI switcher)
CC Switch setup
# 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 CodeClick 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)
Magpie manual setup
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)
Codex Desktop settings
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: 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. Install and open Codex Desktop, choose API Key as the auth method instead of ChatGPT account login.
- 2. Create the config.toml above and point the model and provider at WanAPIs.
- 3. Set WANAPIS_API_KEY, then restart Codex Desktop; restart VS Code/Cursor too if you use them.
- 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
4. 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 && codex5. VS Code extensions
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
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
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 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-proContinue
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.
name: WanAPIs
version: 0.0.1
schema: v1
models:
- name: WanAPIs Claude Opus 4.7
provider: openai
model: claude-opus-4-7
apiBase: https://api.wanapis.com/v1
apiKey: sk-xxx
roles:
- chat
- edit
- applyRoo Code
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
6. Desktop clients / browser extensions
- 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.
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"}]}POST /v1/video/generations
# Put the model name in the request body's model field (OpenAI-compatible)
# {"model": "seedance-2.0", ...}# 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
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
Sync vs async (Official)
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Fixed: gpt-image-2. |
| prompt | string | Yes | Image description or edit instruction; Chinese or English. |
| image_urls | string[] | No | Reference images for image-to-image: public URLs or base64 data URLs (mixable), up to 16. |
| size | string | No | Pixel 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. |
| n | integer | No | Number of images, default 1. |
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.
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"
]
}'{
"created": 1783144062,
"data": [
{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...<base64 PNG>" }
]
}Tested notes
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.
| Field | Description | Example |
|---|---|---|
| prompt | Required for normal generation; optional for layer decomposition. | string |
| image_urls | 0–10 reference images for normal generation; exactly 1 for layer decomposition. | ["https://.../source.png"] |
| n | Only 1 is supported. | 1 |
| size | Normal 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_format | Generation supports png / jpeg; choose png for a transparent background. Layer outputs are transparent PNGs. | png |
| background | Use transparent for transparent PNG generation. For decomposition, omit this field entirely, including auto. | transparent |
| layer_decomposition | Set true to decompose an image into layers. | true |
| layer_decomposition_options.max_images | 2–100, including the first base image; default 30. Sets the maximum number of returned images. | 2 |
| layer_decomposition_options.text_recognition | Optional. Set true to request OCR; text recognition is not guaranteed. | true |
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"
}'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
Reservation and wait time
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.
| Field | Description | Example |
|---|---|---|
| model | One of the four. Only seedream-5-0-pro has resolution tiers; the rest have a single price. | seedream-5-0-pro |
| prompt | Required. The image description. | string |
| size | Aspect ratio: 1:1 / 16:9 / 9:16 / 4:3 / 3:4 and more. | 1:1 |
| resolution | Output resolution. seedream-5-0-pro supports 1K / 2K, and the price follows the tier. | 2K |
| image_urls | Reference 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).
| Field | Description | Example |
|---|---|---|
| model | nano-banana-pro (quality-first) or nano-banana-2 (speed and price first). | nano-banana-pro |
| prompt | Required. Up to about 1000 characters. | string |
| size | Aspect ratio: auto / 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 21:9 and more. | auto |
| resolution | Output resolution. nano-banana-pro supports 1K / 2K / 4K, with 4K priced higher. | 1K |
| image_urls | Reference images for image-to-image, up to 14, as URLs or base64. | ["https://...jpg"] |
| n | Number 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
| Field | Description | Example |
|---|---|---|
| model | Always midjourney. | midjourney |
| prompt | Required. 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_urls | Reference images for image-to-image. You can also put the image URL at the start of the prompt, the native Midjourney way. | ["https://...jpg"] |
| speed | Speed mode: relax / fast / turbo, default relax. | relax |
| version | Model version, e.g. 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 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
| Field | Description | Example |
|---|---|---|
| model | Fixed: gpt-image-2-official. | gpt-image-2-official |
| prompt | Image description or edit instruction, Chinese or English (required). | "a starry-sky castle" |
| size | Aspect ratio (NOT pixels). 15 supported, e.g. 1:1 / 16:9 / 9:16 / 4:3 / 3:4. | 16:9 |
| resolution | Resolution tier 1k / 2k / 4k. If omitted, the upstream defaults to the lowest tier. | 2k |
| quality | Quality low / medium / high; defaults to low if omitted. Together with resolution it drives the price (see below) — higher quality costs more. | low |
| n | Number of images, 1–4, default 1. | 1 |
| image_urls | Reference images for image-to-image / editing: public URLs or base64 data URLs, up to 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": "An ancient castle beneath a starry sky, cinematic",
"size": "16:9",
"resolution": "2k",
"quality": "low"
}'curl https://api.wanapis.com/v1/images/tasks/task_xxxxxxxxxxxxxxxxxxxxxxxxxx \
-H "Authorization: Bearer $WANAPIS_API_KEY"{
"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
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.
| Field | Description | Example |
|---|---|---|
| model | Required. Either variant. | gpt-image-2.5-flare |
| prompt | Required. The description of the image. | a white ceramic mug |
| quality | Quality 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 |
| resolution | Resolution tier 1k / 2k / 4k, multiplied with quality for pricing. Omitting it is the same as 1k. | 1k |
| size | Aspect ratio such as 1:1, 16:9 or 3:2. | 1:1 |
| image_urls | Reference 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"] |
| n | Number of images, default 1, billed per image. | 1 |
Price multiplies across tiers, and the spread is large
The tier price is a pre-charge; tasks settle on actual usage
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"
}'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.
| Field | Description | Example |
|---|---|---|
| model | Required. Either variant. | gpt-image-2.6-flare |
| output_format | png / jpeg / webp / gif / svg; see below for GIF / SVG parameters and settlement rules. | png |
| prompt | Required. The description of the image. | a white ceramic mug |
| quality | Quality 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 |
| resolution | Resolution tier 1k / 2k / 4k, multiplied with quality for pricing. Omitting it is the same as 1k. | 1k |
| size | Aspect ratio such as 1:1, 16:9 or 3:2; exact pixel dimensions are also accepted. | 1:1 |
| image_urls | Reference images; providing them switches to image-to-image editing and counts as billable input. | ["https://.../a.jpg"] |
| n | Number of images, default 1, billed per image. | 1 |
2.6 tiers are flatter than 2.5
Tier pre-charge, settled on actual usage
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
| Field | Description | Example |
|---|---|---|
| gif.frame_count | 2–16 frames; default 9. | 2 |
| gif.frame_duration_ms | At least 20 milliseconds per frame; default 200. | 200 |
| size | auto or pixel dimensions; default 512x512. Ratios such as 1:1 are not accepted. | 512x512 |
| image_urls / n | Up to 16 reference images; n is 1–4. Mask, markup and compression parameters are unsupported. | 1 |
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.
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
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.
| Field | Description | Example |
|---|---|---|
| Seedream | Includes 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 |
| Flux | The FLUX.2 family, including Kontext for image editing. | flux-2-pro / flux-kontext-pro |
| Imagen | Google Imagen 4. | imagen-4.0-apimart |
| Qwen Image | Qwen image generation; the Pro tier has finer detail. | qwen-image-2.0 / qwen-image-2.0-pro |
| WAN | WAN 2.7 image models; the Pro tier renders at higher resolution. | wan2.7-image / wan2.7-image-pro |
| Z-Image | Lightweight and fast, the cheapest tier. | z-image-turbo |
| Midjourney | Returns four images per generation; see the Midjourney subsection above for its parameters. | midjourney |
| Official | OpenAI 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.
| Field | Description | Example |
|---|---|---|
| model | Required. The model name, from the table above. | qwen-image-2.0 |
| prompt | Required. The description of the image, in any language. Leaving it empty returns a 400. | a white ceramic mug |
| size | Optional. Controls the frame. Support for pixel format versus ratio format varies by model — see the table below. | 16:9 |
| image_urls | Optional. 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"] |
| n | Optional. 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:
| Field | Description | Example |
|---|---|---|
| Qwen Image | Both 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 models | For 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
If your key restricts models, allow the model for polling too
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"}}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.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.
| Field | Description | Example |
|---|---|---|
| seedance-2.5 | ByteDance's latest generation. 480p / 720p / 1080p, 4-15s, best quality and consistency. | per second |
| seedance-2.0 | Standard version, quality-first. 480p / 720p / 1080p, 4-15s. | per second |
| seedance-2.0-fast | Fast version for drafts and batch previews. | per second |
| seedance-2.0-mini | Lightweight and cheapest, good for high-volume drafts. | per second |
| veo3.1-quality | Google Veo 3.1 quality tier, supports 4K and synced audio. | per call |
| veo3.1-fast | Veo 3.1 fast tier. | per call |
| veo3.1-lite | Veo 3.1 lite tier, the cheapest. | per call |
| minimax-h3 | MiniMax 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-v3 | Kuaishou Kling v3, natural human motion, with pro / sound / 4k tiers. | per second |
| kling-v2-6 | Kling 2.6, the value tier. | per second |
| viduq3 | Shengshu Vidu Q3, with pro / turbo / mix variants. 540p / 720p / 1080p. | per second |
| happyhorse-1.0 | Alibaba ATH, released April 2026. 720p / 1080p. | per second |
| grok-video | xAI 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-video | xAI 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.5 | xAI'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
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).
| Field | Description | Example |
|---|---|---|
| model | kling-v3 or kling-v2-6. | kling-v3 |
| prompt | Required. The video prompt. | string |
| negative_prompt | Negative prompt to exclude unwanted elements. | string |
| mode | Quality tier: std / pro / 4k. Price rises with the tier. | std |
| duration | Duration in seconds, 3-15, default 5. | 5 |
| aspect_ratio | Aspect ratio: 16:9 / 9:16 / 1:1, default 16:9. | 16:9 |
| image_urls | Reference images for image-to-video. | ["https://...jpg"] |
| audio | Whether to generate synced audio, default false. | false |
| multi_shot | Multi-shot mode, used with shot_type and multi_prompt. | false |
| watermark | Whether to add a 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 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.
| Field | Description | Example |
|---|---|---|
| model | veo3.1-quality / veo3.1-fast / veo3.1-lite. | veo3.1-fast |
| prompt | Required. The video prompt. | string |
| resolution | Output resolution: 720p / 1080p / 4k; price rises accordingly. | 1080p |
| duration | Duration in seconds. Billed per call, so duration does not change the unit price. | 5 |
| image_urls | Reference 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 regenerationDefaults and strict input
| Field | Description | Example |
|---|---|---|
| model | Required public model ID. | minimax-h3 |
| prompt / content | Use 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 |
| resolution | 480p / 768P / 1080p / 2K. A tier is not a guarantee of exact output pixels. | 768P |
| seconds / duration | Integer 4–30; 2K up to 15. An integer number or digit string is accepted. Conflicting aliases are rejected. | 4 |
| ratio | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16; adaptive is available only for supported media requests. | 9:16 |
| fast_mode | JSON boolean. true doubles output and billable reference material fees; it does not double IR. | false |
| context_ir_enabled | JSON boolean for built-in prompt optimization. Disable when deliberately reusing a separately optimized prompt. | true |
| input_reference | Legacy 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[].role | Images: reference_image / first_frame / last_frame. Video: reference_video. Audio: reference_audio. | reference_image |
| media source | Exactly one of url or asset_id inside image_url / video_url / audio_url. Use an owned upload handle for local files. | {"asset_id":"asset_…"} |
| size | Legacy tier/orientation selector. Prefer resolution + ratio. Conflicting selections return 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
}'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)
| Field | Description | Example |
|---|---|---|
| 480p | Output and reference video CNY 0.078/second | per second |
| 768P | Output and reference video CNY 0.117/second | per second |
| 1080p | Output and reference video CNY 0.182/second | per second |
| 2K | Output and reference video CNY 0.195/second | per 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.
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.mp4For 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
| Field | Description | Example |
|---|---|---|
| viduq3 | Shengshu. Resolutions 540p / 720p / 1080p, with viduq3-pro (higher quality), viduq3-turbo (cheaper) and viduq3-mix variants. | per second |
| happyhorse-1.0 | Alibaba ATH, released April 2026. Supports 720p / 1080p. | per second |
| grok-video | xAI. 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-video | xAI 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.5 | xAI'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
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"
}'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"]
}'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"
}'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.
| Field | Description | Example |
|---|---|---|
| data.status | This 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_url | The 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.progress | Progress - a string including the percent sign, not a number. | "100%" |
| data.fail_reason | Failure reason as a string; an empty string when the task succeeded. | string |
| data.submit_time / start_time / finish_time | Submit / start / finish timestamps in seconds; subtract them to get queue time and render time. | 1790087400 |
| data.quota | Quota 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.data | Model-specific supplemental results. Their structure differs by model; prefer the documented public status and result fields. | object |
Save completed results promptly
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)
Request parameter conventions (important)
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.
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
}'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"
}'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.
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
}Upload limits
| Field | Description | Example |
|---|---|---|
| prompt | Video prompt. Describe the subject, action, scene, camera, style and constraints. | "cinematic dolly-in" |
| duration | Video duration in seconds, top-level number, 4-15. Defaults to 5. The legacy seconds field is still accepted. | 5 |
| size | Video ratio, top-level. 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / adaptive. | 16:9 |
| resolution | Output resolution, top-level. 480p / 720p / 1080p / 4k; the supported range varies by model. | 720p |
| image_urls | Reference image array, up to 9 including frames. Mutually exclusive with image_with_roles. | ["https://...jpg"] |
| image_with_roles | Reference images with roles, each {url, role}; role is first_frame / last_frame / reference_image. | [{url, role}] |
| video_urls | Reference 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_urls | Reference 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_audio | Whether to generate synced audio, top-level boolean. Enabling it may take longer. | true |
| return_last_frame | Whether to return the last frame, top-level boolean, handy for continuous shots. | true |
| seed | Random seed, top-level integer, for reproducible results. | 42 |
Submit response
{
"id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"object": "video",
"model": "seedance-2.0",
"status": "queued",
"progress": 0,
"created_at": 1780000000
}Poll task
curl https://api.wanapis.com/v1/video/generations/task_xxxxxxxxxxxxxxxxxxxxxxxxxx \
-H "Authorization: Bearer $WANAPIS_API_KEY"{
"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
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
Two modes
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"
}'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
}'| Field | Description | Example |
|---|---|---|
| model | Music model name; currently suno. | suno |
| version | Suno version (required). v3.5 / v4 / v4.5 / v4.5+ / v5 / v5.5; newer is higher quality. | v5 |
| custom | Mode switch. false = inspiration (prompt only); true = custom (lyrics + style). | false |
| prompt | Inspiration mode = music description; custom mode = lyrics. May be empty when instrumental is true. | "lo-fi piano" |
| instrumental | Whether to produce an instrumental (no vocals); works in both modes. | true |
| title | Song title (custom mode only). | "City Lights" |
| style | Style / tags (custom mode only), e.g. lo-fi, chill, piano. | "lo-fi, chill" |
| vocal_gender | Preferred vocal gender (optional). male / female. | female |
| negative_tags | Negative style tags to exclude unwanted styles (custom mode only). | "heavy metal" |
Submit response
{
"code": "success",
"data": {
"task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"status": "submitted"
}
}Poll task
curl https://api.wanapis.com/v1/music/tasks/task_xxxxxxxxxxxxxxxxxxxxxxxxxx \
-H "Authorization: Bearer $WANAPIS_API_KEY"{
"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
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.
| Field | Description | Example |
|---|---|---|
| Input price | model_ratio × CNY 2 / 1M tokens | input_tokens |
| Output price | model_ratio × completion_ratio × CNY 2 / 1M tokens | output_tokens |
| Quota unit | Quota 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.
| Field | Description | Example |
|---|---|---|
| 401 | API key missing or invalid | Check the Authorization header |
| 429 | Rate limit or quota protection triggered | Lower concurrency or switch group |
| 503 | Upstream or system overloaded | Wait 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:
OPENAI_API_KEY=$WANAPIS_API_KEY
OPENAI_BASE_URL=https://api.wanapis.com/v1Then 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.