获取 API Key
在开始使用 Ling.AI API 之前，您需要先获取 API Key：
- 访问 注册页 创建账号，或前往 登录页 登录
- 进入控制台的 API Keys 页面
- 点击 创建新的 API Key
- 复制并安全保存您的 API Key（明文仅在创建时返回一次）
- 如有需要，可为该 Key 配置 IP 白名单
⚠️ 安全提示
API Key 具有完整账户权限，请勿分享给他人或提交到代码仓库。建议使用环境变量管理：
export XIAOW_API_KEY="sk-xxxxxxxx"
鉴权方式
当前公开 API 统一走 /v1 路由。`AuthMiddleware` 同时接受三种 Header 名称，方便不同客户端或代理复用同一把 Key。
Authorization: Bearer 推荐
这是最推荐的方式，适用于 OpenAI SDK、绝大多数 HTTP 客户端与大部分第三方工具。
HTTP
Authorization: Bearer sk-xxxxxxxx
curl
# 推荐：Authorization Bearer curl https://api.lingyuncx.com/v1/chat/completions \ -H "Authorization: Bearer <你的 API_KEY>" \ -H "Content-Type: application/json" \ -d '{\n "model": "qwen3.5-plus",\n "messages": [{"role": "user", "content": "请返回当前公开 API 列表"}]\n }'
Python
from openai import OpenAI client = OpenAI( base_url="https://api.lingyuncx.com/v1", api_key="<你的 API_KEY>" ) response = client.chat.completions.create( model="qwen3.5-plus", messages=[ {"role": "system", "content": "你是 Ling.AI 接入助手。"}, {"role": "user", "content": "请介绍当前系统开放了哪些接口。"} ] ) print(response.choices[0].message.content)
x-api-key Header 兼容写法
如果客户端更容易设置自定义 Header，而不方便设置 Bearer Token，可以把同一把 API Key 放到 x-api-key 中；访问路径仍然是 /v1。
HTTP
x-api-key: sk-xxxxxxxx
curl
# 兼容写法：x-api-key curl https://api.lingyuncx.com/v1/chat/completions \ -H "x-api-key: <你的 API_KEY>" \ -H "Content-Type: application/json" \ -d '{\n "model": "qwen3.5-plus",\n "messages": [{"role": "user", "content": "请检查 x-api-key 是否可用"}]\n }'
Python
import requests response = requests.get( "https://api.lingyuncx.com/v1/models", headers={"x-api-key": "<你的 API_KEY>"} ) print(response.json())
x-goog-api-key Header 兼容写法
这是另一种兼容 Header 名称，适合需要沿用既有 Header 约定的工具或代理；访问路径同样保持在 /v1。
HTTP
x-goog-api-key: sk-xxxxxxxx
curl
# 兼容写法：x-goog-api-key curl https://api.lingyuncx.com/v1/models \ -H "x-goog-api-key: <你的 API_KEY>" \ -H "Content-Type: application/json"
Node.js
const response = await fetch('https://api.lingyuncx.com/v1/models', { headers: { 'x-goog-api-key': '<你的 API_KEY>' } }); console.log(await response.json());
协议对比
| Header 写法 | 访问路径 | 认证方式 | 适用场景 |
|---|---|---|---|
| Authorization | /v1/* |
Authorization: Bearer <KEY> |
标准 SDK、最推荐 |
| x-api-key | /v1/* |
x-api-key: <KEY> |
代理或固定 Header 客户端 |
| x-goog-api-key | /v1/* |
x-goog-api-key: <KEY> |
保留既有 Header 习惯的客户端 |
认证错误处理
认证或访问受限时，API 会返回统一错误结构：
JSON
{
"error": {
"message": "Invalid API key",
"type": "api_error",
"code": "invalid_api_key"
}
}
常见错误原因
- API Key 格式错误：确保使用正确的格式（
sk-开头） - API Key 已禁用：在控制台检查 API Key 状态
- IP 不在白名单：已配置白名单时，请确认当前出口 IP 被允许
- 触发频率限制：用户、Key 或 IP 达到限流阈值时会返回
rate_limit_exceeded相关错误 - 模型未启用：请先通过
/v1/models确认可用模型 ID
💡 提示
推荐优先使用 Authorization: Bearer；另外两种 Header 写法更适合做兼容接入，而不是区分不同公开协议。