API 接入文档

快速开始

只需要三样东西：接口地址、API Key 和模型名称。准备好之后，几分钟就能发出第一条请求。

1. 创建 Key 并保存到本机在控制台创建 API Key，保存到环境变量 API302_KEY。不要写进代码、网页前端，也不要截图外发。
2. 发送第一条请求复制下面任意一种写法运行，能看到模型回复就说明接通了。
3. 核对用量返回结果里的 usage 是本次消耗的 Token 数；到控制台“调用记录”可以看到对应扣费。

curl https://api.302api.com/v1/chat/completions \
  -H "Authorization: Bearer ${API302_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-luna","messages":[{"role":"user","content":"你好"}],"max_completion_tokens":256}'

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["API302_KEY"], base_url="https://api.302api.com/v1",
                max_retries=0, timeout=120.0)
result = client.chat.completions.create(
    model="gpt-6-luna",
    messages=[{"role": "user", "content": "你好"}],
    max_completion_tokens=256,
)
print(result.choices[0].message.content)
print(result.usage)

import os
import anthropic

client = anthropic.Anthropic(api_key=os.environ["API302_KEY"], base_url="https://api.302api.com",
                             max_retries=0, timeout=120.0)
message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=512,
    messages=[{"role": "user", "content": "你好"}],
)
print("".join(block.text for block in message.content if block.type == "text"))
print(message.usage)

const response = await fetch("https://api.302api.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API302_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-6-luna",
    messages: [{ role: "user", content: "你好" }],
    max_completion_tokens: 256,
  }),
});
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data.error));
console.log(data.choices[0].message.content);
console.log(data.usage);

怎么判断回复是否完整

• finish_reason 为 stop：正常结束。
• finish_reason 为 length：达到输出上限被截断，回答不完整，需要调大上限。
• finish_reason 为 tool_calls：模型要求调用工具，需要你的程序执行工具后把结果发回去。
• 没有返回 usage 不代表免费，请到控制台调用记录核对。

选择模型

不知道选哪个？日常对话和批量任务用便宜的 luna 或 Haiku，写代码和复杂分析用 astra、Opus 或 Fable，拿不准就用 sol 或 Sonnet。

表中“Chat”指 /v1/chat/completions，“Responses”指 /v1/responses，“Claude 原生”指 /v1/messages。全部模型的价格见模型与价格，实时清单和当前售价以控制台模型页为准，也可以用接口查询（不产生费用）：

curl https://api.302api.com/v1/models \
  -H "Authorization: Bearer ${API302_KEY}"

术语速查

第一次接触 API？下面这些词在文档里会反复出现。

API KeyAPI Key

调用接口的密钥，相当于账号密码。泄露后别人可以花你的余额，发现泄露请立即在控制台停用并换新。

接口地址Base URL

程序把请求发到哪里。本站统一是 https://api.302api.com。

模型名称Model ID

告诉接口要用哪个模型，比如 gpt-6-luna，必须一字不差。

Tokentoken

模型计算文字长度的单位，也是计费单位。文字越长 Token 越多，准确数量以每次返回的 usage 为准。

输入 / 输出input / output

输入是你发给模型的内容（提问、历史对话、文件），输出是模型生成的回复。两者单价不同，输出通常更贵。

上下文context

模型一次能“看到”的全部内容，包括历史对话。越长越慢、越贵，太长时可以压缩对话或开新会话。

缓存cache

反复发送的相同开头内容（如固定的系统提示）可以命中缓存，按更低价格计费。

流式输出stream

边生成边返回，文字像打字一样逐段出现；关闭时要等全部生成完才一次性返回。

SDKSDK

官方提供的代码库，替你处理请求细节。本站兼容 OpenAI SDK 和 Anthropic SDK，改个地址就能用。

协议格式API format

请求和返回的格式约定。本站同时支持 OpenAI 格式和 Anthropic（Claude）格式。

接入常用工具

