开发者中心 · 快速接入
把模型接入你的工具
选择你正在使用的客户端，文档会自动匹配协议、分组和模型，并生成可以直接复制的配置。
服务状态正在获取
服务分组--
可用模型--
协议分组目录暂不可用
START HERE
先选你要接入的客户端
选对客户端，后面的协议和分组就不会配错。
协议自动匹配配置可复制
当前配置
等待模型目录OpenAI 兼容客户端 OpenAI
/v1/chat/completions · 选择 OpenAI 分组
Base URL
https://lingzhanai.top/v1三步完成第一次调用
API Key 绑定的分组决定可用协议、模型范围与计费倍率。上面的配置卡已经为你匹配了推荐组合。
发送请求
把客户端 Base URL 改为灵栈地址。密钥放在环境变量中，不要写入源码或提交到仓库。
统一 Base URL
https://lingzhanai.top/v1调用示例
示例会优先使用当前目录中的 OpenAI 协议模型；实际调用前仍应通过模型列表确认。
curl https://lingzhanai.top/v1/chat/completions \
-H "Authorization: Bearer $LINGZHAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL_ID",
"messages": [{"role": "user", "content": "你好，请介绍一下你自己"}]
}'密钥安全 浏览器前端、公开仓库和聊天截图中都不应出现完整 API Key。生产环境请使用服务端环境变量或密钥管理服务。
协议与端点
同一个 Base URL 支持多类请求，但密钥分组必须与端点协议匹配。本站不会将 Anthropic 请求静默转换为 OpenAI 请求。
| 方法 | 端点 | 协议 | 适用场景 |
|---|---|---|---|
| POST | /v1/chat/completions | OpenAI | 聊天、工具调用及兼容 OpenAI SDK 的客户端 |
| POST | /v1/responses | OpenAI | Codex 等使用 Responses API 的客户端 |
| POST | /v1/messages | Anthropic | Claude Code 及兼容 Anthropic Messages 的客户端 |
| GET | /v1/models | 自动识别 | 按当前 API Key 的分组返回可调用模型 |
| POST | /v1/embeddings | OpenAI | 向量嵌入 |
| POST | /v1/images/generations | OpenAI | 图片生成 |
常见误区：Codex++ 等仅支持 OpenAI 端点的客户端，不能直接使用 Anthropic 分组。Claude Code 应使用 /v1/messages；协议选错会返回 protocol_mismatch。
获取可用模型
模型目录随分组和上游状态变化，请在运行时发现模型，不要长期硬编码目录。
GET
https://lingzhanai.top/v1/models请求需携带 Authorization: Bearer YOUR_API_KEY。返回结果会根据 API Key 绑定的服务分组过滤，只包含该密钥实际可调用的模型。
流式响应
聊天、Responses 和 Messages 端点均可按对应协议启用流式输出。
开启流式
在请求体中设置 "stream": true。客户端应持续消费 SSE 数据，直到协议规定的结束事件。
正确取消
用户终止生成时请主动取消 HTTP 请求，避免上游继续生成并产生费用。不要只停止界面渲染。
保存请求 ID
记录响应头或错误体中的请求 ID。需要排查计费、超时或上游错误时，它是最有效的定位依据。
错误码与处理
先根据 HTTP 状态与错误 code 判断问题归属，再决定重试、换模型或调整配置。
| 状态 | 错误 code | 含义 | 建议处理 |
|---|---|---|---|
| 401 | invalid_api_key | API Key 无效、已停用或已过期 | 检查密钥并在 API 密钥页确认状态 |
| 402 | insufficient_quota | 余额或密钥额度不足 | 充值或调整密钥额度 |
| 400 | protocol_mismatch | 所选分组与请求协议不匹配 | 对照上方端点，并检查密钥绑定分组 |
| 404 | model_not_in_group | 模型不属于当前密钥分组 | 通过 /v1/models 获取允许的模型 ID |
| 429 | account_rate_limit | 达到密钥用量或并发限制 | 稍后重试，或调整密钥限制 |
| 502/504 | upstream_* | 上游暂时异常或超时 | 稍后采用指数退避重试 |
生产环境最佳实践
把调用稳定性、安全和成本控制放进客户端的默认行为。
- 只重试临时错误：对 429、502、503、504 使用带抖动的指数退避；认证、余额与协议错误不应盲目重试。
- 设置合理超时：连接超时与完整响应超时分开配置，流式请求允许更长的读取时间。
- 按应用创建独立密钥：分别设置分组、额度和有效期，泄露时可以单独停用并创建替代密钥，不影响其他业务。
- 控制重试范围：大批量任务对临时错误使用退避，避免把短暂异常放大成重试风暴。