API 参考文档
完整的 Dianwei API 端点、参数、错误码和最佳实践参考。
1. 概览
OpenAI 兼容端点
Chat Completions API
Base URL
https://api.dianwei.net/v1
Chat Completions
POST /v1/chat/completions
List Models
GET /v1/models
Anthropic 兼容端点
Messages API
Base URL
https://api.dianwei.net/anthropic
Messages
POST /anthropic/v1/messages
2. 认证
3. Chat Completions (OpenAI 兼容)
POST/v1/chat/completions
向模型发送对话消息并获取回复
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| model | string | Yes | — | 模型 ID，如 gpt-4o、claude-sonnet-4-6 |
| messages | array | Yes | — | 消息数组，每项含 role (system/user/assistant) 和 content |
| temperature | number | No | 1.0 | 采样温度 0-2，越高越随机 |
| top_p | number | No | 1.0 | 核采样，0.1 表示仅保留前 10% 概率质量的 token |
| max_tokens | integer | No | 模型最大值 | 生成最大 token 数 |
| stream | boolean | No | false | 是否流式返回，true 时以 SSE 格式增量推送 |
| stop | string / array | No | — | 停止词，遇到即终止生成 |
| frequency_penalty | number | No | 0 | 频率惩罚 -2.0 到 2.0，减少重复 |
| presence_penalty | number | No | 0 | 存在惩罚 -2.0 到 2.0，鼓励新话题 |
| n | integer | No | 1 | 生成 N 个候选回复 |
4. Messages API (Anthropic 兼容)
POST/anthropic/v1/messages
使用 Anthropic 原生 Messages API 格式调用模型
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| model | string | Yes | — | 模型 ID，如 claude-sonnet-4-6 |
| messages | array | Yes | — | 消息数组，每项含 role (user/assistant) 和 content |
| max_tokens | integer | Yes | — | 生成最大 token 数（Anthropic 必传） |
| temperature | number | No | 1.0 | 采样温度 0-1 |
| top_p | number | No | 1.0 | 核采样阈值 |
| top_k | integer | No | 不限制 | 仅从概率最高的 K 个 token 中采样 |
| stream | boolean | No | false | 是否流式返回 SSE |
| stop_sequences | array | No | — | 停止序列，遇到即终止生成 |
| system | string | No | — | 系统提示词（也可用 messages 中 role: system 的形式） |
5. 模型列表
GET/v1/models
获取所有可用模型列表及详细信息
curl https://api.dianwei.net/v1/models \ -H "Authorization: Bearer sk-YOUR_API_KEY"
响应示例：
{
"object": "list",
"data": [
{
"id": "claude-sonnet-4-6",
"object": "model",
"created": 1700000000,
"owned_by": "dianwei"
},
{
"id": "gpt-4o",
"object": "model",
"created": 1700000000,
"owned_by": "dianwei"
}
]
}模型目录
| Model ID | 类型 | 上下文 | 说明 |
|---|---|---|---|
| gpt-4o | OpenAI | 128K | GPT-4o 多模态旗舰模型 |
| gpt-4o-mini | OpenAI | 128K | GPT-4o Mini 轻量高效 |
| gpt-4.1 | OpenAI | 1M | GPT-4.1 超长上下文 |
| o4-mini | OpenAI | 200K | o4-mini 高推理模型 |
| claude-opus-4-7 | Anthropic | 200K | Claude Opus 4.7 最强推理 |
| claude-sonnet-4-6 | Anthropic | 200K | Claude Sonnet 4.6 性价比最优 |
| claude-haiku-4-5 | Anthropic | 200K | Claude Haiku 4.5 极速响应 |
| gemini-2.5-pro | 1M | Gemini 2.5 Pro 超长上下文 | |
| gemini-2.5-flash | 1M | Gemini 2.5 Flash 高速版 |
模型列表持续更新。使用 GET /v1/models 获取最新模型清单。
6. 错误码参考
错误响应格式
{
"error": {
"message": "Invalid API key",
"type": "invalid_request_error",
"param": null,
"code": "invalid_api_key"
}
}| HTTP | 名称 | 说明 | 处理建议 |
|---|---|---|---|
| 400 | Bad Request | 请求参数有误，请检查 JSON 格式、必填字段、参数类型 | Check your request body syntax and required parameters. |
| 401 | Unauthorized | API Key 无效或已过期。请在控制台 Token 管理中检查 | Verify your API Key is valid and active in the Token Management page. |
| 402 | Insufficient Quota | Token 配额不足，请在控制台充值 | Check your remaining quota and top up if needed. |
| 429 | Rate Limit Exceeded | 请求频率超限，请稍后重试或降低并发 | Implement exponential backoff, reduce request rate. |
| 500 | Internal Server Error | 服务器内部错误，我们会自动监控并修复 | Retry with exponential backoff. Contact support if persistent. |
| 503 | Service Unavailable | 服务暂时不可用，可能正在维护中 | Wait and retry. Check the status page for maintenance windows. |
7. 速率限制
限制策略
API 请求受速率限制保护。当前限制基于每个 API Key 的每分钟请求数 (RPM) 和每分钟 Token 数 (TPM)，具体额度取决于你的订阅方案。
速率限制响应头
每个 API 响应的 HTTP 头中包含以下速率限制信息：
| Header | 说明 |
|---|---|
| x-ratelimit-limit-requests | 每分钟最大请求数 |
| x-ratelimit-remaining-requests | 当前窗口剩余请求数 |
| x-ratelimit-limit-tokens | 每分钟最大 Token 数 |
| x-ratelimit-remaining-tokens | 当前窗口剩余 Token 数 |
429 处理建议
- 实现指数退避重试策略（初始等待 1s，每次加倍，最大 60s）
- 使用 jitter 避免惊群效应
- 监控 x-ratelimit-remaining-* 头，提前调整请求速率
8. 最佳实践
连接管理
• 使用 HTTP Keep-Alive 复用连接，减少 TLS 握手开销
• 设置合理的超时时间：连接超时 10s，读取超时 120s（长文本生成）
• 使用 HTTP/2 以支持多路复用
重试策略
• 仅对 429 和 5xx 错误重试，4xx 不应重试
• 使用指数退避 + 随机 jitter
• 设置最大重试次数（建议 3-5 次）
安全
• 永远不要在客户端代码中硬编码 API Key
• 使用环境变量或密钥管理服务存储 Key
• 定期轮换 API Key，每个应用使用独立 Key
成本优化
• 根据任务复杂度选择合适模型，简单任务用 mini/flash 模型
• 控制 max_tokens 上限，避免浪费
• 在 dashboard 中监控用量，设置预算告警