Token API v2 文档

本文档介绍 Token 产品的对话补全接口。接口与 OpenAI Chat Completions 兼容： 已有 OpenAI SDK 的客户只需把 Base URL 换成本平台地址、API Key 换成平台密钥即可接入。 由平台统一路由到模型服务，并按本次实际输入/输出 token 数计费。

1. 基础信息

• 接口地址：https://api.starloft.cn/v2/token
• 请求格式：application/json
• 鉴权方式：API Key + HMAC-SHA256 签名（与平台其它产品一致，见「请求鉴权」）
• 可授权接口标识：token_chat

2. 调用前提

1. 账户已完成个人实名（realname_status ≥ 1）。
2. 已创建 API 密钥，且密钥权限包含 token_chat（或为 all）。
3. 调用模型已在平台后台登记并启用（未登记/停用返回 400「模型未开通或已停用」）。
4. 账户有可用 Token 积分或余额（调用前平台会按预估用量预检，不足时返回 402）。

3. 对话补全

POST /v2/token/chat/completions

鉴权方式（两种任选其一）：

• Bearer（推荐，兼容 OpenAI SDK / 现成工具）：只需 Authorization: Bearer <API Key>， 无需计算签名，可直接把 Base URL 配成 https://api.starloft.cn/v2/token。
• 签名（与其它接口一致）：X-Api-Key + X-Sign-Version + X-Timestamp + X-Sign；v2 还需 X-Nonce。

# 方式一：Bearer（OpenAI SDK 默认方式）
curl https://api.starloft.cn/v2/token/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Key>" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'

# 方式二：签名（v2）
curl https://api.starloft.cn/v2/token/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <API Key>" \
  -H "X-Sign-Version: hmac_sha256_v2" \
  -H "X-Timestamp: <秒级时间戳>" \
  -H "X-Nonce: <16-128 位随机串>" \
  -H "X-Sign: <HMAC-SHA256 签名>" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'

Bearer 模式下 API Key 即凭证，请勿写入前端代码或公开日志；建议为每个工具单独签发密钥并限制额度。 其它产品接口（人脸核验/短信/验证码/要素核验）仍只接受签名方式。

非流式响应与 OpenAI 一致，usage 字段为本次实际用量：

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "deepseek-v4-flash",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "你好！"}, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 8, "completion_tokens": 5, "total_tokens": 13}
}

流式响应为 text/event-stream，每行 data: {...}，以 data: [DONE] 结束；平台会自动注入 stream_options.include_usage=true 以获取最后一块的 usage。

4. 计费规则

• 按实际用量计费：输入 token × 输入单价 + 输出 token × 输出单价，单价单位为元/百万 token，每个模型单独配置。
• 积分口径：10 积分 = 1 元，积分包售价可优惠（例如 9 元 100 积分）；扣费时按本次费用折算积分扣减，支持小数积分。
• 计费顺序：先扣 Token 积分包，不足部分按比例扣余额；实际扣费金额四舍五入保留 4 位小数。
• 平台返回 4xx/5xx 或请求未送达模型服务的网络异常不计费；扣费失败不回滚响应，平台记录审计日志并支持对账补扣。
• 模型服务中断（超时、断流、客户端断开）导致拿不到 usage 时，平台默认不计费，只把按已产生内容估算的 token（约 3 字符 = 1 token）落库并标记 usage_estimated=1，待上游账单核对后按实际用量补收。
• 超时口径：timeout_seconds（默认 1200s = 20 分钟，可配 5~1800s）只限制等模型服务响应头/首字节的时间，不是整条请求的总超时；长回答持续输出期间会一直读，中途连续 120s 无新数据才中断，单次调用绝对上限 2 小时（服务端可用环境变量调整）。
• 中断的请求不应自动重试：重试会产生新的调用记录并可能再次计费（当前未提供请求级幂等键）；需要补齐结果时请先查用量，或改用非流式请求。

5. 错误码