API 文档
轻松集成 ZDZL AI 大模型能力,支持 OpenAI 兼容格式
基本信息
| API 地址 | https://ai.zdzltop.com |
| Base URL | https://ai.zdzltop.com/v1 |
| 协议 | HTTPS |
| 数据格式 | JSON |
认证
所有 API 请求都需要在 Header 中包含 API Key 进行认证
认证方式
Authorization: Bearer YOUR_API_KEY
将 YOUR_API_KEY 替换为你在控制台获取的 API Key。
Python 示例
# 使用 openai 库 from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://ai.zdzltop.com/v1" ) response = client.chat.completions.create( model="zdzl-chat", messages=[{"role": "user", "content": "你好"}] ) print(response.choices[0].message.content)
Node.js 示例
// 使用 openai 官方 SDK(Node.js) import OpenAI from "openai"; const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://ai.zdzltop.com/v1" }); const response = await client.chat.completions.create({ model: "zdzl-chat", messages: [{ role: "user", content: "你好" }] }); console.log(response.choices[0].message.content);
对话接口
发送对话请求,获取 AI 回复
聊天补全
请求参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| model 必填 | string | 模型名称。zdzl-chat:通用对话(思考关闭);zdzl-reasoner:深度思考(思考开启) |
| messages 必填 | array | 对话消息数组,按时间顺序排列。每条消息包含 role(system / user / assistant)和 content |
| stream | boolean | 是否流式返回,默认 false。流式说明见下文 |
| max_tokens | integer | 最大生成 token 数,默认 2048 |
| temperature | float | 采样温度,取值 0-2,默认 1.0。思考模式下该参数不生效 |
| top_p | float | 核采样,取值 0-1,默认 1.0。思考模式下该参数不生效 |
请求示例
{
"model": "zdzl-chat",
"messages": [
{"role": "system", "content": "你是一个有帮助的AI助手"},
{"role": "user", "content": "你好,请介绍一下自己"}
],
"stream": false,
"max_tokens": 1000,
"temperature": 0.7
}
响应示例
{
"id": "chatcmpl-xxx",
"object": "chat.completion",
"created": 1700000000,
"model": "zdzl-chat",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "你好!我是 ZDZL AI,一个由 ZDZL 驱动的智能助手..."
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 20,
"completion_tokens": 50,
"total_tokens": 70
}
}
响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 本次请求唯一 ID,chatcmpl- 前缀 |
| object | string | chat.completion(非流式)/ chat.completion.chunk(流式) |
| created | integer | Unix 时间戳 |
| choices[].message.content | string | 回复正文 |
| choices[].message.reasoning_content | string | 思考过程,仅 model 为 zdzl-reasoner 时返回,详见「深度思考」 |
| choices[].finish_reason | string | stop 表示正常结束 |
| usage | object | token 用量统计(prompt / completion / total) |
流式输出
设置 stream: true 启用流式输出,服务器会逐块返回数据。
# 流式响应示例 curl https://ai.zdzltop.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "zdzl-chat", "messages": [{"role": "user", "content": "讲个笑话"}], "stream": true }' # 响应格式 (SSE) data: {"choices": [{"delta": {"content": "好的"}}]} data: {"choices": [{"delta": {"content": ","}}]} ... data: [DONE] # 深度思考模型 (zdzl-reasoner) 会先输出 reasoning_content 增量,再输出 content data: {"choices": [{"delta": {"reasoning_content": "首先分析问题..."}}]} data: {"choices": [{"delta": {"reasoning_content": "然后..."}}]} ... data: {"choices": [{"delta": {"content": "答案是..."}}]} ... data: [DONE]
深度思考
使用 zdzl-reasoner 获取思维链(reasoning_content)
两个模型的区别
| 模型 | 思考模式 | 适用场景 |
|---|---|---|
| zdzl-chat | 关闭 | 日常对话、问答、写作、翻译等,响应更快 |
| zdzl-reasoner | 开启(思考强度固定为 high) | 复杂问题分析、数学推理、代码生成等需要逐步推理的场景 |
思考强度当前固定为 high,暂不支持客户端调整;思考模式下 temperature / top_p 参数不生效。
获取思考过程
请求时将 model 设为 zdzl-reasoner,响应中即包含
reasoning_content 字段(思维链文本)。流式模式下先收到
reasoning_content 增量,再收到 content 增量。
# Python:读取思考过程与回答 message = response.choices[0].message print(message.reasoning_content) # 思考过程 print(message.content) # 最终回答
注:思考过程会消耗生成时间与 token,请按需选用;普通问答建议使用 zdzl-chat。
多轮对话中的思维链
在后续请求的 messages 历史中无需回传 reasoning_content, 只需保留 role 与 content;即使传了也会被网关自动忽略。
多轮对话
把历史消息按顺序放入 messages 数组即可延续上下文
请求示例
{
"model": "zdzl-chat",
"messages": [
{"role": "system", "content": "你是一个有帮助的AI助手"},
{"role": "user", "content": "帮我起一个科技感的产品名"},
{"role": "assistant", "content": "推荐:云枢(CloudPivot)。"},
{"role": "user", "content": "再解释一下这个名字的含义"}
]
}
assistant 消息填入上一轮模型的原始回复即可;上下文越长消耗的 token 越多,建议按需裁剪历史。
模型列表
查看所有可用的模型
通用对话模型(思考关闭),适用于日常对话、问答、写作、翻译等场景。响应快速,效果出色。
深度思考模型(思考开启),响应中包含 reasoning_content 思维链,适用于复杂问题分析、 数学推理、代码生成等场景,详见「深度思考」。
获取模型列表
curl https://ai.zdzltop.com/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"
错误码
API 返回的错误代码及含义
| HTTP 状态码 | error.code | 说明与解决方式 |
|---|---|---|
| 400 | invalid_model | 模型名不合法,检查 model 取值 |
| 400 | messages_required | messages 缺失或为空,检查请求体 |
| 401 | api_key_missing | 缺少 Authorization 请求头 |
| 401 | invalid_api_key | API Key 无效或已被删除,到控制台重新生成 |
| 429 | quota_exceeded | 当日额度已用完,次日自动恢复或升级套餐 |
| 500 | request_failed / invalid_response | 上游服务异常,请稍后重试 |
| 503 | — | 功能维护中,恢复时间见公告 |
错误响应格式
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}
额度与限流
免费额度的计算规则与建议
| 免费额度 | 每天 10 次 API 调用(免费套餐额度),每日 0 点重置 |
| 计数方式 | 每次对话请求计 1 次(含流式),与返回内容长短无关 |
| 超出额度 | 返回 429 quota_exceeded,次日自动恢复;需要更多额度可升级套餐 |
| 查看用量 | 控制台可查看今日剩余额度与最近 7 天使用趋势 |
建议:捕获 429 错误后做退避重试;批量任务请在请求间增加间隔,避免瞬间打满额度。
开始使用
前往控制台获取 API Key,开始你的 AI 开发之旅