用现成的工具（编程助手、聊天客户端）接入本站，一般只需要填地址、Key 和模型名称，不用写代码。

Claude Code

分步配置、平台差异与排错：Claude Code 完整指南 →

export ANTHROPIC_BASE_URL="https://api.302api.com"
export ANTHROPIC_API_KEY="$API302_KEY"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-5-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-5-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-5-5"
claude --model claude-sonnet-5-5

$env:ANTHROPIC_BASE_URL = "https://api.302api.com"
$env:ANTHROPIC_API_KEY = $env:API302_KEY
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-5-5"
claude --model claude-sonnet-5-5

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.302api.com",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5"
  }
}

首次启动如果询问是否使用检测到的 API Key，选择使用。会话中可以用 /model 切换到 claude-opus-5-5、claude-fable-5-1 等型号。

Codex CLI

配置文件位置、服务商与调用核对：Codex CLI 完整指南 →

把下面内容写进 ~/.codex/config.toml，Key 放在环境变量 API302_KEY。Codex 使用 Responses 格式，可选 gpt-6-astra、gpt-6-sol、gpt-6-luna。

model = "gpt-6-astra"
model_provider = "302api"

[model_providers.302api]
name = "302API"
base_url = "https://api.302api.com/v1"
env_key = "API302_KEY"
wire_api = "responses"

Cherry Studio 等图形客户端

1. 新建服务商类型选“OpenAI 兼容”；想用 Claude 原生功能可选“Anthropic”。
2. 填写地址和 KeyAPI 地址填 https://api.302api.com，粘贴本站 API Key。
3. 添加模型手动添加模型表里的名称，保存后即可对话。

生图需要客户端本身支持图片功能；在聊天里选图片型号，不一定会自动走图片接口。分步图文教程：Cherry Studio · WorkBuddy · Cline（VS Code）

让 AI 帮你配置生图

请为我当前使用的 AI 工具接入 302API 生图。
先阅读最新文档：https://302api.com/docs
Base URL：https://api.302api.com

1. 检查当前工具，优先使用已有生图配置；不支持时再用插件、MCP 或 Skill。保留原有主模型和其他配置，修改前备份。
2. 按文档选择图片模型、接口与参数，不要把生图模型直接当主聊天模型，也不要切换到其他收费服务。
3. 使用我本地配置的 Key；缺少时引导我安全填写，不要让我发到聊天中，不写入代码、日志或截图。
4. 正确提取并保存图片，返回文件或预览；处理超时和错误，结果未知时不要自动重试。
5. 先完成免费检查和模拟验证；真实生图或自动检测前，确认模型、次数和费用上限，已有明确授权则沿用。
6. 完成后说明使用方法、改动和验证结果；未真实生图时明确标注“真实生图未验证”。

Claude 原生接口

如果你的程序原本就用 Anthropic（Claude）官方格式，直接把地址换成本站即可，Key、余额和模型名称与其他接口通用。

curl https://api.302api.com/v1/messages \
  -H "x-api-key: ${API302_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":512,"messages":[{"role":"user","content":"你好"}]}'

• max_tokens（最多输出多少 Token）必填。Sonnet、Opus、Fable 默认会先“思考”，思考也算输出，建议不低于 512。
• 请求头需要 anthropic-version: 2023-06-01。鉴权用 x-api-key 或 Authorization: Bearer 都可以。
• 读取回复时只取类型为 text 的内容块；开启思考时，第一块可能是思考过程（thinking）。
• anthropic-beta 测试功能按白名单放行（如 Claude Code、交错思考、上下文管理、结构化输出、1 小时缓存），其余会被自动去掉。
• Token 计数接口 /v1/messages/count_tokens 暂未开放。

Responses 接口

Responses 是 OpenAI 的新一代接口格式，Codex 等编程工具默认使用它。GPT-6 三个文本模型都支持。

curl https://api.302api.com/v1/responses \
  -H "Authorization: Bearer ${API302_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-sol","input":"用一句话解释递归","max_output_tokens":256}'

