API 开发文档

本平台提供与 OpenAI 完全兼容的 HTTP 接口。任何支持自定义 Base URL 的客户端、SDK 或框架,把地址指过来、换成这里的 API Key 即可直接使用,无需改动业务代码。

快速开始

三步就能跑通第一次调用:

步骤做法
1. 拿 Key注册并登录后,在「个人中心 → API Key」复制你的密钥(形如 sk-...)
2. 选模型到 模型列表 或主页模型广场,挑一个模型 ID
3. 发请求把 Base URL 设成 https://api.xn--o8z274c.top/v1,带上 Key 调用即可
Base URL 是 https://api.xn--o8z274c.top/v1, 注意结尾带 /v1。客户端里若要求填「完整端点」,则填 https://api.xn--o8z274c.top/v1/chat/completions。

鉴权方式

所有接口都通过 HTTP 头携带 API Key,使用标准的 Bearer 方案:

Authorization: Bearer sk-你的密钥

也兼容部分客户端发送的 x-api-key 头。密钥等同于账号凭证,请不要写进前端代码或提交到公开仓库。

密钥泄露风险自负:任何拿到你 Key 的人都能消耗你的余额。若怀疑泄露, 请立刻到个人中心使用「更换 API Key」,旧 Key 会立即失效。

模型列表 GET

查询当前账号可用的全部模型,用于客户端下拉选择。

curl https://api.xn--o8z274c.top/v1/models \ -H "Authorization: Bearer $API_KEY"

返回标准 OpenAI 列表结构:

{ "object": "list", "data": [ { "id": "deepseek-flash", "object": "model", "owned_by": "..." } ] }

Chat Completions POST

最常用的对话接口,路径 /v1/chat/completions,请求体与 OpenAI 一致。

请求参数

参数类型说明
modelstring必填。模型 ID,见模型列表
messagesarray必填。消息数组,每项含 role 与 content
streambool是否流式返回,默认 false
max_tokensint限制生成的最大 token 数
temperaturefloat采样温度,0~2

role 支持 system / user / assistant。 content 可以是字符串,也可以是数组形式以支持图文混合输入。

curl https://api.xn--o8z274c.top/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $API_KEY" \ -d '{ "model": "deepseek-flash", "messages": [ { "role": "system", "content": "你是一个有帮助的助手" }, { "role": "user", "content": "你好,介绍一下自己" } ], "stream": false }'

返回体(usage 里的 token 数与计费金额由本平台附加,标准客户端可忽略):

{ "id": "chatcmpl-...", "object": "chat.completion", "model": "deepseek-flash", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "你好!..." }, "finish_reason": "stop" }], "usage": { "prompt_tokens": 24, "completion_tokens": 56, "total_tokens": 80 } }

Responses API POST

路径 /v1/responses,是 OpenAI 较新的接口形态。用法同样是「改 Base URL 即可」。

curl https://api.xn--o8z274c.top/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $API_KEY" \ -d '{ "model": "deepseek-flash", "input": "你好" }'
本平台会把上游的 chat 型分片自动翻译成规范的 response.* 事件, 因此即使上游只支持 /chat/completions,严格客户端(官方 SDK、Operit、AstrBot 等) 也能正常收流并拿到终结事件。

流式输出

把 stream 设为 true,服务端以 SSE(text/event-stream)逐块返回。

Chat 流式

每个分片是 data: {...},最后以 data: [DONE] 结束:

data: {"choices":[{"delta":{"content":"你"},"finish_reason":null}]} data: {"choices":[{"delta":{"content":"好"},"finish_reason":null}]} data: {"choices":[{"delta":{},"finish_reason":"stop"}]} data: [DONE]

Responses 流式

事件带 event: 前缀,顺序为 response.created → response.output_text.delta(多次) → response.completed。严格客户端请按 sequence_number 递增校验。

客户端中途断开连接(用户点「停止」或关页面)时,服务端会按已实际生成的内容 计费,不会因为断开就免费。这是为了防止刷接口,属正常行为。

错误码

状态码type含义与处理
400invalid_request_error请求体格式错误,或缺 model / messages
401—API Key 无效或未携带,检查 Authorization 头
402insufficient_quota余额不足,请充值或购买套餐
403—账号被封禁,联系管理员
404invalid_request_error模型不存在或未上架,检查 model 字段
429rate_limit请求过于频繁,按 Retry-After 头退避重试

错误响应体与 OpenAI 保持一致,便于客户端统一处理:

{ "error": { "message": "Insufficient balance for this request", "type": "insufficient_quota" } }

多语言示例

Python
Node.js
cURL
# 直接用官方 OpenAI SDK,只改 base_url from openai import OpenAI client = OpenAI( api_key="sk-你的密钥", base_url="https://api.xn--o8z274c.top/v1", ) resp = client.chat.completions.create( model="deepseek-flash", messages=[{"role": "user", "content": "你好"}], ) print(resp.choices[0].message.content) # 流式 for chunk in client.chat.completions.create( model="deepseek-flash", messages=[{"role": "user", "content": "写一首短诗"}], stream=True, ): if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="")
import OpenAI from "openai"; const client = new OpenAI({ apiKey: "sk-你的密钥", baseURL: "https://api.xn--o8z274c.top/v1", }); const resp = await client.chat.completions.create({ model: "deepseek-flash", messages: [{ role: "user", content: "你好" }], }); console.log(resp.choices[0].message.content); // 流式 const stream = await client.chat.completions.create({ model: "deepseek-flash", messages: [{ role: "user", content: "写一首短诗" }], stream: true, }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content || ""); }
curl https://api.xn--o8z274c.top/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的密钥" \ -d '{ "model": "deepseek-flash", "messages": [{"role": "user", "content": "你好"}] }' # 流式:加 -N 关闭 curl 缓冲 curl -N https://api.xn--o8z274c.top/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的密钥" \ -d '{ "model": "deepseek-flash", "messages": [{"role": "user", "content": "写一首短诗"}], "stream": true }'

常见问题

客户端报「连接失败」或超时

先确认 Base URL 是否带了 /v1,以及服务器能否出网访问上游。 部分客户端把 Base URL 与完整路径混填,注意区分。

报 400 且提示 Missing model or messages

请求体的 JSON 结构不对。messages 必须是数组,model 必须与模型列表里的 ID 完全一致(区分大小写)。

怎么知道花了多少钱?

响应 usage 里会附带 cost(本次费用)、balance(剩余余额) 与缓存命中拆分。登录后到「用量明细」可查每一笔流水。

支持 Function Calling / 多模态吗?

请求体是原样透传给上游的,上游支持的能力都能用;本平台只做鉴权、计费与协议兼容, 不会裁剪你的参数。

还有问题?主站「我的工单」可以提交技术支持,或联系 2162771318@qq.com。