API 指南

API 指南

JoyToken 面向开发者提供 OpenAI 兼容和 Anthropic 兼容的模型接口。

通用 API

Base URL 使用 环境 中的 JOY_TOKEN_API_BASE_URL。

接口认证用途
GET /api/v1/models无公开模型列表
GET /api/v1/models/metaBearer 或 X-API-Key目录筛选元数据
GET /api/v1/pricingBearer 或 X-API-Key面向客户的档位兑换价格

模型描述可通过可选的 locale 查询参数指定语言：locale=zh 返回中文，locale=en 返回英文；不传时默认返回英文。

curl -sS "https://api.joytokens.ai/api/v1/models?locale=zh"

选择协议接口

项目值
接口POST /openai/v1/chat/completions
Base URLhttps://api.joytokens.ai/openai/v1
认证Authorization: Bearer $JOY_TOKEN_API_KEY
响应内容choices[0].message.content

Responses 接口为 POST /openai/v1/responses。input 支持字符串或 message input items；非流式文本位于 output[0].content[0].text。

curl -N -sS -X POST "https://api.joytokens.ai/openai/v1/responses" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "input": "用一句话解释 JoyToken。",
    "instructions": "保持简洁。",
    "max_output_tokens": 256,
    "stream": false
  }'

图片生成接口为 POST /openai/v1/images/generations。model 必须为 auto，prompt 为必填字段。n、size、quality、style、response_format 等图片选项会透传给所选 Provider；请省略 Provider 特有选项，除非所有候选图片模型都支持该选项。

图片生成仅支持非流式响应。不要传 stream: true，也不要按 SSE 消费此接口：保持请求连接，直到 JoyToken 在生成完成后一次性返回完整的 application/json。生成图片位于 data；根据 response_format 从 data[0].url 或 data[0].b64_json 读取结果。

curl -sS -X POST "https://api.joytokens.ai/openai/v1/images/generations" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: image-$(date +%s%3N)" \
  -d '{
    "model": "auto",
    "prompt": "A neon JoyToken logo on a black background",
    "n": 1,
    "size": "1024x1024"
  }'
{
  "created": 1793395200,
  "data": [
    {
      "url": "https://example.com/generated.png",
      "revised_prompt": "A neon JoyToken logo on a black background"
    }
  ]
}
curl -N -sS -X POST "https://api.joytokens.ai/openai/v1/chat/completions" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: test-$(date +%s%3N)" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "user", "content": "你好，帮我测试一下网关链路" }
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'

不要在同一个请求里同时传 Authorization 和 X-API-Key。如果两个都存在，当前网关会优先读取 X-API-Key。

通用响应信息

字段位置用途
usage响应体token 统计
metadata.billing响应体 / 流式 metadataJoyToken 计费信息
X-Request-ID请求头日志和排障关联