平台介绍
千川太初计划提供一套统一的模型 API 入口，让应用通过一致的请求结构管理模型、密钥与用量。当前页面用于确认产品信息架构和接入体验，不代表真实服务已经上线。
文档中的 https://api.tokey.example/v1 是专门用于界面演示的占位符，不是真实 API baseURL，也不得作为生产或测试接入地址。正式地址将在服务完成安全验收后单独发布。
基础信息
核心概念
应用侧只需要关心四类信息。平台后续负责模型路由、用量记录与统一错误格式。
baseURL
API 的统一访问入口。当前未发布，页面所示地址仅为占位示例。
https://api.tokey.example/v1apiKey
服务端调用凭证。正式密钥只在创建时完整展示一次。
tk_demo_••••••••••••model
请求体中的模型标识。以正式上线后的模型目录为准。
claude-sonnet-demorequest_id
请求唯一标识，用于排查、重试去重和对账。
req_demo_01安全接入
认证方式
将 API Key 作为 Bearer Token 放在请求头中。密钥只能保存在服务端环境变量或密钥管理服务，不能写入网页、移动端包、公开仓库和日志。
Authorization: Bearer tk_demo_xxxxxxxxxxxx
Content-Type: application/json
X-Request-Id: your-idempotency-key正式产品应支持密钥摘要存储、权限范围、有效期、IP 白名单、轮换与立即吊销。
第一条请求
快速开始
- 1创建项目
在控制台中隔离不同应用的成员、密钥、预算和调用记录。
- 2创建 API Key
仅在服务端保存密钥；创建后立即复制到安全的密钥管理服务。
- 3选择模型并发送请求
先在本地调试页验证请求结构，再接入业务服务。
curl --request POST \
--url https://api.tokey.example/v1/chat/completions \
--header "Authorization: Bearer tk_demo_xxxxxxxxxxxx" \
--header "Content-Type: application/json" \
--data '{
"model": "claude-sonnet-demo",
"messages": [
{
"role": "user",
"content": "你好，请用一句话介绍千川太初"
}
],
"stream": false
}'上述命令不可直接执行：baseURL、API Key 和模型 ID 均为占位演示值。
可用能力
模型列表
以下是产品界面使用的演示目录，不代表模型已接通、可用或采用所示价格。
| 模型 ID | 提供方 | 上下文 | 协议 | 状态 |
|---|---|---|---|---|
claude-sonnet-demo | Anthropic | 200K | Messages / Chat | 演示配置 |
claude-haiku-demo | Anthropic | 200K | Messages / Chat | 演示配置 |
gpt-general-demo | OpenAI | 128K | Chat / Responses | 待接入 |
gpt-mini-demo | OpenAI | 128K | Chat / Responses | 演示配置 |
gemini-pro-demo | 1M | Chat / Responses | 待接入 | |
gemini-flash-demo | 1M | Chat / Responses | 演示配置 |
响应结构
请求与响应
同步响应统一返回 choices 与 usage。正式版本还需明确流式事件、工具调用与多模态字段。
{
"id": "req_demo_01",
"object": "chat.completion",
"model": "claude-sonnet-demo",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "千川太初提供统一、清晰、可控的模型接入体验。"
},
"finish_reason": "stop"
}
],
"usage": {
"input_tokens": 18,
"output_tokens": 24,
"total_tokens": 42
}
}稳定性
错误处理
对 429 和可恢复的 5xx 使用带抖动的指数退避；不要自动重试参数错误和认证错误。
invalid_request请求结构、字段类型或参数组合不合法。
unauthorized缺少密钥，或 API Key 无效、过期。
model_not_found模型 ID 不存在，或当前项目无权访问。
rate_limit_exceeded并发、速率或预算上限已触发。
service_unavailable平台或上游服务暂时不可用。
生产准备