API 文档

快速开始

一个 chat completions 调用 —— 选择您熟悉的客户端。

curl https://api.tokengp.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKENGP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

鉴权

所有端点均要求在 Authorization 请求头中携带 API 密钥：

Authorization: Bearer sk-tokengp-<your-key>

• • 密钥在 /keys 页面创建，且仅展示一次 —— 请妥善保存。
• • 创建密钥时可选配置单密钥消费上限、RPM 速率限制、可用模型名单与来源 IP 白名单。设置了 IP 白名单后，仅名单内的 IPv4/CIDR 来源可调用（否则返回 403）；留空则不限制来源 IP。
• • 若密钥泄漏，在同一页面立即吊销；吊销即时生效。

列出模型

返回当前账户可调用的模型目录。即将上线和已停用的模型会被过滤掉。

示例

curl https://api.tokengp.com/v1/models \
  -H "Authorization: Bearer $TOKENGP_API_KEY"

• • 每条记录都带有 OpenAI 风格的字段（id、object、created、owned_by），并额外包含 display_name、input_price_per_1m、output_price_per_1m。大多数 OpenAI SDK 会忽略未知字段。

获取单个模型

按 id 查询单个模型。部分 SDK 会在客户端初始化时调用此端点校验模型名是否有效。

示例

curl https://api.tokengp.com/v1/models/qwen3.8-max \
  -H "Authorization: Bearer $TOKENGP_API_KEY"

• • 若 id 未知或已停用，返回 404 model_not_found。

对话补全

兼容 OpenAI 的 chat completions 端点。支持流式（SSE）与非流式两种模式。token 用量在上游计费，您的余额会在每次请求结束时扣减。

请求体

{
  "model": "qwen3.8-max",
  "messages": [
    {"role": "system", "content": "You are concise."},
    {"role": "user", "content": "Explain JWT in one sentence."}
  ],
  "max_tokens": 256,
  "temperature": 0.2,
  "stream": false
}

示例

curl https://api.tokengp.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKENGP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [{"role":"user","content":"hi"}],
    "max_tokens": 32
  }'

• • 如需流式响应，请设置 "stream": true。每个 SSE 事件形如 "data: {...}"，承载一个 OpenAI 风格的 chunk，其中 "choices[0].delta.content" 为增量文本，最后一个非 DONE chunk 会带上 "choices[0].finish_reason"。请持续消费，直到读到 "data: [DONE]"。
• • Vision 与 tool / function calling 会透传到支持这些能力的上游模型（如 qwen-vl-*、GPT 系列）。详见下方示例。
• • 在调用前会按最坏情况（input + max_tokens × output 价格）预扣余额。余额不足返回 402。
• • 推理模型（如 DeepSeek R1）会将思维链按 output_tokens 计费 —— 您看到的 usage.completion_tokens 可能超过可见消息的长度。思维链本身不会在响应中暴露，与 OpenAI o 系列保持一致。

{
  "model": "qwen3.8-max",
  "messages": [
    {"role": "user", "content": "What's the weather in Paris?"}
  ],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the current weather for a city.",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}

{
  "model": "qwen3.8-max",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What is in this image?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
    ]
  }]
}

Anthropic Messages（兼容）

Anthropic Messages API 兼容端点。基于 Anthropic SDK 的工具（Claude Code、ZCode 等）把 base URL 指向这里即可直接使用 TokenGP。请求在内部翻译为 chat-completions 处理，鉴权、模型名单、限速、计费与 OpenAI 端点完全一致。

请求体

{
  "model": "qwen3.8-max",
  "max_tokens": 1024,
  "system": "You are concise.",
  "messages": [
    {"role": "user", "content": "Explain JWT in one sentence."}
  ],
  "stream": false
}

示例

curl https://api.tokengp.com/v1/messages \
  -H "x-api-key: $TOKENGP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "max_tokens": 256,
    "messages": [{"role":"user","content":"hi"}]
  }'

• • 鉴权同时接受 Anthropic 风格的 "x-api-key: <key>" 和 "Authorization: Bearer <key>" —— 用的都是同一把 sk-tokengp-* 密钥。
• • 流式输出为标准 Anthropic SSE 事件（message_start、content_block_delta、message_delta、message_stop）。工具调用与图像输入双向翻译。
• • 请求中的 "thinking" 参数会被接受但不转发 —— 模型是否思考由上游自行决定。会输出推理过程的模型（如 DeepSeek）以标准 Anthropic "thinking" 内容块返回。
• • POST /v1/messages/count_tokens 返回本地估算值（约 4 字符/token），不打上游、不计费。

// %USERPROFILE%\.zcode\cli\config.json  (macOS/Linux: ~/.zcode/cli/config.json)
{
  "provider": {
    "tokengp": {
      "kind": "openai-compatible",
      "name": "TokenGP",
      "options": {
        "baseURL": "https://api.tokengp.com/v1",
        "apiKey": "sk-tokengp-...",
        "apiKeyRequired": true,
        "includeUsage": true
      },
      "models": {
        "qwen3.8-max": { "name": "Qwen3.8 Max" },
        "deepseek-v4-pro":   { "name": "DeepSeek V4 Pro" }
      }
    }
  },
  "model": { "main": "tokengp/qwen3.8-max", "lite": "tokengp/deepseek-v4-pro" }
}

向量

为一个或多个字符串生成向量。此端点仅接受 modality=embedding 的模型（对话模型会返回 400 wrong_endpoint）。

请求体

{
  "model": "text-embedding-v3",
  "input": "Hello, world."
}

示例

curl https://api.tokengp.com/v1/embeddings \
  -H "Authorization: Bearer $TOKENGP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-v3",
    "input": ["hello", "world"]
  }'

• • input 支持单个字符串或字符串数组。
• • 仅按 input token 计费（output_tokens = 0）。

图像生成

根据文本提示词生成图像。TokenGP 封装了阿里云的异步任务 API，因此客户端看到的是同步响应 —— 典型延迟 3-10 秒。按张计费，与分辨率无关。

请求体

{
  "model": "qwen-image-plus",
  "prompt": "a red apple on a wooden table",
  "n": 1,
  "size": "1024x1024"
}

示例

curl https://api.tokengp.com/v1/images/generations \
  -H "Authorization: Bearer $TOKENGP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-plus",
    "prompt": "a red apple on a wooden table",
    "n": 1,
    "size": "1024x1024"
  }'

• • 响应结构：{"created":<ts>,"data":[{"url":"<signed-oss-url>","revised_prompt":"..."}]}。
• • n 最多为 4。可选尺寸取决于具体模型；1024x1024 各模型均支持。
• • URL 是临时签名的 OSS 链接 —— 请在约 1 小时内下载并自行托管。
• • 内部轮询超时为 90 秒；过长的任务返回 504 upstream_timeout。

错误码

所有错误均以以下 JSON 结构返回：{"error":{"code":"...","message":"...","type":"..."}}。HTTP 状态码与 error.code 的对应关系如下表。

type 字段按家族对错误码归类，便于您据此分支处理，而无需逐个匹配名称：auth_error（密钥问题）、invalid_request_error（请求输入）、rate_limit（RPM 上限）、billing_error（余额 / 上限）、upstream_error（上游服务商）、server_error（少见 —— TokenGP 自身问题）。