API 文档
通过 OpenAI 兼容接口调用平台模型。本文档覆盖鉴权、请求格式、返回结构、错误码与限额。
当前平台处于联调演示模式：接口鉴权、配额扣减和用量记录真实生效，但生成内容由平台演示逻辑返回，尚未转发至外部大模型。
配置正式上游后自动切换，无需修改客户端代码。
概览
平台提供与 OpenAI Chat Completions 兼容的 HTTP 接口。你可以直接使用 OpenAI 官方 SDK，或将现有请求的 base_url 指向本平台。
| 接口地址 | https://www.5ifbi.com/api/v1/chat/completions |
|---|---|
| 请求方法 | POST |
| Content-Type | application/json |
| 鉴权方式 | Authorization: Bearer sk-tzkp-... |
| 流式输出 | 暂不支持 stream=true |
鉴权
在 AI 控制台创建 API Key，完整密钥仅在创建时显示一次。调用时放在请求头中：
Authorization: Bearer sk-tzkp-xxxxxxxxxxxxxxxx密钥与账号绑定。吊销密钥后，使用该密钥的请求会立即返回 401。请勿在前端代码、公开仓库或聊天工具中暴露密钥。
模型别名
平台以别名对外提供模型能力。业务侧只需使用别名，上游模型调整由平台负责。
| 别名 | 适用场景 | 状态 |
|---|---|---|
tzkp-fast |
通用对话、摘要、分类、轻量任务 | 可用 |
tzkp-pro |
复杂推理、长文生成、高质量输出 | 可用 |
可通过 GET /api/v1/models 获取当前账号可用的别名列表。
发起请求
请求体字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型别名，如 tzkp-fast |
messages | array | 是 | 消息数组，最多 80 条；role 支持 system、user、assistant，content 为字符串 |
temperature | number | 否 | 0–2，默认 0.7 |
max_tokens | integer | 否 | 最大输出 token，平台上限 4096 |
stream | boolean | 否 | 当前仅支持 false |
输入内容总字符数不超过 24000。超出时返回 413 input_too_long。
返回结构
成功时返回 200，结构如下：
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1767225600,
"model": "tzkp-fast",
"choices": [
{
"index": 0,
"message": {"role": "assistant", "content": "..."},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 24,
"completion_tokens": 186,
"total_tokens": 210
},
"_gateway": {
"request_id": "req-...",
"mode": "demo",
"model_alias": "tzkp-fast"
}
}_gateway 为平台附加的调用元数据，不影响兼容性。usage 用于额度扣减；若上游未返回 usage，平台会按字符数估算。
响应头包含 X-Request-Id、X-TZKP-Mode 以及本次调用后的剩余额度 X-TZKP-Quota-Remaining。
调用示例
cURL
curl https://www.5ifbi.com/api/v1/chat/completions \
-H "Authorization: Bearer $TZKP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "tzkp-fast",
"messages": [
{"role": "user", "content": "用三点说明什么是 token 计量"}
],
"temperature": 0.7
}'Python（OpenAI SDK）
import os
from openai import OpenAI
client = OpenAI(
base_url="https://www.5ifbi.com/api/v1",
api_key=os.environ["TZKP_API_KEY"],
)
resp = client.chat.completions.create(
model="tzkp-fast",
messages=[{"role": "user", "content": "用三点说明什么是 token 计量"}],
)
print(resp.choices[0].message.content)
print(resp.usage.total_tokens)错误码
错误响应统一为：
{"error": {"message": "...", "type": "invalid_request_error", "code": "invalid_request"}}| HTTP | code | 说明 |
|---|---|---|
| 400 | invalid_request / invalid_json | 参数缺失、格式错误或请求体不是有效 JSON |
| 401 | invalid_api_key | 密钥缺失、无效或已吊销 |
| 402 | insufficient_quota | 套餐额度不足或已到期，请订购套餐 |
| 404 | model_not_found | 模型别名不存在 |
| 413 | input_too_long | 输入内容超过字符上限 |
| 415 | unsupported_media_type | Content-Type 不是 application/json |
| 429 | rate_limit_exceeded | 超过每分钟请求限制 |
| 502 | upstream_unavailable / upstream_error | 上游模型服务异常 |
| 503 | upstream_not_configured | 平台尚未完成上游配置 |
额度与限额
- 默认每分钟最多 60 次请求，具体以所购套餐为准。
- 额度按成功调用的
usage.total_tokens扣减；失败请求不扣减。 - 套餐额度有效期 365 天，续购在原到期日基础上顺延。
- 额度用尽或到期后返回
402，需在控制台订购新套餐。
安全与数据
- 平台不回显、不记录完整 API Key，只保存哈希值和前缀。
- 调用记录保存模型别名、token 数量、耗时、状态码和请求 ID，不保存提示词与生成内容。
- 请勿提交违法、侵权、涉密或未脱敏的个人信息。具体规则见 AI 服务条款。
- 发现密钥泄漏，请立即在控制台吊销并重新创建。