API 参考 - TOENK API · DeepSeek专精·AI模型API加速平台

🔑 认证鉴权

所有 API 请求需要在 HTTP Header 中携带 API Key 进行身份认证。API Key 可在密钥管理页面创建和管理。

请求头格式

HTTP Headers

Authorization: Bearer your-api-key-here
Content-Type: application/json

POST /v1/chat/completions 聊天补全

创建聊天补全。向模型发送消息序列，模型会根据接收到的消息生成响应。这是最核心的 API 接口。

请求参数

参数	类型	必填	说明
`model`	string	✅ 是	模型ID，如 `deepseek-chat`、`gpt-4o`、`deepseek-v4-flash`。完整列表见模型列表
`messages`	array	✅ 是	消息数组，包含 `role` 和 `content`。支持 `system`、`user`、`assistant`、`tool` 角色
`max_tokens`	integer	❌ 否	最大生成 token 数，默认根据模型设定
`temperature`	number	❌ 否	采样温度 (0-2)，默认 1。越低结果越确定，越高越随机
`top_p`	number	❌ 否	核采样参数 (0-1)，默认 1。建议只调整 temperature 或 top_p 之一
`stream`	boolean	❌ 否	是否启用流式响应，默认 `false`。启用后以 SSE 格式返回
`stop`	string/array	❌ 否	停止序列，最多4个字符串。遇到这些序列时停止生成
`frequency_penalty`	number	❌ 否	频率惩罚 (-2 到 2)，默认 0。正值减少重复
`presence_penalty`	number	❌ 否	存在惩罚 (-2 到 2)，默认 0。正值鼓励讨论新话题
`tools`	array	❌ 否	函数/工具调用定义数组，模型可选择调用这些工具
`tool_choice`	string/object	❌ 否	工具选择策略：`"auto"`、`"none"`、`"required"` 或指定具体工具
`user`	string	❌ 否	用户标识，用于监控和检测滥用
`seed`	integer	❌ 否	随机种子，固定后可获得更确定性的输出
`response_format`	object	❌ 否	指定响应格式，如 `{"type":"json_object"}` 强制JSON输出

请求示例

📤 请求

curl https://toenk-api.com/v1/chat/completions \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "system", "content": "你是一个有用的助手。"},
      {"role": "user", "content": "介绍一下TOENK API平台"}
    ],
    "max_tokens": 500,
    "temperature": 0.7
  }'

响应示例

📥 响应

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "TOENK API 是一个..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 180,
    "total_tokens": 205,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  },
  "system_fingerprint": "fp_xxx"
}

响应字段说明

字段	类型	说明
`id`	string	本次请求的唯一标识
`object`	string	对象类型，固定为 `chat.completion`
`created`	integer	创建时间戳 (Unix)
`model`	string	实际使用的模型ID
`choices[].message.content`	string	模型生成的回复内容
`choices[].finish_reason`	string	结束原因：`stop`（正常结束）、`length`（达到最大token）、`tool_calls`（工具调用）
`usage.prompt_tokens`	integer	输入 token 数
`usage.completion_tokens`	integer	输出 token 数
`usage.total_tokens`	integer	总 token 数
`usage.prompt_tokens_details.cached_tokens`	integer	缓存命中的 token 数，命中部分享受折扣

GET /v1/models 模型列表

获取平台上所有可用的模型列表。响应包含模型ID、所属组织和端点类型等信息。

请求示例

cURL

curl https://toenk-api.com/v1/models \
  -H "Authorization: Bearer your-api-key-here"

响应示例

📥 响应

{
  "object": "list",
  "success": true,
  "data": [
    {
      "id": "deepseek-chat",
      "object": "model",
      "created": 1626777600,
      "owned_by": "deepseek",
      "supported_endpoint_types": ["openai"]
    }
    // ... 更多模型
  ]
}

当前可用模型（共19个）

      提示：模型列表是动态的，请始终使用 GET /v1/models 获取最新列表。以下为当前平台已上线模型：
    

模型ID	提供商	类型
`deepseek-chat`	DeepSeek	对话
`deepseek-reasoner`	DeepSeek	推理
`deepseek-v4-flash`	DeepSeek	对话/快速
`deepseek-v4-pro`	DeepSeek	推理/专业
`gpt-4o`	OpenAI	多模态
`gpt-4o-mini`	OpenAI	对话/轻量
`gpt-5`	OpenAI	对话
`gpt-5.4`	OpenAI	对话
`claude-opus-4`	Anthropic	推理/专业
`claude-sonnet-4`	Anthropic	对话
`gemini-2.5-pro`	Google	推理/多模态
`gemini-2.5-flash`	Google	对话/快速
`qwen3.6-plus`	阿里通义	对话
`qwen3.6-flash`	阿里通义	对话/快速
`grok-4.1`	xAI	对话
`kimi-k2.6`	Moonshot	对话
`glm-5`	智谱	对话
`glm-5.1`	智谱	对话
`doubao-seed-2.0-pro`	字节跳动	对话

