把模型接入你的应用

01 / GET STARTED

快速开始

1. 登录工作台（本地默认 http://localhost:5173），进入 API Keys 页面创建一把密钥。密钥以 rly_live_ 开头，完整密钥只会显示一次，请立即保存。
2. 把密钥写入服务端环境变量，例如 RELAY_API_KEY=rly_live_xxxxxxxx，不要在代码里硬编码。
3. 用下面的命令发第一个请求，把 rly_live_你的APIKey 替换成真实密钥。
4. 在工作台「用量」页面查看本次调用的 Token 消耗与扣费。

02 / AUTHENTICATION

认证与密钥

所有接口使用同一套认证：请求头携带 Authorization: Bearer rly_live_xxx。密钥可随时在工作台创建、撤销；被撤销的密钥立即失效。

• 密钥前缀固定为 rly_live_，格式校验不通过会直接返回 401。
• 服务端密钥与展示用会话（session）互不影响；API 调用全部走密钥认证。
• 不要把上游 sk- 开头的密钥传给 RelayOS——上游密钥只保存在服务端环境变量。

03 / MODELS

模型列表

不要把模型名写死在客户端。每个账号可访问的模型可能不同，启动时或定期读取此接口获取实时可用列表。

curl http://localhost:8788/v1/models \
  -H "Authorization: Bearer rly_live_你的APIKey"

响应示例

{
  "object": "list",
  "data": [
    {"id": "openai/gpt-5.6-luna", "object": "model", "owned_by": "OpenAI"},
    {"id": "openai/claude-sonnet-4-5", "object": "model", "owned_by": "Anthropic"}
  ]
}

模型名说明

模型 id 采用 provider/模型名 格式，例如 openai/gpt-5.6-luna、openai/claude-sonnet-4-5。调用 Chat / Responses 接口时 model 字段必须填写此 id（而非上游原始模型名）。真实上游启用时模型目录来自 OpenAI；演示模式会返回本地演示模型 relay-demo。

04 / CHAT COMPLETIONS

对话接口

OpenAI 兼容的聊天补全接口，返回单条或多条候选回复，支持流式。请求体最大 4 MB。

curl

curl http://localhost:8788/v1/chat/completions \
  -H "Authorization: Bearer rly_live_你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

Python SDK（openai）

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["RELAY_API_KEY"],
    base_url="http://localhost:8788/v1",
)

result = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}],
)
print(result.choices[0].message.content)

Node.js（openai 包）

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.RELAY_API_KEY,
  baseURL: "http://localhost:8788/v1",
});

const result = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [{ role: "user", content: "你好" }],
});
console.log(result.choices[0].message.content);

响应结构

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "model": "openai/gpt-4o-mini",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "你好！有什么可以帮你？"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 8, "completion_tokens": 4, "total_tokens": 12}
}

05 / STREAMING

流式输出

Chat Completions 请求设置 "stream": true 后返回 SSE 流。逐行读取 data: 数据块，取 choices[0].delta.content 增量拼装文本，以 data: [DONE] 作为结束标志。

curl http://localhost:8788/v1/chat/completions \
  -H "Authorization: Bearer rly_live_你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "写一个短故事"}],
    "stream": true
  }'

SSE 数据格式

data: {"id":"chatcmpl_...","choices":[{"delta":{"role":"assistant"},"index":0}]}
data: {"id":"chatcmpl_...","choices":[{"delta":{"content":"从前"},"index":0}]}
data: {"id":"chatcmpl_...","choices":[{"delta":{"content":"有座山"},"index":0}]}
data: {"id":"chatcmpl_...","choices":[{"delta":{},"finish_reason":"stop","index":0}]}
data: [DONE]

Python 流式示例

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["RELAY_API_KEY"], base_url="http://localhost:8788/v1")
stream = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "写一个短故事"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

06 / RESPONSES API

Responses 接口

兼容 OpenAI Responses API 的客户端（如 Agents SDK、部分新框架）。请求体会转发给上游，模型必须使用 /v1/models 返回的有效 id。

curl http://localhost:8788/v1/responses \
  -H "Authorization: Bearer rly_live_你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "input": "你好"
  }'

07 / MORE PROTOCOLS

其它协议与能力

RelayOS 同时兼容以下入口，按你的 SDK 语言选择即可。

08 / BILLING

计费与用量

所有真实模型按 Token 用量计费、美元计价。单次费用 =（输入 Token × 输入单价 + 输出 Token × 输出单价），单价按模型配置（美元 / 百万 Token），单次扣费向上取整到 0.01 美元。

• 每个模型独立配置输入 / 输出单价，以工作台模型列表展示的价格为准。
• 新用户注册赠送 0.15 美元 体验额度。
• 每次调用的 Token 与费用明细可在工作台「用量」「账单」页面查看，接口：GET /api/usage/logs、GET /api/billing/transactions。
• 余额不足时接口返回 402，充值后即可恢复调用。

09 / ERRORS

错误处理

所有错误统一返回 OpenAI 风格错误体，可按 error.type 做程序化处理：

{
  "error": {
    "message": "具体错误信息",
    "type": "invalid_request_error"
  }
}

10 / SECURITY

安全建议

• 密钥只保存在服务端：环境变量、密钥管理服务（如 Vault / KMS），绝不下发到前端。
• 生产环境必须启用 HTTPS，避免密钥在传输中被窃听。
• 不要把完整密钥截图发到群聊、Issue 或公开文档；泄露后立即在工作台撤销并重建。
• 按需限制调用频率与用量，避免异常流量产生高额账单。