Docs

API Documentation

Integration guide for the IWKey unified gateway: available models, quick start, endpoints, code examples, SDK setup, and FAQ.

Text call · cURL
curl https://iwkey.com/v1/chat/completions \
  -H "Authorization: Bearer $IWKEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

Video model task · cURL
curl https://iwkey.com/videos/v1/videos/generations \
  -H "Authorization: Bearer $IWKEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "A cinematic product shot",
    "duration": 5,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }'

01One key for text and video models

One place for Claude, ChatGPT, Grok, Kimi, and video model endpoints, model ID lookup, and status; see the models page for the full catalog.

Live model catalog

Model IDs are sourced from GET /v1/models. Live pricing, groups, and available endpoints for the public site live on the model market; the docs center keeps only integration rules and key entry points.

Open model market View endpoints

GET /v1/models Query current callable model IDs POST /v1/chat/completions OpenAI-compatible text endpoint POST /v1/messages Anthropic Messages endpoint POST /videos/v1/videos/generations Video async task endpoint GET /videos/v1/videos/jobs/{job_id} Use the poll_url returned by submission to fetch the result

API definition: /docs/openapi.json. Model details follow live /v1/models and the model market.

curl · List models
curl https://iwkey.com/v1/models \
  -H "Authorization: Bearer $IWKEY_KEY"

Last updated: 2026-08-23

02Three steps to integrate

STEP 01

Request an API key

STEP 02

Choose an endpoint

Text models swap the SDK base URL; video models submit tasks through /videos/v1/videos/generations.

STEP 03

Review results and usage

Text requests return in real time; video tasks are polled until complete, then results can be downloaded and roll up into usage records.

Last updated: 2026-08-23

03Endpoints

GET

`/v1/models`

Query current callable model IDs before integrating. ChatGPT model IDs follow this list.

POST

`/v1/chat/completions`

OpenAI-compatible endpoint. After swapping the base URL, the OpenAI SDK, Cursor, Codex CLI, opencode, and LangChain can all call through here.

POST

`/v1/messages`

Anthropic Messages-native endpoint. Claude Code and the Anthropic SDK can switch directly to the IWKey base URL.

POST

`/videos/v1/videos/generations`

Video model async task endpoint. Submit a prompt, duration, resolution, and aspect ratio to receive a job_id and poll_url.

GET

`/videos/v1/videos/jobs/{job_id}`

Prefer the poll_url returned by submission; it provides task status, completed output, failure details, and the video download URL.

POST

`/videos/api/v3/contents/generations/tasks`

Volcano Ark native-format entry for video models. model accepts the official IDs (doubao-seedance-2-0-260128 / doubao-seedance-2-0-fast-260128 / doubao-seedance-2-5-260628); unsupported top-level parameters return an explicit error and are never silently dropped.

GET

`/videos/api/v3/contents/generations/tasks/{id}`

Ark native-format task query entry; returns Ark status values (queued / running / succeeded / failed / cancelled / expired). On success content.video_url is the generation engine's official link (typically valid ~24 hours), identical to video_url on the standard endpoint. When a platform copy exists, content.platform_video_url and content.platform_expires_at are also included (kept for 7 days on our side; these are gateway additions absent from the Ark native format and can be safely ignored).

Developers already using the Volcano Ark native request format can use the Ark-compatible endpoint above directly; see the specific differences from Ark native in the Video Model API Integration Guide's "Ark-compatible endpoint: differences from Ark native".

Last updated: 2026-08-28

04Advanced scenario examples

Advanced text capabilities and video model async task examples — each scenario shown in cURL / Python / JavaScript.

Anthropic text protocol ↗ OpenAI text protocol ↗ Video workbench

Streaming response Video model Tool calling Extended Thinking

cURL Python JavaScript

cURL · streaming response (SSE)
curl -N https://iwkey.com/v1/chat/completions \
  -H "Authorization: Bearer $IWKEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Write a short poem about clouds"}],
    "stream": true
  }'

