// Quick Start

使用文档

通过环境变量配置 API 地址和密钥，无需改动代码即可接入 PioModel。

01API 端点

Anthropic SDK（Claude Code 等）
https://api.piomodel.com
OpenAI SDK / HTTP
https://api.piomodel.com/v1
KEY
在控制台「API Key 管理」创建密钥，形如 sk-your-api-key。请求时作为 Authorization: Bearer sk-... 传入。

02环境变量设置

Windows 配置

仅当前终端窗口有效，关闭后失效。适合临时测试。

# PowerShell (valid for current session only)
$env:ANTHROPIC_BASE_URL = "https://api.piomodel.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-your-api-key"

macOS / Linux 配置

仅当前终端窗口有效，关闭后失效。适合临时测试。

# bash / zsh (valid for current session only)
export ANTHROPIC_BASE_URL="https://api.piomodel.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-api-key"

03工具接入

主流 AI 编程工具都能直连 PioModel，设置好环境变量或下面的配置即可。

Claude Code CLI

Anthropic 官方命令行工具，通过环境变量连接 PioModel，无需改动代码。

前往「API Key 管理」页面一键下载配置脚本 → 
# bash / zsh (valid for current session only)
export ANTHROPIC_BASE_URL="https://api.piomodel.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-api-key"

配置完成后启动：

claude

Codex CLI

OpenAI 官方 Codex 命令行工具，走 /v1/responses 接口。注意 base_url 必须带 /v1。

编辑 ~/.codex/config.toml：

model_provider = "piomodel"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.piomodel]
name = "piomodel"
base_url = "https://api.piomodel.com/v1"
wire_api = "responses"
env_key = "PIOMODEL_API_KEY"

然后设置 API Key 到环境变量：

# bash / zsh
export PIOMODEL_API_KEY="sk-your-api-key"

配置完成后启动：

codex

Cursor / Windsurf

在设置里覆盖 OpenAI 接口地址与密钥即可。

{
  "openai.baseUrl": "https://api.piomodel.com/v1",
  "openai.apiKey": "sk-your-api-key"
}

Cline（VS Code）

在 Cline 里选择 OpenAI Compatible 提供方，填入地址、密钥与模型名。

Provider   : OpenAI Compatible
Base URL   : https://api.piomodel.com/v1
API Key    : sk-your-api-key
Model      : claude-sonnet-4-5-20250929

04调用示例

from anthropic import Anthropic

# Automatically reads ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN from env
client = Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)

安装： pip install anthropic / openai · npm install openai

05流式响应

请求体加入 stream: true 即可启用 SSE 流式输出，适合聊天界面实时渲染。

from anthropic import Anthropic

client = Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a haiku about Go."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

06格式自动转换

PioModel 在网关侧做 Anthropic Messages ↔ OpenAI Chat 双向透明转换。这意味着：同一个模型，你既能用 Anthropic 风格调，也能用 OpenAI 风格调——一套代码，任意模型。

两种风格的主要字段对应关系：

Anthropic 风格OpenAI 风格说明
systemmessages[role=system]系统提示位置不同，网关自动搬运
max_tokens（必填）max_tokens（可选）缺省时网关按模型上限处理
content 分块数组content 字符串文本/图像块与字符串互转
stop_reasonfinish_reason结束原因字段名映射
TIP
已有 OpenAI 代码想调 Claude？只改 base_url 与 model 两处即可，消息结构不用动。

07多模态

图像生成走同一网关与密钥，按量计费。

img = client.images.generate(
    model="gpt-image-2",
    prompt="夜幕下的城市天际线，电影感",
    size="1024x1024",
)
print(img.data[0].url)

08函数调用

用 OpenAI 风格的 tools 定义可调用函数，模型会在需要时返回 tool_calls，由你的代码执行后回填结果。

tools = [{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "查询某城市天气",
    "parameters": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"],
    },
  },
}]

resp = client.chat.completions.create(
    model="claude-sonnet-4-5-20250929",
    messages=[{"role": "user", "content": "上海今天天气怎么样？"}],
    tools=tools,
)
print(resp.choices[0].message.tool_calls)

09错误处理

/v1/* 路径遵循 OpenAI 错误格式，错误 JSON 包含 type / code / message。

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_quota",
    "message": "余额不足"
  }
}

常见错误码

HTTP说明
401API Key 无效或未提供
402余额不足，请前往充值
429触发限流或每日配额耗尽
503上游渠道全部不可用（熔断中）
查看全部模型与价格 →