API 文档

统一大模型 API 网关 · 兼容 OpenAI / Claude / Gemini 协议的统一网关

概览

本站提供 OpenAI 兼容的 HTTP 接口。任何支持自定义 base_url 的 SDK 或客户端都可以直接接入，无需修改业务代码。

项目	值
Base URL	`http://test.z7z8.site/v1`
协议	HTTPS（生产环境）/ HTTP（本地调试）
数据格式	`application/json`
编码	UTF-8

鉴权

所有 /v1 请求都必须在请求头携带 API Key：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx

API Key 可在「控制台 → API 密钥」中创建。Key 只在创建时完整显示一次，请立即保存。若 Key 泄露，请立刻在控制台删除并重建。

快速开始

下面三种写法等价，选你手上已有的那个。所有示例都可以直接复制运行，只需要把 sk-xxxx 换成你自己的 Key。

curl http://test.z7z8.site/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}]}'

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxx",
    base_url="http://test.z7z8.site/v1",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-xxxxxxxx',
  baseURL: 'http://test.z7z8.site/v1',
});

const r = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: '你好' }],
});
console.log(r.choices[0].message.content);

SDK 会自动带上 Authorization 头，所以 Python / Node 示例里没有手写它。用 curl 时必须自己加，少这一行会直接 401。

POST /v1/chat/completions

创建一次对话补全。请求体与 OpenAI 官方保持一致。

字段	类型	说明
`model`	string	必填，模型 ID，可从 /v1/models 获取
`messages`	array	必填，消息列表，role 支持 system/user/assistant/tool
`stream`	bool	是否流式返回，默认 false
`temperature`	number	采样温度，0-2
`max_tokens`	int	最大生成 token 数
`tools`	array	可调用的函数定义
`tool_choice`	string/object	函数调用策略

响应

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-4o-mini",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "你好！有什么可以帮你？" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 }
}

流式输出

设置 "stream": true 后，服务以 SSE 返回。每行以 data: 开头，最后一个数据块固定为 data: [DONE]。

data: {"id":"chatcmpl-x","choices":[{"delta":{"role":"assistant"},"index":0}]}

data: {"id":"chatcmpl-x","choices":[{"delta":{"content":"你好"},"index":0}]}

data: {"id":"chatcmpl-x","choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

计费以最终 usage 为准。若上游不返回 usage，网关会按字符数估算，因此流式与一次性调用的账单可能有极小差异。

Function Calling

与 OpenAI 一致：在请求中传入 tools，模型若决定调用，响应里的 finish_reason 为 tool_calls，并在 message.tool_calls 中给出函数名与 JSON 参数。调用方执行函数后，把结果以 role 为 tool 的消息回传即可继续对话。

POST /v1/embeddings

把文本转为向量。请求体为 model 加 input，input 也可以是字符串数组以批量处理。

{
  "object": "list",
  "data": [{ "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456] }],
  "model": "text-embedding-3-small",
  "usage": { "prompt_tokens": 8, "total_tokens": 8 }
}

GET /v1/models

返回当前 API Key 可用的模型列表。

{
  "object": "list",
  "data": [
    { "id": "gpt-4o-mini", "object": "model", "created": 1730000000, "owned_by": "unai" }
  ]
}

错误码

错误统一返回 OpenAI 风格结构，便于 SDK 直接解析：

{
  "error": {
    "message": "用户名或密码错误",
    "type": "invalid_request_error",
    "code": "unauthorized"
  }
}

HTTP	含义	处理建议
200	成功	返回 JSON；`stream:true` 时为 SSE 分块
400	请求参数错误	检查请求体字段与类型
401	未授权 / Key 无效	确认 Authorization 头是否正确
403	无权限	该模型未授权给你的分组，联系管理员
404	模型或端点不存在	用 /v1/models 确认模型 ID
429	触发限流	降低并发或稍后重试
500	服务内部错误	稍后重试，持续失败请联系管理员
502	上游渠道异常	网关会自动重试与切换渠道

限流与重试

每个 API Key 有独立的每分钟请求上限（RPM）。超限返回 429 并附带 x-ratelimit-remaining 头。

网关在遇到上游 5xx、超时或连接失败时会自动重试并切换到其它可用渠道；对调用方而言通常表现为「稍慢但成功」，无需自行实现故障转移。某个渠道连续失败达到阈值后会被熔断一段时间，期间不再被选中。