Python · streaming response
from openai import OpenAI

client = OpenAI(base_url="https://iwkey.com/v1", api_key="$IWKEY_KEY")

stream = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Write a short poem about clouds"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

JavaScript · streaming response
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://iwkey.com/v1",
  apiKey: process.env.IWKEY_KEY,
});

const stream = await client.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Write a short poem about clouds" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0].delta.content ?? "");
}

cURL Python JavaScript

cURL · video model async task
# 1. Submit job and capture the returned poll_url
POLL_URL=$(curl -sS https://iwkey.com/videos/v1/videos/generations \
  -H "Authorization: Bearer $IWKEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "A cinematic product shot on a clean studio desk",
    "duration": 5,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }' | jq -r '.poll_url')

# 2. Poll the exact URL returned by the API
curl "$POLL_URL" \
  -H "Authorization: Bearer $IWKEY_KEY"

cURL · Volcano Ark native format
# 1. Submit the task (Ark native shape: content array + ratio field)
TASK_ID=$(curl -sS https://iwkey.com/videos/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $IWKEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      { "type": "text", "text": "A cinematic product shot on a clean studio desk" }
    ],
    "duration": 5,
    "resolution": "480p",
    "ratio": "16:9"
  }' | jq -r '.id')

# 2. Query the task (content.video_url = official link, ~24h;
#    content.platform_video_url is our 7-day copy when present)
curl "https://iwkey.com/videos/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $IWKEY_KEY"

Python · video model async task
import os
import time
import requests

headers = {
    "Authorization": f"Bearer {os.environ['IWKEY_KEY']}",
    "Content-Type": "application/json",
}

job = requests.post(
    "https://iwkey.com/videos/v1/videos/generations",
    headers=headers,
    json={
        "model": "doubao-seedance-2.0",
        "prompt": "A cinematic product shot on a clean studio desk",
        "duration": 5,
        "resolution": "480p",
        "aspect_ratio": "16:9",
    },
)
job.raise_for_status()
poll_url = job.json()["poll_url"]

while True:
    result = requests.get(poll_url, headers=headers)
    result.raise_for_status()
    data = result.json()
    if data["status"] in {"completed", "failed", "cancelled", "timeout"}:
        print(data)
        break
    time.sleep(5)

JavaScript · video model async task
const headers = {
  Authorization: `Bearer ${process.env.IWKEY_KEY}`,
  "Content-Type": "application/json",
};

const submit = await fetch("https://iwkey.com/videos/v1/videos/generations", {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "doubao-seedance-2.0",
    prompt: "A cinematic product shot on a clean studio desk",
    duration: 5,
    resolution: "480p",
    aspect_ratio: "16:9",
  }),
});
const job = await submit.json();

