API 指南

API 参考

JoyToken 当前对开发者公开的是一个 OpenAI 兼容的模型网关。应用侧可以继续使用 OpenAI SDK、LangChain、Cursor、Claude Code、Codex CLI 等工具的 OpenAI-compatible 配置方式接入，JoyToken 在网关侧补上 API Key 校验、策略约束、模型路由、钱包预冻结和用量记录。

本页只描述当前工程已经暴露的公开接口。Console、API Key 管理、策略配置、账单管理等后台接口目前主要由 JoyToken Console 调用，不作为稳定开发者 API 写入这里。

基础 URL

场景基础 URL
OpenAI 兼容模型调用https://api-dev.joytokens.ai/openai/v1
公开模型目录https://api-dev.joytokens.ai

认证

模型调用需要 JoyToken API Key。推荐使用 Authorization header，因为它和 OpenAI SDK 以及常见 AI 工具的配置方式一致。

Recommended
Authorization: Bearer $JOY_TOKEN_API_KEY

网关当前也接受 X-API-Key，主要用于兼容旧客户端或手写 HTTP 请求。

Compatibility
X-API-Key: $JOY_TOKEN_API_KEY

如果两个 header 同时存在，当前网关会优先读取 X-API-Key。迁移到 Bearer 认证时，不要在同一个请求里保留旧的 X-API-Key。

当前公开接口

接口是否需要 API Key用途
POST /openai/v1/chat/completions需要OpenAI 兼容聊天补全，支持非流式和 SSE 流式响应
GET /api/v1/models不需要公开模型目录，用于模型广场、模型选择器和接入前发现

请求头

请求头必填说明
Authorization模型调用必填Bearer $JOY_TOKEN_API_KEY
X-API-Key可选兼容型认证请求头；不建议新接入优先使用
Content-Type建议application/json
X-Request-ID可选用于日志、账单排障和调用链定位；如果不传，网关会生成内部 request id

响应头

响应头场景说明
X-DAOE-Used-Model模型调用成功实际命中的模型
X-DAOE-Used-Provider模型调用成功实际服务本次请求的提供方
X-DAOE-Failover流式调用触发故障切换值为 1 表示本次流式调用曾发生提供方故障切换

响应元数据

非流式调用成功时，网关会尽量把 JoyToken 元数据合并到 OpenAI 兼容 JSON 的 metadata 字段。流式调用会在 [DONE] 前追加一条 metadata SSE 记录。

常见字段包括：

字段说明
modelJoyToken 选中的模型
tier实际使用的计费/路由档位
score路由评分
model_recommendation候选模型推荐信息，依赖路由器返回
latency路由、提供方、流式等阶段耗时
billing.credits_used本次调用计算出的 Credits 消耗
billing.input_tokens / billing.output_tokens账单侧使用的输入/输出 token 数

错误形态

模型调用错误使用 OpenAI 兼容结构：

Error response
1{
2  "error": {
3    "message": "missing api key",
4    "type": "missing_api_key"
5  }
6}

错误排查时优先记录 X-Request-ID、请求中的 model / tier、HTTP status、error.type，以及成功响应里的 X-DAOE-Used-Model 和 X-DAOE-Used-Provider。