从 API Key到生产请求。

这里是可直接使用的接入说明。示例基于统一 Base URL，端点清单与仓库中的 relay OpenAPI 契约保持一致。

01 / START

Quickstart

登录控制台创建 API Key。
从公开模型目录复制模型 ID。
把密钥放在服务端环境变量中，然后发送第一条请求。

创建或管理 API Key 打开模型目录

02 / AUTH

鉴权与 Base URL

所有受保护端点使用 Bearer Token。不要把 API Key 放进浏览器代码、公开仓库、日志或截图。

Base URLhttps://tokenboat.com/v1

请求头Authorization: Bearer $TOKEN_BOAT_API_KEY

03 / CALL

三种调用方式

Curl

export TOKEN_BOAT_API_KEY="your_api_key"
export MODEL_ID="choose_from_the_model_catalog"

curl https://tokenboat.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN_BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL_ID"'",
    "messages": [{"role": "user", "content": "Hello from Token Boat"}]
  }'

Python

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["TOKEN_BOAT_API_KEY"],
    base_url="https://tokenboat.com/v1",
)

response = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "Hello from Token Boat"}],
)
print(response.choices[0].message.content)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOKEN_BOAT_API_KEY,
  baseURL: "https://tokenboat.com/v1",
});

const response = await client.chat.completions.create({
  model: process.env.MODEL_ID,
  messages: [{ role: "user", content: "Hello from Token Boat" }],
});
console.log(response.choices[0].message.content);

04 / STREAM

流式输出

对支持流式响应的模型设置 stream: true，并逐块读取 Server-Sent Events。客户端应处理连接中断和不完整的最后一块。

const stream = await client.chat.completions.create({
  model: process.env.MODEL_ID,
  messages: [{ role: "user", content: "Stream a short answer" }],
  stream: true,
});

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

05 / RECOVER

错误与重试

错误响应包含 HTTP 状态和消息。记录请求时间、端点、模型 ID 与返回状态；不要记录完整密钥或敏感提示词。

Status	含义	建议动作
400	请求字段或模型参数无效	修正请求后再试
401	API Key 缺失、无效或已失效	检查 Authorization 头与密钥状态
403	账户或模型无访问权限	检查账户权限与模型可用性
429	触发请求或 Token 限制	读取 Retry-After，指数退避并加入抖动
5xx	网关或上游暂时不可用	仅对幂等或可安全重放请求进行有限重试

06 / LIMITS

限流

具体 RPM、TPM 和并发上限取决于账户、模型与当前策略，因此文档不硬编码一个可能失真的数字。遇到 429 时以响应头和账户控制台为准。

限制并发并设置客户端超时。
对 429 和暂时性 5xx 使用带抖动的指数退避。
生成类任务避免盲目重放；先查询任务状态。
需要提升上限时，从支持中心提交账户与使用场景。

07 / REFERENCE

主要端点

以下为主要公共端点；模型实际支持哪些端点，以模型详情中的兼容端点为准。

方法	路径	用途
GET	`/v1/models`	列出当前可访问模型
POST	`/v1/responses`	Responses API，适合工具与多轮工作流
POST	`/v1/chat/completions`	OpenAI 兼容对话补全
POST	`/v1/messages`	Anthropic Messages 兼容端点
POST	`/v1/embeddings`	生成文本嵌入向量
POST	`/v1/images/generations`	提交图像生成请求
POST	`/v1/audio/speech`	文本转语音
POST	`/v1/audio/transcriptions`	音频转录
POST	`/v1/videos`	提交视频生成任务

接口契约来源：docs/openapi/relay.json