API 文档

本站提供 OpenAI 兼容的 HTTP 接口。下面带你从零跑通第一次调用，并列出全部可用端点与常见错误。

基地址：https://api.leafovo.net/v1 · 所有请求都以此为前缀，路径与 OpenAI 官方一致。

快速开始

三步即可完成接入：

前往控制台 → 令牌创建一个 API 密钥（形如 sk-...）。
在你的代码里，把 base_url 改成本站地址，api_key 换成刚创建的密钥。
照常调用原来的方法，无需改动其他业务逻辑。

example.py

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-token",
    base_url="https://api.leafovo.net/v1",
)

resp = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

example.mjs

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-your-token",
  baseURL: "https://api.leafovo.net/v1",
});

const resp = await client.chat.completions.create({
  model: "gpt-5.6-terra",
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);

shell

curl https://api.leafovo.net/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "你好"}]
  }'

鉴权方式

所有需要授权的接口都通过 HTTP 头传递密钥，与 OpenAI 一致：

请求头

Authorization: Bearer sk-your-token

密钥在控制台 → 令牌创建与管理。
每个令牌可单独限定可用模型、额度上限、过期时间与 IP 白名单。
请勿把密钥写进前端代码或公开仓库 —— 浏览器端请求会暴露密钥。需要前端直连时，建议由自己的后端中转。
若怀疑密钥泄露，立即在控制台删除该令牌并新建一个。

接口清单

路径与 OpenAI 官方保持一致，因此各语言官方 SDK 均可直接使用。

方法	路径	说明
POST	`/v1/chat/completions`	对话补全，支持流式（`stream: true`）、函数调用、图片输入
POST	`/v1/completions`	文本补全（旧版接口，部分模型支持）
POST	`/v1/embeddings`	文本向量化
POST	`/v1/images/generations`	文生图
POST	`/v1/audio/speech`	文本转语音
POST	`/v1/audio/transcriptions`	语音转文本
GET	`/v1/models`	列出当前账户可用的模型

关于可用性：上表是网关支持的端点类型，具体某个模型是否支持某一端点，取决于该模型自身的上游能力。调用前可先查 /v1/models，或在模型列表里查看各模型的分组。

请求与响应示例

POST /v1/chat/completions

{
  "model": "gpt-5.6-terra",
  "messages": [
    {"role": "system", "content": "你是一个简洁的助手。"},
    {"role": "user",   "content": "用一句话解释什么是 API 网关。"}
  ],
  "temperature": 0.7,
  "stream": false
}

响应 200

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1789427887,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "API 网关是位于客户端与后端服务之间的统一入口，负责转发请求并附加鉴权、限流与计费。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 48,
    "total_tokens": 80
  }
}

流式输出

把 stream 设为 true，服务端会以 SSE 逐块返回，适合打字机效果：

stream.py

stream = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "写一首关于代码的五言诗"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

错误码

接口沿用 OpenAI 的错误结构，返回体形如：

错误响应

{
  "error": {
    "message": "Invalid token",
    "type": "new_api_error",
    "code": ""
  }
}

状态码	含义	常见原因与处理
`400`	请求格式错误	参数缺失或类型不对，检查请求体字段
`401`	未授权 / 密钥无效	密钥写错、被删除，或未带 `Authorization` 头
`403`	无权限	该令牌未被允许使用此模型，或 IP 不在白名单内
`404`	路径或模型不存在	检查路径拼写；确认模型名在模型列表中
`429`	请求过于频繁	触发限流，降低并发或稍后重试
`500`	上游异常	目标模型暂时不可用，可重试或换用其他模型

建议：对 429 与 5xx 做指数退避重试（如 1s / 2s / 4s），对 4xx 中的参数类错误直接修正，不要盲目重试。

常见问题

调用报 `Invalid token` 怎么办？

依次检查：密钥是否复制完整（注意别漏掉 sk- 前缀）、是否已带上 Authorization: Bearer <key> 请求头、控制台里该令牌是否被停用或额度已耗尽。

模型名应该填什么？

填模型列表里显示的模型名（model_name 字段），区分大小写。填了一个站内没有的模型会返回 404。

可以直接在前端调用吗？

不建议。前端代码里的密钥对所有访客可见。正确做法是由你自己的后端持有密钥，前端请求你的后端，再由后端转发到本站。

支持哪些编程语言？

只要该语言有 OpenAI 官方或社区 SDK，把 base_url 指向本站即可。 Python、Node.js、Go、Java、PHP、C# 等均有可用 SDK。