while (true) {
  const res = await fetch(job.poll_url, { headers });
  const result = await res.json();
  if (["completed", "failed", "cancelled", "timeout"].includes(result.status)) {
    console.log(result);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

Video task parameter reference

Parameter	Type	Description
`model`	string	`doubao-seedance-2.0` / `doubao-seedance-2.0-fast` / `doubao-seedance-2.5` / `MiniMax-H3`
`prompt`	string	Text prompt, required
`duration`	integer	Duration in seconds: `doubao-seedance-2.0` / `-fast` is 4–15, `doubao-seedance-2.5` is 4–30
`resolution`	string	`480p` / `720p` / `1080p` (fast does not support 1080p)
`image_urls`	array ≤9	Reference images. Each item is either a URL string (default role = `first_frame`, image-to-video) or an object `{"url":"…","role":"first_frame\|last_frame\|reference_image"}`
`video_urls`	array ≤3	Reference videos
`audio_urls`	array ≤3	Reference audio; cannot be used alone — must pair with a `role:"reference_image"` image or `video_urls`; first/last-frame images cannot be combined with audio
`generate_audio`	boolean	Whether output includes audio, default `false`

cURL

cURL · with reference image and audio
curl https://iwkey.com/videos/v1/videos/generations \
  -H "Authorization: Bearer $IWKEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "Product showcase video, soft lighting, slow push-in",
    "duration": 5,
    "resolution": "720p",
    "image_urls": [
      {"url": "https://example.com/product.jpg", "role": "reference_image"}
    ],
    "audio_urls": ["https://example.com/bgm.mp3"],
    "generate_audio": true
  }'

Billing: settled per task; on success, reconciled against upstream usage.total_tokens with a credit or charge adjustment; failed tasks are fully refunded.

Video link fields

Field	Description
`video_url`	Original video link from the generation engine, valid for about 24 hours (`expires_at` is the authoritative expiry).
`platform_video_url`	Platform storage link, kept for 7 days from job completion (the web console Download button uses this one). Once expired the file is deleted and cannot be recovered, so download it within that window. `null` when the job has no platform copy (storage unavailable, or platform storage not enabled for the account) — use `video_url` instead.
`platform_expires_at`	Expiry time for `platform_video_url`.

cURL Python JavaScript

cURL · tool calling (Function Calling)
curl https://iwkey.com/v1/chat/completions \
  -H "Authorization: Bearer $IWKEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "What's the weather like in Hangzhou?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}}
        }
      }
    }]
  }'

Python · tool calling
from openai import OpenAI

client = OpenAI(base_url="https://iwkey.com/v1", api_key="$IWKEY_KEY")

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "What's the weather like in Hangzhou?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
            },
        },
    }],
)
print(resp.choices[0].message.tool_calls)

JavaScript · tool calling
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://iwkey.com/v1",
  apiKey: process.env.IWKEY_KEY,
});

const resp = await client.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "What's the weather like in Hangzhou?" }],
  tools: [{
    type: "function",
    function: {
      name: "get_weather",
      parameters: {
        type: "object",
        properties: { city: { type: "string" } },
      },
    },
  }],
});
console.log(resp.choices[0].message.tool_calls);

The platform provides only official standard model IDs — suffix variants like -thinking/-high/-low are not offered. Reasoning is controlled via API parameters — Anthropic uses the thinking object, OpenAI uses reasoning_effort.

Anthropic（thinking） OpenAI（reasoning_effort）

Anthropic Claude · Enable Extended Thinking
curl https://iwkey.com/v1/messages \
  -H "Authorization: Bearer $IWKEY_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 16000,
    "thinking": {
      "type": "enabled",
      "budget_tokens": 10000
    },
    "messages": [{
      "role": "user",
      "content": "Explain the mechanism of quantum entanglement"
    }]
  }'

# thinking.budget_tokens controls reasoning depth (1024 ~ 100000)
# max_tokens must be > budget_tokens, to leave room for output
# Supported: claude-opus-4-7, claude-opus-4-8, and other models with extended thinking

Python · Anthropic SDK
import anthropic

client = anthropic.Anthropic(
    base_url="https://iwkey.com",
    api_key="$IWKEY_KEY",
)

resp = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000,
    },
    messages=[{"role": "user", "content": "Explain the mechanism of quantum entanglement"}],
)

for block in resp.content:
    if block.type == "thinking":
        print("[thinking]", block.thinking[:200], "...")
    elif block.type == "text":
        print("[answer]", block.text)

OpenAI · reasoning_effort parameter
curl https://iwkey.com/v1/chat/completions \
  -H "Authorization: Bearer $IWKEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "reasoning_effort": "high",
    "messages": [{
      "role": "user",
      "content": "Explain the mechanism of quantum entanglement"
    }]
  }'

# reasoning_effort: "low" | "medium" | "high" (default: medium)
# Applies to gpt-5.5 and other reasoning models; check /v1/models for current IDs

Python · OpenAI SDK
from openai import OpenAI

client = OpenAI(base_url="https://iwkey.com/v1", api_key="$IWKEY_KEY")

