Developer documentation

接入知元api

接口兼容 OpenAI Chat Completions 格式。以下示例使用占位密钥，请先在控制台创建令牌。

概览

Base URLhttps://zhiyuanapi.top/v1

Chat endpointPOST /chat/completions

当前模型deepseek-chat

Content-Typeapplication/json

模型列表和权限以控制台实时显示为准。

身份验证

在请求头中以 Bearer Token 方式传入令牌：

HTTP Header

Authorization: Bearer YOUR_ZHIYUAN_API_KEY

切勿在浏览器前端、公开仓库或移动应用安装包中直接保存长期密钥。生产环境应由服务端安全注入。

对话接口

请求体

JSON

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "system", "content": "你是一个简洁的助手。"},
    {"role": "user", "content": "用一句话解释 API 网关。"}
  ],
  "stream": false
}

常用字段包括 model、messages、stream。其他参数是否可用取决于所选模型。

代码示例

cURL

Shell

curl https://zhiyuanapi.top/v1/chat/completions \
  -H "Authorization: Bearer $ZHIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}]}'

JavaScript

Node.js

const response = await fetch(
  "https://zhiyuanapi.top/v1/chat/completions",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.ZHIYUAN_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "deepseek-chat",
      messages: [{ role: "user", content: "你好" }]
    })
  }
);

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

Python

import os
import requests

response = requests.post(
    "https://zhiyuanapi.top/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['ZHIYUAN_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-chat",
        "messages": [{"role": "user", "content": "你好"}],
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

常见错误

401

认证失败

检查请求头、令牌是否有效，以及是否多复制了空格。

402 / 403

额度或权限不足

检查账户额度、令牌额度和模型权限。

429

请求过快

降低并发，并使用指数退避后重试。

5xx

服务暂时异常

记录请求时间与错误信息，稍后重试；不要无限循环重试。

安全建议

为开发、测试、生产环境分别创建令牌。
从小额度开始，并为异常消耗设置人工检查。
密钥疑似泄露时立即撤销，不要等待事故发生。
日志中只记录密钥末尾少量字符，禁止记录完整令牌。