DOCUMENTATION

Relay AI 接入文档

为所需模型通道创建 API Key，通过对应的兼容接口发起调用，并在控制台查看额度、用量与消费明细。

通道 Key按项目和模型通道创建、管理调用凭证

统一接口沿用熟悉的 OpenAI 调用方式

模型可查询通过鉴权接口获取可用模型 ID

用量可核对在控制台查看请求与消费明细

Base URLhttps://api.relay-ai.space/v1

01 · QUICK START

三步完成第一次调用

只需要创建 Key、设置环境变量，然后发送请求。

创建 API Key

登录控制台，在 API Key 页面创建一把用于当前项目的 Key。完整值请立即安全保存。

前往创建

保存到环境变量

不要把 Key 写入浏览器代码或提交到代码仓库。

export RELAY_AI_KEY="你的完整 Key"

发送请求

收到 HTTP 200 且响应中包含模型输出，即表示接入成功。

02 · CHAT COMPLETIONS

发送对话请求

当前公开接入方式使用 POST /v1/chat/completions。以下示例使用页面当前发布的模型 ID。

curl https://api.relay-ai.space/v1/chat/completions \
  -H "Authorization: Bearer $RELAY_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role":"user","content":"请用一句话介绍你自己"}]
  }'

响应结构 · HTTP 200

{
  "id": "chatcmpl-relay_example",
  "object": "chat.completion",
  "model": "claude-sonnet-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好，我是通过 Relay AI 接入的模型。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 18,
    "total_tokens": 31
  }
}

03 · MODELS

查询这把 Key 可用的模型

调用前先获取模型列表，再把返回的 id 原样填入请求的 model 字段。

GET/v1/models

需要 Authorization Bearer Key。返回结果中的模型范围以当前 Key 的权限为准。

curl https://api.relay-ai.space/v1/models \
  -H "Authorization: Bearer $RELAY_AI_KEY"

模型 ID 区分大小写；不要根据展示名称自行拼写。

04 · CLAUDE CODE

Claude Code

通过 Anthropic Messages 协议连接 Relay AI。复制下面的命令，在同一个终端中启动 Claude Code。

安装并启动

npm install -g @anthropic-ai/claude-code

export RELAY_AI_KEY="YOUR_FULL_KEY"
export ANTHROPIC_BASE_URL="https://api.relay-ai.space"
export ANTHROPIC_AUTH_TOKEN="$RELAY_AI_KEY"
export ANTHROPIC_MODEL="claude-sonnet-5"

claude

Base URL 不要带 /v1https://api.relay-ai.space 由 Claude Code 自动拼接 Messages 路径。

进入后检查连接运行 /status，确认 Base URL 已指向 Relay AI；需要切换时运行 /model。

Claude Code 网关配置说明

05 · CODEX CLI

Codex CLI

为 Codex 增加一个 Relay AI 模型提供方。密钥只从环境变量读取，不需要写进 config.toml。

~/.codex/config.toml

model = "gpt-5.5"
model_provider = "relay-ai"

[model_providers.relay-ai]
name = "Relay AI"
base_url = "https://api.relay-ai.space/v1"
wire_api = "responses"
env_key = "RELAY_AI_KEY"

安装并启动

npm install -g @openai/codex
export RELAY_AI_KEY="YOUR_FULL_KEY"
codex

Codex CLI 使用 Responses 协议。模型名必须与当前 Key 的 /v1/models 返回值一致；更换模型时只修改 config.toml 顶部的 model。

Codex 自定义模型提供方说明

06 · CC SWITCH

CC Switch

在 CC Switch 中分别保存 Claude Code 与 Codex 配置，之后可从桌面端切换。

CLAUDE CODE添加自定义服务商

API Format: Anthropic Messages
Endpoint: https://api.relay-ai.space
API Key: Relay AI 完整 Key
Model: claude-sonnet-5

CODEX添加自定义服务商

API Format: OpenAI Responses
Base URL: https://api.relay-ai.space/v1
API Key: Relay AI 完整 Key
Model: gpt-5.5

在顶部切换到 Claude 或 Codex，再点击 + 添加自定义服务商。
按上表填写并保存，回到服务商卡片启用 Relay AI。
关闭已经打开的 CLI 进程，再开一个新终端启动对应客户端。

CC Switch 服务商配置说明

07 · HERMES

Hermes

使用 Hermes 当前版本的 Custom endpoint 向导，选择 OpenAI Chat Completions 协议。

hermes model在会话外运行，选择 Custom endpoint。

依次填写连接信息Base URL: https://api.relay-ai.space/v1 · Model: claude-sonnet-5 · API mode: chat_completions

重新启动 Hermes进入会话后可用 /model 在已经配置的模型之间切换。

也可以手动配置

# ~/.hermes/config.yaml
custom_providers:
  - name: relay-ai
    base_url: https://api.relay-ai.space/v1
    key_env: RELAY_AI_KEY
    api_mode: chat_completions

model:
  default: claude-sonnet-5
  provider: custom:relay-ai

把 RELAY_AI_KEY 写入 ~/.hermes/.env 或系统密钥环境，不要把真实 Key 提交到仓库。

Hermes 自定义端点说明

08 · SDK & CLIENTS

SDK 与其他客户端

支持自定义 OpenAI Base URL 的 SDK、插件或桌面客户端，通常只需下面四项。

Base URLhttps://api.relay-ai.space/v1

API Key你在 Relay AI 创建的完整 Key

模型 ID从鉴权后的 /v1/models 返回结果复制

接口类型OpenAI Chat Completions

Node.js、Python 与 cURL 的可复制示例见上方“对话请求”。如果客户端自动补 /v1，请把它的 Base URL 改为仅包含域名，避免出现 /v1/v1。

09 · API KEYS

按用途拆分 Key

建议按应用、环境或设备创建不同 Key。出现异常时，只需停用受影响的凭证。

创建与命名用容易识别的名称标记项目与环境。

独立启停每把 Key 可单独重命名、停用、启用或删除。

默认脱敏列表隐藏完整值，查看前需要再次验证身份。

10 · USAGE & BILLING

核对额度、用量与消费

模型页展示当前发布价格；登录后可查看实际请求数、输入与输出 Tokens，以及消费趋势。

最近 30 天用量从汇总指标查看总体情况，再进入用量页核对每日消费。

查看用量

11 · SECURITY

把 API Key 当作密码管理

仅保存在服务端使用环境变量或密钥管理服务，不要放进浏览器代码、公开仓库、截图或聊天记录。

监控不采集内容服务监控与告警不采集输入内容、模型输出或完整 Key；请求仍会发送给所选模型服务完成推理。

12 · HELP

常见错误排查

401Key 无效或未携带

确认请求头是 Authorization: Bearer YOUR_KEY，并检查 Key 完整且处于启用状态。

404路径或模型不存在

确认接口地址没有重复的 /v1，并从鉴权后的 /v1/models 返回结果复制模型 ID。

429额度、并发或频率受限

检查额度与 Key 状态，降低并发后稍等片刻再试。仍未恢复时联系管理员。

5xx服务暂时不可用

查看页面顶部的服务状态并稍后重试。请使用有限次数的退避重试，避免持续快速请求。