和 Chat 接口的区别：请求里用 input 代替 messages；回复在 output 里类型为 output_text 的内容中，OpenAI SDK 可以直接读 result.output_text。

目前只开放创建（POST /v1/responses），不支持按 ID 查询或删除历史响应；多轮对话请在请求里自己带上历史。

图片生成与编辑

图片模型不能像聊天模型那样选上就用，需要额外配置：GPT 图片走专门的图片接口，支持生成和编辑；Gemini 图片（Nano Banana）走对话接口，只支持生成，而且要关掉流式等设置。

GPT 图片

第 1 步：生成，结果保存为 image-response.json

curl --fail-with-body --max-time 210 https://api.302api.com/v1/images/generations \
  -H "Authorization: Bearer ${API302_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2.5-flare","prompt":"白色背景中央的蓝色圆形，无文字","size":"1024x1024","quality":"low"}' \
  -o image-response.json

第 2 步：把结果解码成 PNG 图片

import base64, json
from pathlib import Path

result = json.loads(Path("image-response.json").read_text())
if "error" in result:
    raise SystemExit(result["error"])
Path("generated.png").write_bytes(base64.b64decode(result["data"][0]["b64_json"]))
print("saved generated.png", result.get("usage"))

编辑已有图片（上传一张 PNG / JPEG / WebP，大小由模型服务校验）

curl --fail-with-body --max-time 210 https://api.302api.com/v1/images/edits \
  -H "Authorization: Bearer ${API302_KEY}" \
  -F "model=gpt-image-2.5-flare" -F "image=@generated.png;type=image/png" \
  -F "prompt=把圆形改成红色" -F "size=1024x1024" -F "quality=low" \
  -o edit-response.json

每次只出一张 PNG，不支持批量生成、流式预览、图片 URL 输入，也不支持 response_format、style 参数。

Gemini 图片

用对话接口，必须设置 "stream": false；modalities 可不填（默认就是文字加图片，填的话写 ["text", "image"]）；max_tokens 可不填，填写时须为正整数，实际支持上限由模型服务校验。不要带 temperature、top_p 等参数。图片以 Base64 编码的形式放在回复内容里：

第 1 步：生成

curl --fail-with-body --max-time 210 https://api.302api.com/v1/chat/completions \
  -H "Authorization: Bearer ${API302_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-3.1-flash-image","messages":[{"role":"user","content":"生成一张蓝色圆形图片，无文字"}],"modalities":["text","image"],"stream":false}' \
  -o gemini-response.json

第 2 步：取出图片并保存

import base64, json, re
from pathlib import Path

result = json.loads(Path("gemini-response.json").read_text())
if "error" in result:
    raise SystemExit(result["error"])
content = result["choices"][0]["message"]["content"]
parts = content if isinstance(content, list) else [{"type": "text", "text": content or ""}]
saved = 0
for part in parts:
    if part.get("type") == "image_url":
        match = re.match(r"data:image/(\w+);base64,(.+)", part["image_url"]["url"], re.S)
        if match:
            saved += 1
            Path(f"gemini-{saved}.{match.group(1)}").write_bytes(base64.b64decode(match.group(2)))
    elif part.get("text"):
        print(part["text"])
print(f"saved {saved} image(s)", result.get("usage"))

在客户端里使用

• GPT 图片：要用客户端里的“绘画 / 图片生成”功能（调用 OpenAI 图片接口的那种），服务商地址填 https://api.302api.com，Key 同上，模型填 gpt-image-2.5-flare。在普通聊天窗口里选它不会出图。
• Gemini 图片：可以在聊天窗口里用，但要在这个模型的设置里关闭流式输出、关闭温度（Temperature）和 Top-P，最大输出 Token 可不填，或按模型能力设置。
• 客户端不支持生图时，直接用上面的代码最省事，或者把“让 AI 帮你配置生图”指令发给 Codex 等 AI 工具，让它帮你配置。

