文档

API 接入文档

IWKey 统一网关的接入指南：可用模型、快速开始、调用入口、代码示例、SDK 配置与常见问题。

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

视频模型任务 · 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"
  }'

01文本与视频模型，一个 Key 接入

统一查看 Claude、ChatGPT、Grok、Kimi 与视频模型的调用入口、模型 ID 获取方式和状态；完整目录见模型页面。

实时模型目录

模型 ID 以 GET /v1/models 返回为准；实时价格与分组见模型市场。

打开模型市场查看调用入口

GET /v1/models 查询当前可调用模型 ID POST /v1/chat/completions OpenAI 兼容文本入口 POST /v1/messages Anthropic Messages 入口 POST /videos/v1/videos/generations 视频异步任务入口 GET /videos/v1/videos/jobs/{job_id} 使用提交响应返回的 poll_url 查询任务结果

接口定义见 /docs/openapi.json；模型详情以实时 /v1/models 与模型市场为准。

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

最后更新：2026-09-04

02三步接入

STEP 01

申请 API Key

登录控制台，创建 API Key。

STEP 02

选择调用入口

文本模型替换 SDK base URL；视频模型用 /videos/v1/videos/generations 提交任务。

STEP 03

查看结果与用量

文本请求实时返回；视频模型按任务轮询，完成后可下载结果，并进入使用记录汇总。

最后更新：2026-09-04

03调用入口

GET

`/v1/models`

接入前查询当前可调用模型 ID。ChatGPT 模型 ID 以此列表为准。

POST

`/v1/chat/completions`

OpenAI 兼容入口。完成 base URL 替换后，OpenAI SDK、Cursor、Codex CLI、opencode、LangChain 可走此入口。

POST

`/v1/messages`

Anthropic Messages 原生入口。Claude Code 与 Anthropic SDK 可直接切换到 IWKey base URL。

POST

`/videos/v1/videos/generations`

视频模型异步任务入口。提交 prompt、时长、清晰度和画幅后返回 job_id 与 poll_url。

GET

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

优先请求提交响应返回的 poll_url；该地址用于查询任务状态、完成结果、失败原因和视频下载地址。

POST

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

火山方舟原生格式的视频模型入口。model 可直接填官方 ID（doubao-seedance-2-0-260128 / doubao-seedance-2-0-fast-260128 / doubao-seedance-2-5-260628）；顶层不支持的参数会明确报错，不会静默丢弃。

GET

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

方舟原生格式的任务查询入口，返回方舟状态枚举（queued / running / succeeded / failed / cancelled / expired）。成功时 content.video_url 为生成引擎官方直链（有效期通常约 24 小时），与标准接口的 video_url 完全一致；若该任务有平台副本，会额外附带 content.platform_video_url 与 content.platform_expires_at（本平台保存 7 天；这两个字段为本网关新增，方舟原生格式中没有）。

已经在用火山方舟原生请求格式的开发者，可以直接使用上面的方舟兼容入口；与方舟原生的具体差异见视频模型 API 接入指南「方舟兼容入口：与方舟原生的差异」。

最后更新：2026-09-04

04进阶场景示例

文本高级能力与视频模型异步任务示例，每个场景给出 cURL / Python / JavaScript 三种写法。

Anthropic 文本协议 ↗ OpenAI 文本协议 ↗ 视频工作台

流式响应（Streaming）视频模型工具调用（Tool Calling）推理增强（Thinking）

cURL Python JavaScript

cURL · 流式响应（SSE）
curl -N https://iwkey.com/v1/chat/completions \
  -H "Authorization: Bearer $IWKEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "写一首关于云的短诗"}],
    "stream": true
  }'

Python · 流式响应
from openai import OpenAI

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

stream = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "写一首关于云的短诗"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

JavaScript · 流式响应
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-5",
  messages: [{ role: "user", content: "写一首关于云的短诗" }],
  stream: true,
});

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

cURL Python JavaScript

cURL · 视频模型异步任务
# 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 · 火山方舟原生格式
# 1. 提交任务（方舟原生结构：content 数组 + ratio 字段）
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. 查询任务（成功时 content.video_url = 官方直链约 24h；
#    有平台副本时另有 content.platform_video_url，本平台保存 7 天）
curl "https://iwkey.com/videos/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $IWKEY_KEY"

Python · 视频模型异步任务
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 · 视频模型异步任务
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));
}

视频任务参数参考

