平台接入 SDK

Upthos Relay 兼容 Anthropic / OpenAI / Gemini 三套官方协议，任何支持自定义 base URL 的官方 SDK 都可直接接入，业务代码不用改。本文给出四类常用接入方式的最小可运行配置和必看注意事项。

通用准备

1. 在 API 密钥 创建 Key，必须分配到对应平台的分组：
   • Claude 流量 → Anthropic 协议分组（如 Claude Max、Claude 入门/标准/进阶）
   • OpenAI / Codex 流量 → OpenAI 协议分组（如 Codex 基础/标准、OpenAI 企业级）
   • Gemini 流量 → Google 协议分组
2. 分组绑错或未分组会返回 403 permission_error。
3. API Key 在三种鉴权头任选其一即可，按优先级：Authorization: Bearer → x-api-key → x-goog-api-key。

1. Anthropic / Claude Agent SDK

注入两个环境变量后，官方 Anthropic SDK、Claude Agent SDK、Claude Code 都可直接使用，无需改业务代码。

export ANTHROPIC_BASE_URL=https://relay.upthos.com
export ANTHROPIC_AUTH_TOKEN=sk-...

ANTHROPIC_BASE_URL 不带 /v1 后缀，SDK 会自行拼接。
ANTHROPIC_AUTH_TOKEN 走 Bearer 认证（Agent SDK / Claude Code 默认）；旧版 SDK 用 ANTHROPIC_API_KEY（走 x-api-key）也支持。

Claude Agent SDK（推荐用于嵌入业务）

// npm install @anthropic-ai/claude-agent-sdk
import { query } from '@anthropic-ai/claude-agent-sdk'

for await (const msg of query({
  prompt: '帮我看下这个仓库的目录结构',
  options: { model: 'claude-sonnet-4-6' },
})) {
  console.log(msg)
}

# pip install claude-agent-sdk
from claude_agent_sdk import query, ClaudeAgentOptions

async for msg in query(
    prompt="帮我看下这个仓库的目录结构",
    options=ClaudeAgentOptions(model="claude-sonnet-4-6"),
):
    print(msg)

Anthropic SDK（直接 Messages API）

// npm install @anthropic-ai/sdk
import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({
  baseURL: 'https://relay.upthos.com',
  apiKey: process.env.UPTHOS_API_KEY,
})

const msg = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: '你好' }],
})

# pip install anthropic
from anthropic import Anthropic

client = Anthropic(
    base_url="https://relay.upthos.com",
    api_key=os.environ["UPTHOS_API_KEY"],
)

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

完整端点（/v1/messages、/v1/messages/count_tokens、/v1/models、/v1/usage）见 Anthropic API 接口。

2. OpenAI SDK

export OPENAI_BASE_URL=https://relay.upthos.com/v1     # 注意：这个要带 /v1
export OPENAI_API_KEY=sk-...

// npm install openai
import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://relay.upthos.com/v1',
  apiKey: process.env.UPTHOS_API_KEY,
})

// Chat Completions
const resp = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: '你好' }],
})

// Responses API（Agent / 工具调用）
const r = await client.responses.create({
  model: 'gpt-5.5',
  input: '你好',
})

# pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="https://relay.upthos.com/v1",
    api_key=os.environ["UPTHOS_API_KEY"],
)

resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "你好"}],
)

支持的端点：

• POST /v1/chat/completions —— 标准 chat
• POST /v1/responses —— Responses API（Agent / 工具调用 / WebSocket 双向流）
• POST /v1/images/generations、POST /v1/images/edits —— OpenAI 兼容同步图像 API，返回标准 {data: [{url|b64_json}]} 结构。OpenAI SDK 可直接使用。
• POST /v1/images/tasks、GET /v1/images/tasks/:id、POST /v1/images/tasks/:id/cancel、POST /v1/images/tasks/batch、POST /v1/images/uploads —— RayRelay 异步任务，立即返 task_id，客户端轮询拿稳定 R2 URL；支持中途取消、img2img 参考图上传。

