--- title: "API 文档：Base URL 与 SDK 示例" canonical: https://relayswitch.io/zh/docs generated: 2026-11-02T10:50:21.767Z source: https://api.relayswitch.io/v1/catalog base_url: https://api.relayswitch.io/v1 --- 文档 # 快速上手 一个 Base URL，OpenAI 和 Anthropic 两种格式。设置地址，带上密钥，选一个模型 id，接入就完成了。 [获取密钥](https://app.relayswitch.io/console)[模型 id](https://relayswitch.io/zh/models) Base URL`https://api.relayswitch.io/v1` 鉴权头`Authorization: Bearer ` 模型 id`"model": "claude-opus-5-5"` 01 ## 发起请求：OpenAI 格式 任何 OpenAI SDK 原样可用，只改 base\_url 和密钥。 bash 1`curl https://api.relayswitch.io/v1/chat/completions \` 2 `-H "Authorization: Bearer $RELAYSWITCH_KEY" \` 3 `-H "Content-Type: application/json" \` 4 `-d '{` 5 `"model": "claude-opus-5-5",` 6 `"messages": [{"role": "user", "content": "你好"}]` 7 `}'` python 1`from openai import OpenAI` 2 3`client = OpenAI(` 4 `base_url="https://api.relayswitch.io/v1",` 5 `api_key="YOUR_RELAYSWITCH_KEY",` 6`)` 7`reply = client.chat.completions.create(` 8 `model="claude-opus-5-5",` 9 `messages=[{"role": "user", "content": "你好"}],` 10`)` 11`print(reply.choices[0].message.content)` node 1`import OpenAI from "openai";` 2 3`const client = new OpenAI({` 4 `baseURL: "https://api.relayswitch.io/v1",` 5 `apiKey: process.env.RELAYSWITCH_KEY,` 6`});` 7`const reply = await client.chat.completions.create({` 8 `model: "claude-opus-5-5",` 9 `messages: [{ role: "user", content: "你好" }],` 10`});` 11`console.log(reply.choices[0].message.content);` 流式输出同样：设置 `stream: true`，读取 server-sent events。 node 1`const stream = await client.chat.completions.create({` 2 `model: "claude-opus-5-5",` 3 `messages: [{ role: "user", content: "写一首五言绝句" }],` 4 `stream: true,` 5`});` 6`for await (const chunk of stream) {` 7 `process.stdout.write(chunk.choices[0]?.delta?.content ?? "");` 8`}` 02 ## 发起请求：Anthropic 格式 Claude 系列模型同时支持 Anthropic Messages 格式，地址仍是 https://api.relayswitch.io/v1。 python 1`import anthropic` 2 3`client = anthropic.Anthropic(` 4 `base_url="https://api.relayswitch.io/v1",` 5 `api_key="YOUR_RELAYSWITCH_KEY",` 6`)` 7`message = client.messages.create(` 8 `model="claude-sonnet-5-5",` 9 `max_tokens=256,` 10 `messages=[{"role": "user", "content": "你好"}],` 11`)` 12`print(message.content[0].text)` node 1`import Anthropic from "@anthropic-ai/sdk";` 2 3`const client = new Anthropic({` 4 `baseURL: "https://api.relayswitch.io/v1",` 5 `apiKey: process.env.RELAYSWITCH_KEY,` 6`});` 7`const message = await client.messages.create({` 8 `model: "claude-sonnet-5-5",` 9 `max_tokens: 256,` 10 `messages: [{ role: "user", content: "你好" }],` 11`});` 12`console.log(message.content[0]);` 03 ## 模型 id 334 个模型。id 与模型页上打印的完全一致。 ### 在哪里找 [模型页](https://relayswitch.io/zh/models) 列出每个 id 和实时价格。API 本身也应答 `GET https://api.relayswitch.io/v1/models`，完整 OpenAPI 文档在 `https://api.relayswitch.io/openapi.json`。 ### 速率限制 限制按密钥设置，在控制台创建或编辑密钥时指定。超限的密钥返回 `429`，响应头 `retry-after` 给出等待秒数。 04 ## 不经模型的网页搜索 POST /v1/search 单独调用聊天工具 web\_search 用的同一个搜索：传入 query，返回排序结果，按次计费。 bash 1`curl https://api.relayswitch.io/v1/search \` 2 `-H "Authorization: Bearer $RELAYSWITCH_KEY" \` 3 `-H "Content-Type: application/json" \` 4 `-d '{"query": "cloudflare workers 定时任务", "max_results": 5, "freshness": "month"}'` `query` 最多 400 字；`max_results` 1 到 10（默认 5）；`freshness` 取 day、week、month 或 year。 返回每条结果的标题、链接、摘要和发布日期，费用在 `charge_usd`，签名回执在响应头 `x-uplink-receipt`。单价在目录的 server\_tools 里；受密钥预算与限额约束，不受模型白名单约束。 05 ## 不注册，按次付费 不带密钥的请求返回 402 和 x402 付款要求；按里面的结账链接付款，再带付款 id 重发同一请求。 bash 1`# 1. 不带密钥：返回 402 和报价` 2`curl -i https://api.relayswitch.io/v1/chat/completions \` 3 `-H "Content-Type: application/json" \` 4 `-d '{"model": "claude-opus-5-5", "messages": [{"role": "user", "content": "你好"}]}'` 5 6`# 2. 按 402 里的结账链接付款，再带付款 id 重发` 7`curl https://api.relayswitch.io/v1/chat/completions \` 8 `-H "X-PAYMENT: xp_..." \` 9 `-H "Content-Type: application/json" \` 10 `-d '{"model": "claude-opus-5-5", "messages": [{"role": "user", "content": "你好"}]}'` 报价是该请求的估算向上取整到整数美元，最低 $1；402 响应体和 `PAYMENT-REQUIRED` 头给出金额、结账链接和 `extra.payment_id`。付款到账前重发返回 402 `x402_payment_pending`；到账后请求运行，响应带 `PAYMENT-RESPONSE` 和签名回执，剩余金额可用同一 id 继续请求。适用于 chat、messages、responses、embeddings 和 search 路由；流式、别名和预设需要密钥。 06 ## 中转站术语 常见说法在这个密钥上各对应什么。 | 术语 | 在本站 | | --- | --- | | 中转站 | 本站：一个 Base URL，请求转发到各模型的线路，不换模型。每天公开检测，每次调用一张签名回执。 | | 倍率 | 没有倍率加价：按模型页的美元标价计费，输入与输出分别计价。多数模型低于开发商官方价，页面实时显示差额。 | | 渠道 | 每个模型多条线路。一条线路返回 5xx 或 429，请求自动转到下一条，价格不变。 | | 令牌 | 密钥以 sk-relay- 开头。每个密钥可设美元预算、模型白名单、每分钟请求数与 tokens 上限、月度上限、有效期和 IP 白名单；带 x-customer-id 的请求还可按终端用户限额。控制台有逐条请求日志、签名回执和账户审计记录。 | | 通知 | 密钥预算或周期限额到 50%、80%、100% 时邮件提醒，每个阈值每周期一次；可选的账户每日消费提醒。最多 3 个 HTTPS 地址接收签名的账户事件 webhook：余额不足、余额用尽、密钥到预算或限额、充值到账、扣款失败。 | | 额度 | 预付美元余额，用 USDT、USDC、BTC、ETH、SOL 充值。用完返回 402，充值后立即恢复。 | 07 ## 错误码 | 状态码 | 含义 | 处理 | | --- | --- | --- | | 400 | 请求无效 | 请求体不合法，或被安全规则拦截（guardrail\_blocked：未调用模型，不计费）。 | | 401 | 未授权 | 密钥缺失、格式错误或已吊销。检查 Authorization 头。 | | 402 | 余额不足 | 余额为零，或密钥达到预算或限额。充值或上调限额后立即恢复。 | | 404 | 未找到 | 模型 id 不在目录中。从模型页复制 id。 | | 429 | 请求过多 | 密钥超过速率限制。退避重试，或在控制台创建更高每分钟请求数的密钥。 | | 503 | 服务不可用 | 该模型暂时没有可用线路。退避重试或换一个模型 id。 | Related - [中转站术语表](https://relayswitch.io/zh/glossary) - [配置教程](https://relayswitch.io/zh/guides) - [每日真实模型检测](https://relayswitch.io/zh/proof) - [充值](https://relayswitch.io/zh/pay) - [状态](https://relayswitch.io/zh/status) - [English docs](https://relayswitch.io/docs) ## 设置地址，发出第一个请求 Base URL https://api.relayswitch.io/v1，密钥在控制台一分钟内拿到。 [模型与价格](https://relayswitch.io/zh/models)[获取密钥](https://app.relayswitch.io/console)