API 参考

TokenMark 提供 OpenAI 兼容接口。除 GET /v1/models 外，/v1/chat/completions 及以 /chat/completions 结尾的路径均透传至上游，参数语义与 OpenAI 一致。

Base URL

https://tokenmark.org/v1

鉴权

所有请求需携带 API 密钥：

Authorization: Bearer sk-你的密钥

• 密钥在门户「API 密钥」页创建，sk- 开头；
• 未携带或密钥无效返回 401；
• 命中 IP 白名单外来源返回 403。

端点

POST /v1/chat/completions

对话补全。请求体与 OpenAI chat/completions 兼容，支持 model / messages / stream / temperature / max_tokens / tools 等标准参数。

请求示例（非流式）：

curl https://tokenmark.org/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chat",
    "messages": [{"role": "user", "content": "你好"}]
  }'

请求示例（流式 SSE）：

curl -N https://tokenmark.org/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chat",
    "messages": [{"role": "user", "content": "写一首诗"}],
    "stream": true
  }'

流式响应为 text/event-stream，每个数据块格式与 OpenAI 一致（data: {...}，末尾 data: [DONE]）。

响应体（非流式）：

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1755200000,
  "model": "chat",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 34,
    "total_tokens": 46
  }
}

GET /v1/models

返回可用模型目录（OpenAI 格式），供客户端自动列出模型：

curl https://tokenmark.org/v1/models \
  -H "Authorization: Bearer sk-你的密钥"

错误码

错误响应格式：{"error": "..."}（部分校验错误附带 issues 字段）。

HTTP	场景	说明
400	参数校验失败	请求体不符合 chat/completions 格式，响应含 issues
401	未认证 / 密钥无效	缺少或错误的 Authorization 头
402	余额不足	insufficient balance, please top up；另有配额变体：日消费上限、硬配额、组织配额、密钥限额
403	IP 白名单拒绝	source IP not allowed for this key
429	限流 / 并发超限	命中速率限制或 too many concurrent requests
500	内部错误	上游故障或未处理异常，请稍后重试或联系支持

常见错误处理建议

• 402 余额不足：到门户「钱包」充值，实时到账；
• 429 并发超限：降低并发（当前单密钥并发有上限），重试建议指数退避；
• 403 IP 白名单：在门户密钥设置中把你当前的出口 IP 加入白名单；
• 400 校验失败：检查 model 是否存在于 GET /v1/models，以及 messages 结构是否合法。