两条路径计费完全一致（矩阵价 × fx_rate × flat 1.0），自由按场景选用。SDK 兼容选同步；需要长任务、可取消、可分享 URL 选异步。旧的 /v1/tasks/:id、/v1/tasks/batch、/v1/tasks/:id/cancel 仍可用，但响应附带 Deprecation: true 头，请逐步迁到 /v1/images/tasks/* 新路径。

3. Codex CLI（@openai/codex）

如果客户希望以 CLI Agent 子进程形式嵌入到内部平台（而不是用 OpenAI SDK 直接发请求），用 Codex：

# ~/.codex/config.toml
model_provider = "upthos"
model = "gpt-5.6-sol"
review_model = "gpt-5.6-sol"
model_reasoning_effort = "high"
model_context_window = 272000

[model_providers.upthos]
name = "upthos"
base_url = "https://relay.upthos.com"
wire_api = "responses"
requires_openai_auth = true

// ~/.codex/auth.json
{ "OPENAI_API_KEY": "sk-..." }

详细说明见 Codex 快速开始。

如果只是程序化调 OpenAI 协议、不通过 CLI，用上一节的 OpenAI SDK 即可。

4. Gemini SDK

@google/genai（新版统一 SDK）支持自定义 endpoint：

// npm install @google/genai
import { GoogleGenAI } from '@google/genai'

const ai = new GoogleGenAI({
  apiKey: process.env.UPTHOS_API_KEY,
  httpOptions: { baseUrl: 'https://relay.upthos.com' },
})

const resp = await ai.models.generateContent({
  model: 'gemini-2.5-pro',
  contents: '你好',
})

# pip install google-genai
from google import genai

client = genai.Client(
    api_key=os.environ["UPTHOS_API_KEY"],
    http_options={"base_url": "https://relay.upthos.com"},
)

resp = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="你好",
)

裸 REST 调用（不依赖 SDK）：

curl https://relay.upthos.com/v1beta/models/gemini-2.5-pro:generateContent \
  -H "x-goog-api-key: $UPTHOS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "你好" }] }]
  }'

支持的端点：

• GET /v1beta/models
• POST /v1beta/models/{model}:generateContent
• POST /v1beta/models/{model}:streamGenerateContent

通用注意事项

1. 模型 ID 用官方裸 ID：claude-sonnet-4-6、claude-opus-4-7、claude-haiku-4-5、gpt-5.5、gemini-2.5-pro。完整列表和路由说明见 支持的模型。
2. Streaming / SSE 自动透传：客户端开 stream: true 或调 :streamGenerateContent 即可，网关不改格式、不缓存。
3. Tool use / Prompt caching 透传：业务代码原样写就行，无需为中转层做适配。
4. 请求体大小：网关层硬限制为 10 MB（超过返回 413）。此外部分上游供应商有更紧的字节墙（典型 5 MB），比模型 token 上限先到，多张 base64 大图请求容易触发 4xx。建议用 /v1/images/uploads 上传后引用 URL，或在客户端先压缩。
5. API Key 安全：API Key 等同账号凭证。强烈建议在你方服务端代理后再暴露给业务，不要塞到前端 Bundle、移动端二进制或公开仓库。
6. 错误格式按调用协议返回：Anthropic 路径返回 Anthropic 错误格式，OpenAI 路径返回 OpenAI 错误格式，Gemini 路径返回 Google 错误格式。SDK 自带的错误处理可直接复用。
7. 可调用模型受 group 限制：业务代码里调到了 group 不支持的 model 会返回 404 not_found_error。建议先调 GET /v1/models 或 GET /v1beta/models 确认当前 Key 能用哪些模型。

上线前自检清单

• API Key 已分配到正确平台的 group
• base URL 配置正确（Anthropic 不带 /v1，OpenAI 带 /v1，Gemini 用 /v1beta）
• API Key 仅存在于服务端环境变量 / Secret Manager，不在前端代码或 git 仓库中
• 通过 GET /v1/models（或 /v1beta/models）验证当前 Key 可用模型
• 至少跑通一次非流式调用 + 一次流式调用
• 长上下文 / 多图请求 body 不超过 10 MB（且尽量控制在 5 MB 以内，避开上游字节墙）
• 业务侧已捕获 401 / 403 / 429 / 503 并加上重试或降级逻辑

如需排查问题，请记录响应头里的 x-request-id，并在控制台联系客服。