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 回复

聊天补全

POST /v1/chat/completions

请求参数

参数名 类型 说明
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 越多,建议按需裁剪历史。

模型列表

查看所有可用的模型

zdzl-chat 通用

通用对话模型(思考关闭),适用于日常对话、问答、写作、翻译等场景。响应快速,效果出色。

zdzl-reasoner 推理

深度思考模型(思考开启),响应中包含 reasoning_content 思维链,适用于复杂问题分析、 数学推理、代码生成等场景,详见「深度思考」。

获取模型列表

GET /v1/models
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 开发之旅

前往控制台 在线测试