resp = client.chat.completions.create(
    model="gpt-5.5",
    reasoning_effort="high",
    messages=[{"role": "user", "content": "Explain the mechanism of quantum entanglement"}],
)
print(resp.choices[0].message.content)

Last updated: 2026-08-28

05Client SDK configuration examples

Claude Code

All Claude models

⚠ ANTHROPIC_BASE_URL must stop at the hostname https://iwkey.com — do not add /v1 (unlike OpenAI; adding it would form /v1/v1/messages → 404)

# Set environment variables, then launch directly
export ANTHROPIC_BASE_URL=https://iwkey.com
export ANTHROPIC_API_KEY=your-iwkey-key
claude

Cursor

Claude + ChatGPT + Grok

⚠ Base URL must include /v1 (Cursor appends /chat/completions directly to this OpenAI-protocol endpoint — unlike Claude Code's ANTHROPIC_BASE_URL, which does not take /v1)

# Settings → Models → Override OpenAI Base URL
Base URL: https://iwkey.com/v1
API Key:  your-iwkey-key

# Claude and Grok: use model IDs directly (e.g. claude-sonnet-4-6 / grok-4.5); ChatGPT model IDs: check /v1/models first

Anthropic Python SDK

All Claude models

import anthropic

client = anthropic.Anthropic(
    base_url="https://iwkey.com",
    api_key="your-iwkey-key",
)

msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)

OpenAI Python SDK

Claude + ChatGPT + Grok

# Swap providers by changing the model name
from openai import OpenAI

client = OpenAI(
    base_url="https://iwkey.com/v1",
    api_key="your-iwkey-key",
)

# Claude
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello"}],
)

# ChatGPT — same client; check /v1/models for the current model ID
resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello"}],
)

# Grok — same client, just swap the model
resp = client.chat.completions.create(
    model="grok-4.5",
    messages=[{"role": "user", "content": "Hello"}],
)

Kimi K3

Reasoning model · OpenAI compatible

⚠ Base URL stops at https://iwkey.com/v1. OpenAI-compatible clients append /chat/completions automatically — do not add another /v1 or /chat/completions yourself, or it becomes /v1/v1/chat/completions and 404s

⚠ Kimi K3 always has reasoning (thinking) enabled — it cannot be turned off. The reasoning content before the visible answer counts as output tokens; even a short reply can consume tens to hundreds of output tokens, so factor this into cost estimates

curl https://iwkey.com/v1/chat/completions \
  -H "Authorization: Bearer $IWKEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

from openai import OpenAI

client = OpenAI(base_url="https://iwkey.com/v1", api_key="your-iwkey-key")

resp = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="low",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

# reasoning_effort: "low" | "high" | "max" (default max — no "medium" tier, unlike some OpenAI reasoning models)

Video model API

Seedance / Video tasks

# Standard HTTP call: submit a task, then poll poll_url
curl https://iwkey.com/videos/v1/videos/generations \
  -H "Authorization: Bearer your-iwkey-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedance-2.0","prompt":"A product video","duration":5,"resolution":"480p","aspect_ratio":"16:9"}'

Codex CLI

ChatGPT series (Responses API)

⚠ base_url must stop at /v1 — do not add /chat/completions, or Codex will build a bad path and return 404

⚠ Use model gpt-5.5. Codex uses the Responses API (not chat/completions) — declare wire_api = "responses" in config.toml

# ~/.codex/config.toml
model = "gpt-5.5"
model_provider = "iwkey"

[model_providers.iwkey]
name = "IWKey"
base_url = "https://iwkey.com/v1"
wire_api = "responses"
env_key = "IWKEY_KEY"

export IWKEY_KEY="sk-your-api-key"
codex

opencode

Claude + ChatGPT + Grok

⚠ options.baseURL must include /v1 — @ai-sdk/openai-compatible appends /chat/completions directly and does not add /v1 for you

# ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "iwkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "IWKey",
      "options": {
        "baseURL": "https://iwkey.com/v1",
        "apiKey": "{env:IWKEY_KEY}"
      },
      "models": {
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
        "gpt-5.5": { "name": "GPT-5.5" },
        "grok-4.5": { "name": "Grok 4.5" }
      }
    }
  }
}

# Set the env var, then run /connect to store the credential under provider id "iwkey"
export IWKEY_KEY="your-iwkey-key"
opencode
# In the TUI: /connect → Other → paste your key under provider id "iwkey"
# Then /models to pick one of the models configured above

LangChain

All Claude models

from langchain_anthropic import ChatAnthropic

llm = ChatAnthropic(
    base_url="https://iwkey.com",
    api_key="your-iwkey-key",
    model="claude-sonnet-4-6",
)

Last updated: 2026-08-23

06Video models

Video generation is asynchronous and carries an extra layer of parameters, an asset library and its own error codes, so it has a dedicated integration guide: /en/docs/video-model/. Same API key, same base URL — no separate account.

Get your first video running in 3 minutes — the minimal submit → poll → fetch loop
Reference images and the asset library — real-person likenesses must go through the library; video assets live there too
Ark-compatible endpoint — already on Volcano Ark's request format? Change the base URL and go
API reference · Error codes · Quotas & limits

Last updated: 2026-08-31

07Frequently asked questions

How do I verify I'm using the real model?

Every response carries the upstream native fields (Anthropic's request_id, OpenAI's id and system_fingerprint), identical to a direct upstream call. You can also visit the transparency page to inspect the database schema and confirm we do not store any prompt or response content.

How is billing handled?

Text models are billed by token usage; video models are billed by task, duration, and upstream model. Log in to the console to see real-time balance and usage detail, filterable by model, date, or key. Bank transfer and VAT invoice are supported.

Do you store my prompts and responses?

The text channel does not persist prompt or response bodies in the regular database layer. Video models are async tasks — task parameters, status, cost, result URL, and failure reason are kept for task tracking and billing. See the transparency page for the full boundary.

Do you support streaming?

Text models support Anthropic-native SSE streaming and OpenAI-compatible streaming — set "stream": true in the request. Video models are not streaming responses; after submission, prefer the response's poll_url. Its current canonical path is /videos/v1/videos/jobs/{job_id}.

How do I call video models?

Use the same API key to call POST /videos/v1/videos/generations. The response returns job_id and poll_url. After the task completes, check the polling response or "Video Model Usage" for the result, download URL, and failure reason.

How do I enable Extended Thinking or reasoning_effort?

The platform provides only official standard model IDs — suffix variants like -thinking/-high/-low are not offered. Reasoning depth is controlled via API parameters:

Anthropic Claude: add "thinking": {"type": "enabled", "budget_tokens": 10000} to the request body (budget: 1024–100000 tokens). max_tokens must exceed budget_tokens. Supported models: claude-opus-4-7, claude-opus-4-8, and others.
OpenAI (reasoning models): add "reasoning_effort": "high" to the request body (options: low/medium/high). Supported models: gpt-5.5 and others — check GET /v1/models to confirm.

See the full example under the Code Examples → Extended Thinking tab.

How do I enable Prompt Caching?

💡 Prompt Caching: Claude models support prompt caching, saving up to ~90% on input cost for repeated long context (system prompts, agent loops, codebase context, etc). To enable: use the Anthropic-native /v1/messages format and mark cache_control breakpoints in the messages or system prompt. Note: the OpenAI-compatible /v1/chat/completions format does not support Claude prompt caching — every request is billed at full input price. Caching is unnecessary for one-off or always-different requests.

How is this different from calling Anthropic / OpenAI directly?

The text channel keeps the Anthropic / OpenAI compatible protocol surface, including streaming and tool calling. Video models are unified across multiple video upstreams via the IWKey async task endpoint. The difference: one key, balance, and usage record across both, plus CNY bank transfer and VAT invoice support.

Last updated: 2026-08-28