概览

快速开始

JoyToken 是一个 OpenAI 兼容模型网关。应用侧只需要接入统一接口，模型路由、API Key 策略、钱包额度、用量记录和账单归因由 JoyToken 处理。

选择接入路径

接入方式适合场景
API服务端直接调用、任意语言、需要完整控制请求和错误处理
客户端 SDK已经在用 OpenAI SDK，希望只替换 baseURL 和 apiKey
Agent SDK需要工具调用、多步任务、状态管理和可治理的 Agent 调用链

当前稳定公开的 OpenAI 兼容处理器是 POST /openai/v1/chat/completions。模型列表当前由 Console 使用 GET /api/v1/models 提供。

1. 创建 API Key

在 Console 创建 API Key。明文 Key 只展示一次，保存到服务端环境变量：

.env
$JOY_TOKEN_API_KEY="jt_xxx"
$JOY_TOKEN_OPENAI_BASE_URL="https://api-dev.joytokens.ai/openai/v1"

生产环境建议每个应用、环境、任务类型拆分 API Key，例如 prod-chat-api、rag-indexer、cursor-dev。

2. 发送第一条请求

向 OpenAI 兼容接口发送标准 HTTP 请求：

Shell
$curl https://api-dev.joytokens.ai/openai/v1/chat/completions \
>  -H "Content-Type: application/json" \
>  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
>  -d '{
>    "model": "openai/gpt-4o-mini",
>    "messages": [
>      { "role": "user", "content": "Say hello from JoyToken" }
>    ]
>  }'

也可以让路由器自动选择模型：

Auto routing
$curl https://api-dev.joytokens.ai/openai/v1/chat/completions \
>  -H "Content-Type: application/json" \
>  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
>  -H "X-Request-ID: quickstart-001" \
>  -d '{
>    "model": "auto",
>    "tier": "standard",
>    "messages": [
>      { "role": "user", "content": "Write a short onboarding message." }
>    ],
>    "stream": false
>  }'

3. 使用 OpenAI SDK

使用官方 OpenAI SDK，并把 base URL 指向 JoyToken：

TypeScript
1import OpenAI from "openai";
2
3const client = new OpenAI({
4  apiKey: process.env.JOY_TOKEN_API_KEY,
5  baseURL: "https://api-dev.joytokens.ai/openai/v1",
6});
7
8const response = await client.chat.completions.create({
9  model: "openai/gpt-4o-mini",
10  messages: [{ role: "user", content: "Explain JoyToken in one sentence." }],
11});
Python
1from openai import OpenAI
2import os
3
4client = OpenAI(
5    api_key=os.environ["JOY_TOKEN_API_KEY"],
6    base_url="https://api-dev.joytokens.ai/openai/v1",
7)
8
9response = client.chat.completions.create(
10    model="openai/gpt-4o-mini",
11    messages=[{"role": "user", "content": "Explain JoyToken in one sentence."}],
12)
13
14print(response.choices[0].message.content)

4. 验证请求是否走通

成功响应会保留 OpenAI-compatible 的 choices 和 usage 结构。JoyToken 还会在响应头和 metadata 中补充治理信号：

信号位置含义
X-DAOE-Used-Model响应头实际命中的模型
X-DAOE-Used-Provider响应头实际命中的提供方
metadata.tier响应体 / 流式元数据本次计费和路由 tier
metadata.billing响应体 / 流式元数据Credits、tokens、成本相关字段
metadata.latency响应体 / 流式元数据路由、首 token、流式响应耗时

下一步阅读：

  • 认证：Key、请求头、服务端代理和轮换。
  • 路由：model: "auto"、tier、固定模型、回退如何工作。
  • 客户端 SDK：TypeScript SDK、Go SDK 和 Agent 使用方式。