OpenAI-compatible Docs
把现有 OpenAI 调用切到 Lucis。
Lucis API 兼容常见 OpenAI 调用方式。你只需要准备 API Key，并把客户端的 Base URL 替换为 Lucis API 地址。
快速开始
大多数 OpenAI-compatible 项目只需要改两处：API Key 和 Base URL。建议先用一个低成本模型发起测试请求，再接入正式业务。
- 在控制台创建 API Key。
- 把 Base URL 设置为
https://api.zilan520.shop/v1。 - 选择控制台可用模型，发起一次测试请求。
- 在使用记录中确认模型、用量和扣费正常。
Base URL
所有 OpenAI-compatible 请求统一使用下面的入口。路径仍按常见 OpenAI 接口拼接，例如 /chat/completions、/models。
Endpoint
https://api.zilan520.shop/v1
认证方式
请求头使用 Bearer Token。API Key 属于敏感凭证，请放在服务端环境变量里，不要写进公开前端代码或客户端安装包。
Headers
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json模型列表
可以通过模型列表接口检查当前 Key 可用的模型。实际可见模型取决于控制台配置、分组权限和余额状态。
GET /models
curl https://api.zilan520.shop/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"文本对话
对话请求使用 /chat/completions。把 YOUR_MODEL 替换成控制台可用模型，例如价格页展示的文本模型。
POST /chat/completions
curl https://api.zilan520.shop/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL",
"messages": [
{ "role": "user", "content": "你好，Lucis API" }
]
}'流式输出
需要边生成边返回时，设置 stream: true。服务端会以 SSE 形式连续返回增量内容，适合聊天框、控制台日志和长文本生成场景。
Streaming
curl https://api.zilan520.shop/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL",
"stream": true,
"messages": [
{ "role": "user", "content": "用三句话介绍 Lucis API" }
]
}'图片生成
图片生成使用 OpenAI-compatible 图片接口。图片按张计费，实际价格和可用分辨率以控制台、价格页和使用记录为准。
POST /images/generations
curl https://api.zilan520.shop/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "一张极简黑银色科技风 API 网关海报",
"size": "1024x1024",
"n": 1
}'JavaScript 示例
适合 Node.js 服务端或本地脚本。不要把服务端 API Key 暴露到公开前端代码中。
JavaScript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.LUCIS_API_KEY,
baseURL: "https://api.zilan520.shop/v1"
});
const response = await client.chat.completions.create({
model: "YOUR_MODEL",
messages: [
{ role: "user", content: "你好，Lucis API" }
]
});
console.log(response.choices[0]?.message?.content);Python 示例
适合自动化、后端服务和数据处理脚本。
Python
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["LUCIS_API_KEY"],
base_url="https://api.zilan520.shop/v1",
)
response = client.chat.completions.create(
model="YOUR_MODEL",
messages=[
{"role": "user", "content": "你好，Lucis API"}
],
)
print(response.choices[0].message.content)错误排查
接入失败时，优先检查下面几项。大部分问题都可以通过状态码、错误信息和控制台记录定位。
- 401：检查 API Key 是否正确、是否带上
Bearer。 - 403：检查账号权限、分组权限或服务策略限制。
- 404：检查路径是否拼错，Base URL 是否包含
/v1。 - 429：请求过快或并发过高，降低频率后重试。
- 5xx：稍后重试，并保留请求时间、模型和错误信息便于排查。
上线检查
把流量切到正式服务前，建议先完成这些检查，避免因为密钥、模型或扣费配置导致异常。
- API Key 已放在服务端环境变量中，没有暴露到浏览器。
- 模型名称来自控制台可用模型列表。
- 文本、流式输出和生图分别做过小流量测试。
- 使用记录能看到请求、模型、用量、图片数量和扣费结果。
- 业务侧已设置超时、重试和错误提示。