参数	类型	说明
`model`	string	`doubao-seedance-2.0` / `doubao-seedance-2.0-fast` / `doubao-seedance-2.5` / `MiniMax-H3`
`prompt`	string	文本描述，必填
`duration`	integer	时长（秒），`doubao-seedance-2.0` / `-fast` 与 `MiniMax-H3` 为 4–15，`doubao-seedance-2.5` 为 4–30
`resolution`	string	按模型取值：`doubao-seedance-2.0` 为 `480p` / `720p` / `1080p` / `4k`；`-fast` 为 `480p` / `720p`；`doubao-seedance-2.5` 为 `480p` / `720p` / `1080p`；`MiniMax-H3` 为 `768p` / `2k`
`image_urls`	array ≤9	参考图片。每项可以是 URL 字符串（默认角色 = `first_frame`，图生视频）或对象 `{"url":"…","role":"first_frame\|last_frame\|reference_image"}`
`video_urls`	array ≤3	参考视频
`audio_urls`	array ≤3	参考音频；不能单独使用，必须搭配 `role:"reference_image"` 的图片或 `video_urls`；首帧/尾帧图片不能与音频同时使用
`generate_audio`	boolean	输出是否带音频，默认 `false`

cURL

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": "产品展示视频，柔和灯光，镜头缓慢推进",
    "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
  }'

计费：提交时预扣，成功后按上游 usage.total_tokens 结算并退补差额；失败全额退款。

出片链接说明

字段	说明
`video_url`	生成引擎官方原始出片链接，约 24 小时有效（有效期以 `expires_at` 为准）。
`platform_video_url`	平台存储链接，自生成完成起保留 7 天，到期后文件删除且不可恢复。未启用平台存储或无副本时为 `null`，此时用 `video_url`。
`platform_expires_at`	`platform_video_url` 的到期时间。

cURL Python JavaScript

cURL · 工具调用（Function Calling）
curl https://iwkey.com/v1/chat/completions \
  -H "Authorization: Bearer $IWKEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "杭州天气怎么样？"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}}
        }
      }
    }]
  }'

Python · 工具调用
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "杭州天气怎么样？"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
            },
        },
    }],
)
print(resp.choices[0].message.tool_calls)

JavaScript · 工具调用
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-5",
  messages: [{ role: "user", content: "杭州天气怎么样？" }],
  tools: [{
    type: "function",
    function: {
      name: "get_weather",
      parameters: {
        type: "object",
        properties: { city: { type: "string" } },
      },
    },
  }],
});
console.log(resp.choices[0].message.tool_calls);

平台采用官方标准模型 ID，推理强度通过 API 参数 控制——Anthropic 用 thinking 对象，OpenAI 用 reasoning_effort。

Anthropic（thinking） OpenAI（reasoning_effort）

Anthropic Claude · 启用 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": "解释量子纠缠的机制"
    }]
  }'

# thinking.budget_tokens 控制推理深度（1024 ~ 100000）
# max_tokens 须 > budget_tokens，留足 output 空间
# 支持 claude-opus-4-7, claude-opus-4-8 等支持 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": "解释量子纠缠的机制"}],
)

for block in resp.content:
    if block.type == "thinking":
        print("[思考过程]", block.thinking[:200], "...")
    elif block.type == "text":
        print("[回答]", block.text)

OpenAI · reasoning_effort 参数
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": "解释量子纠缠的机制"
    }]
  }'

# reasoning_effort: "low" | "medium" | "high"（默认 medium）
# 适用于 gpt-5.5 等支持推理的模型；查 /v1/models 确认当前可用 ID

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": "解释量子纠缠的机制"}],
)
print(resp.choices[0].message.content)

最后更新：2026-09-04

05各客户端配置示例

Claude Code

Claude 全系

⚠ ANTHROPIC_BASE_URL 只到主机名 https://iwkey.com，不要加 /v1（与 OpenAI 接口不同；加了会拼成 /v1/v1/messages → 404）

# 设置环境变量后直接启动
export ANTHROPIC_BASE_URL=https://iwkey.com
export ANTHROPIC_API_KEY=your-iwkey-key
claude

Cursor

Claude + ChatGPT + Grok

⚠ Base URL 须带 /v1（OpenAI 协议入口，Cursor 直接拼接 /chat/completions；与 Claude Code 的 ANTHROPIC_BASE_URL 不带 /v1 不同）

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

# Claude 与 Grok 可直接填模型 ID（如 claude-sonnet-5 / grok-4.6）；ChatGPT 模型 ID 先查 /v1/models

Anthropic Python SDK

Claude 全系

import anthropic

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

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

OpenAI Python SDK

Claude + ChatGPT + Grok

# model 换名即切 provider
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-5",
    messages=[{"role": "user", "content": "Hello"}],
)

# ChatGPT — 同一个 client，具体模型 ID 先查 /v1/models
resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello"}],
)

# Grok — 同样是同一个 client，直接切 model 即可
resp = client.chat.completions.create(
    model="grok-4.6",
    messages=[{"role": "user", "content": "Hello"}],
)

Kimi K3

推理模型 · OpenAI 兼容

⚠ Base URL 只填到 https://iwkey.com/v1 为止；OpenAI 兼容客户端会自动拼接 /chat/completions，不要再手动追加一次 /v1 或 /chat/completions，否则会拼成 /v1/v1/chat/completions 之类的错误路径 → 404

