API 开发文档

快速开始

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

鉴权方式

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

复制Authorization: Bearer sk-你的密钥

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

模型列表 GET

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

复制curl http://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 一致。

请求参数

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

复制curl http://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 http://api.xn--o8z274c.top/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "deepseek-flash",
    "input": "你好"
  }'

流式输出

把 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 递增校验。

错误码

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

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

多语言示例

复制# 直接用官方 OpenAI SDK，只改 base_url
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的密钥",
    base_url="http://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: "http://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 http://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 http://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 / 多模态吗？

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