文档

发出第一个请求、读懂返回结果，需要知道的全部内容。

快速开始

所有请求都发到同一个接入点。在 model 字段里写你要的模型，Switchyard 会把它转接到对应的厂商。

cURL

curl https://api.switchyardai.io/v1/chat/completions \
  -H "Authorization: Bearer sk-sy-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Say hi in five words."}]
  }'

鉴权

在控制台的 API Keys 页生成密钥，作为 bearer token 附在每次请求上。密钥归属账户，不绑定单个模型。

密钥不会自动过期。在控制台吊销后，该密钥上的流量数秒内停止。

请求头	值
Authorization	Bearer sk-sy-...

请求格式

Switchyard 使用与 OpenAI chat completions 相同的 schema，现有 SDK 把 base URL 指过来即可。

字段	类型	说明
model	string	模型页上的任意 slug。
messages	array	标准的 role/content 消息列表。
stream	boolean	设为 true 走 SSE 流式。
max_tokens	integer	可选。请看下面关于推理 token 的说明。
mask_pii	boolean	可选，Switchyard 扩展字段。默认跟随账户设置。

关于推理模型

部分模型会在 content 之外返回 reasoning_content（思维链），我们原样透传。两点需要注意：它的 token 计入 completion_tokens，是要计费的；max_tokens 设得太小会被思维链吃光，导致 content 为空、finish_reason 为 length。请留出余量。

流式

设 "stream": true 即可在生成过程中接收 SSE，无论哪家厂商应答，格式一致。

Node · OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.switchyardai.io/v1",
  apiKey: "sk-sy-...",
});

const stream = await client.chat.completions.create({
  model: "deepseek-v4-flash-0731",
  stream: true,
  messages: [{ role: "user", content: "Write a haiku about rail yards." }],
});

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

PII 脱敏

请求离开我们之前，会有一层过滤把邮箱、电话、卡号替换为占位符，收到响应后再还原。厂商永远看不到原值。

脱敏作用于消息正文，代码块不处理以免破坏示例。若你的上游已经处理过，可在单次请求里设 "mask_pii": false，或在设置里改默认值。

masking

sent to provider    "contact: [MASKED_EMAIL_1], card [MASKED_PAN_1]"
returned to you     "contact: ada@acme.co, card 4242 4242 4242 4242"

我们不做的事

我们不存储请求与响应正文；占位符映射表只在请求期间存在于内存，绝不写入磁盘或日志。

计费与额度

账户使用预付额度，响应返回时按 token 扣减。每个模型的价格公开在模型页。

方式	状态
注册赠送试用额度	现已可用
银行卡	即将开放
USDT / USDC	即将开放

新账户自带试用额度，可以先发真实请求再决定。充值方式正在接入，在此之前额度用完请联系我们。

常见问题

每个模型要用不同的密钥吗？

不需要。一把密钥通向所有已上线模型，换模型只改 model 字段，不换凭证。

某家厂商挂了会怎样？

受影响模型的请求会返回明确错误，而不是静默切到别的模型。你永远知道是哪个模型真正回答了你。

可以设置花费上限吗？

可以——在控制台按密钥设置日或月上限，超出即拒绝，直到重置或你上调。

有免费额度吗？

新账户有少量试用额度用于测试真实请求。没有订阅套餐。

你们会拿我的数据训练、或留存我的 prompt 吗？

不会。我们不存储请求与响应正文。每次调用保留的是元数据：模型、token 数、延迟、花费、是否脱敏。

为什么有的模型标着「待上线」？

因为我们还不能稳定地提供它。与其让你对着一个会失败的东西开发，不如先标出来。