⚠ Kimi K3 始终开启思考过程且无法关闭，思考内容计入输出 token 计费

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"（默认 max，无 medium 档——与部分 OpenAI 推理模型的枚举不同）

视频模型 API

Seedance / 视频任务

# 标准 HTTP 调用：提交任务后轮询 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 系（Responses API）

⚠ base_url 只到 /v1，不要加 /chat/completions，否则 Codex 会拼出错误路径导致 404

⚠ 模型用 gpt-5.5，Codex 走 Responses API（非 chat/completions），需在 config.toml 声明 wire_api = "responses"

# ~/.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-你的令牌"
codex

opencode

Claude + ChatGPT + Grok

⚠ options.baseURL 须带 /v1（@ai-sdk/openai-compatible 直接拼接 /chat/completions，不会自动补 /v1）

# ~/.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-5": { "name": "Claude Sonnet 4.6" },
        "gpt-5.5": { "name": "GPT-5.5" },
        "grok-4.6": { "name": "Grok 4.6" }
      }
    }
  }
}

# 设置环境变量后运行 /connect 存凭据，provider id 填 "iwkey"
export IWKEY_KEY="your-iwkey-key"
opencode
# TUI 内：/connect → Other → 粘贴 Key，provider id 填 "iwkey"
# 完成后 /models 选择上面配置的模型

LangChain

Claude 全系

from langchain_anthropic import ChatAnthropic

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

最后更新：2026-09-04

06视频模型

视频生成是异步任务，支持参考素材与素材库，接入规范见独立文档：/docs/video-model/（共用 API Key 与入口域名）。

三分钟跑通第一条视频——提交 → 轮询 → 取片的最小闭环
参考图与素材库——真人形象只能走素材库，视频素材也在这里
方舟兼容入口——已经在用火山方舟请求格式的，改个地址就能接
接口参考 · 错误码 · 配额与限制

最后更新：2026-09-05

07常见问题

返回格式和官方 API 一致吗？

一致。响应体透传上游原生字段（Anthropic 的 request_id、OpenAI 的 id 与 system_fingerprint）。文本请求不留存提示词和回答正文，完整边界见透明度页面。

计费方式是什么？

文本模型按 token 用量计费；视频模型按任务、时长和上游模型计费。登录控制台后可查看实时余额、用量明细，可按模型/日期/Key 筛选查看。支持对公转账 + 增值税发票。

你们会存储我的 prompt 和 response 吗？

文本请求与响应正文不存数据库。视频模型属于异步任务，任务参数、状态、成本、结果地址和失败原因会保留用于任务追踪与计费；完整边界以透明度页面为准。

支持 Streaming 吗？

文本模型支持 Anthropic 原生 SSE streaming 和 OpenAI 兼容 streaming，在请求中设置 "stream": true 即可。视频模型不是 streaming 响应；提交任务后应优先请求响应中的 poll_url，当前 canonical 地址为 /videos/v1/videos/jobs/{job_id}。

视频模型怎么调用？

使用同一个 API Key 调用 POST /videos/v1/videos/generations，提交后会返回 job_id 和 poll_url。任务完成后可在轮询响应或「视频模型使用记录」里查看结果、下载地址和失败原因。

如何启用推理增强（Extended Thinking / reasoning_effort）？

平台只提供官方标准模型 ID，不提供 -thinking/-high/-low 等后缀变体。推理强度由 API 参数控制：

Anthropic Claude：在请求体加 "thinking": {"type": "enabled", "budget_tokens": 10000}（预算 1024～100000 tokens）。max_tokens 须大于 budget_tokens。支持模型：claude-opus-4-7、claude-opus-4-8 等。
OpenAI（推理模型）：在请求体加 "reasoning_effort": "high"（可选 low/medium/high）。支持模型：gpt-5.5 等，查 GET /v1/models 确认。

完整示例见代码示例 → 推理增强（Thinking）标签。

如何启用提示缓存（Prompt Caching）？

💡 提示缓存（Prompt Caching）：Claude 模型支持提示缓存，对重复的长上下文（system prompt、Agent 循环、代码库上下文等）可节省最高约 90% 的输入费用。启用方式：使用 Anthropic 原生 /v1/messages 格式，并在消息/系统提示中标记 cache_control 断点。注意：OpenAI 兼容的 /v1/chat/completions 格式不支持 Claude 提示缓存，每次请求按全价输入计费。

和直连 Anthropic / OpenAI API 有什么区别？

文本接口与 Anthropic / OpenAI 官方格式兼容，支持 Streaming 和 Tool Calling；视频模型走 IWKey 的异步任务接口。同一个 Key、余额和使用记录打通，支持人民币对公结算与增值税发票。

最后更新：2026-09-04