📡 流式响应 (SSE)

TOENK API 支持 Server-Sent Events (SSE) 流式响应。设置 stream: true 后，响应将以 chunk 形式逐片返回。

请求示例

cURL 流式请求

curl https://toenk-api.com/v1/chat/completions \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "讲个故事"}],
    "stream": true
  }'

流式响应格式

每个数据块格式如下（SSE标准格式）：

SSE Chunk

data: {"choices":[{"delta":{"content":"从前"},"index":0}]}

data: {"choices":[{"delta":{"content":"有座山"},"index":0}]}

data: [DONE]

Python 流式处理示例

Python

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key-here",
    base_url="https://toenk-api.com/v1"
)

stream = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

      💡 提示：流式响应适合实时对话场景。响应中的 finish_reason 只在最后一个 chunk 中出现。记得检查 [DONE] 信号结束流。
    

⏱️ 速率限制

为保证平台稳定性，API 调用受到速率限制。限速策略因用户等级而异。

用户等级	每分钟请求上限 (RPM)	每分钟 Token 上限 (TPM)
🆓 免费用户	60	100,000
💎 付费用户	500	1,000,000
🏢 企业用户	3000+	10,000,000+

限速响应

当达到速率限制时，API 返回 429 Too Many Requests，响应中包含 Retry-After 头指示重试时间。

限速响应示例

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": {
    "message": "Rate limit exceeded. Please retry in 30 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

限速最佳实践

实现 指数退避 (Exponential Backoff) 重试策略
监控 Retry-After 响应头，尊重服务器建议
使用 并发控制，避免突发大量请求
考虑使用 流式响应 而非批量短请求
缓存重复请求的结果以减少 API 调用

⚠️ 错误码与错误处理

API 使用标准的 HTTP 状态码指示请求结果。所有错误响应均包含 JSON 格式的错误信息。

状态码	错误类型	说明	处理方式
`400`	Bad Request	请求参数错误，如缺少必填字段、格式错误	检查请求参数和格式
`401`	Unauthorized	API Key 无效或缺失	检查 `Authorization` 头是否正确
`402`	Payment Required	余额不足，需要充值	登录平台充值后再重试
`429`	Too Many Requests	超出速率限制	等待 `Retry-After` 后重试，实现退避策略
`500`	Internal Server Error	服务器内部错误	稍后重试，如持续报错请联系支持
`503`	Service Unavailable	服务暂时不可用（维护中）	稍后重试，关注状态页

错误响应格式

错误响应示例 (401)

{
  "error": {
    "message": "Incorrect API key provided. You can find your API key at https://toenk-api.com/keys.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

错误处理最佳实践

Python 错误处理

from openai import OpenAI
from openai import APIError, RateLimitError, APIConnectionError
import time

client = OpenAI(api_key="your-key", base_url="https://toenk-api.com/v1")

def chat_with_retry(**kwargs):
    max_retries = 3
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            wait = 2 ** attempt * 5  # 指数退避
            print(f"限速，等待 {wait}s...")
            time.sleep(wait)
        except APIConnectionError:
            time.sleep(10)
        except APIError as e:
            print(f"API错误: {e}")
            break
    return None

# 使用
response = chat_with_retry(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello"}]
)

🏆 最佳实践

1. 合理设置参数

Temperature：对话场景推荐 0.7-0.9；代码/推理场景推荐 0.1-0.3
Max Tokens：根据场景设置，避免输出过长增加费用
System Prompt：善用系统消息设定模型行为和风格

2. 性能优化

多轮对话时，使用 prompt caching 减少重复输入
不需要实时输出时，关闭 stream 降低连接开销
批量短请求合并为单次请求，减少往返

3. 成本控制

使用 max_tokens 限制每次调用费用
简单任务使用 deepseek-chat 或 qwen3.6-flash 等性价比更高的模型
监控 usage 中的 token 消耗，合理规划
缓存命中部分享受75%折扣，尽量复用常见输入前缀

4. 错误处理

总是实现 重试逻辑，特别是对 429 和 500 错误
使用 指数退避 避免加重服务器负担
对 401 错误检查 API Key 是否正确
对 402 错误提示用户充值

📘 API 参考文档

📋 目录

🔑 认证鉴权

请求头格式

POST /v1/chat/completions 聊天补全

请求参数

请求示例

响应示例

响应字段说明

GET /v1/models 模型列表

请求示例

响应示例

当前可用模型（共19个）

📡 流式响应 (SSE)

请求示例

流式响应格式

Python 流式处理示例

⏱️ 速率限制

限速响应

限速最佳实践

⚠️ 错误码与错误处理

错误响应格式

错误处理最佳实践

🏆 最佳实践

1. 合理设置参数

2. 性能优化

3. 成本控制

4. 错误处理