常见报错

流式输出

开启后，回复会像打字一样一段段返回，适合聊天界面；在请求里加上 "stream": true 即可。

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["API302_KEY"], base_url="https://api.302api.com/v1",
                max_retries=0, timeout=210.0)
stream = client.chat.completions.create(
    model="gpt-6-luna",
    messages=[{"role": "user", "content": "用一句话介绍自己"}],
    max_completion_tokens=256,
    stream=True,
    stream_options={"include_usage": True},
)
usage, finish = None, None
for chunk in stream:
    if chunk.usage:
        usage = chunk.usage
    for choice in chunk.choices:
        print(choice.delta.content or "", end="", flush=True)
        finish = choice.finish_reason or finish
print("\nfinish:", finish, "usage:", usage)

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["API302_KEY"], base_url="https://api.302api.com/v1",
                max_retries=0, timeout=210.0)
stream = client.responses.create(model="gpt-6-luna", input="用一句话解释递归",
                                 max_output_tokens=256, stream=True)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print("\nusage:", event.response.usage)
    elif event.type in ("response.failed", "response.incomplete", "error"):
        raise SystemExit(f"未正常完成：{event.type}")

建议用 SDK 解析，不要自己按网络分块拆 JSON。流开始后 HTTP 状态码已经是 200，中途出错会以 error 事件返回；finish_reason 为 length 表示达到输出上限被截断了。

参数与输出上限

“输出上限”就是最多让模型写多少 Token。不同接口的字段名不同：

为什么建议设置：每次请求前，系统会按“最多可能花多少钱”临时冻结一部分余额，结束后按实际用量结算、退回多余部分。上限设得合理，冻结的钱就少，余额不多时可以避免返回 402。

填写时须为正整数，实际支持的输入上下文与输出上限由所选模型及厂商接口校验，本站不再设置统一的体积或 Token 上限。开关类参数请传 true / false，不要加引号。

计费方式

按实际用了多少 Token 收费，用多少扣多少，没有月费。价格以美元 / 百万 Token 标注，扣费时按汇率换算成人民币。

一次请求的费用 = 普通输入 + 缓存读取 + 缓存写入 + 输出，各部分按各自单价计算，互不重复。模型的思考过程计入输出。

长上下文加价

输入特别长时，官方会对整笔请求加价，本站同样执行：

缓存与图片

• Claude 缓存：返回的 input_tokens 只是没命中缓存的部分，总输入还要加上 cache_read_input_tokens 和 cache_creation_input_tokens。缓存写入分 5 分钟和 1 小时两档，价格不同；打了缓存标记也不保证一定命中。
• 图片：按文字输入、图片输入、文字输出、图片输出分别计价；本站 Gemini 图片模型命中缓存的部分免费。

费用（USD）=（普通输入 × 输入价 + 缓存读取 × 缓存读价 + 5 分钟写入 × 写入价 + 1 小时写入 × 1 小时写入价 + 输出 × 输出价）÷ 1,000,000

账单内部保留更高精度，页面显示的金额经过四舍五入，无法据此精确反推单笔费用。如果某次上游没有返回可核对的用量，这笔会先进入人工核对，不会按估算扣费。

python3 -B billing-calculator/calculator.py \
  --prices billing-calculator/public-prices-2026-10-25.json \
  --request billing-calculator/examples/anthropic-cache.json

报错怎么办

先看 HTTP 状态码和返回里的 error.code，对照下表处理。大部分问题出在 Key、模型名称或余额上。

需要人工帮助时，请提供：时间、模型名称、接口路径、状态码、error.code、请求编号（响应头 X-302API-Request-ID）、客户端名称与版本。不要发送 Key 或完整的私密对话。联系技术支持

兼容说明

为了让常见工具开箱即用，网关会自动处理少数上游不支持的参数，不会因此报错。一般用户不需要关心这一节。

字段级参考见 OpenAPI 描述文件。