LingGuo AI GATEWAY · DEVELOPER GUIDE

从创建密钥到第一次调用

连接你的 AI，
几分钟开始使用。

创建 API Key，选择客户端，把模型接入你熟悉的工具。基础文档无需登录；密钥、余额与个人用量在控制台管理。

API Base URL

命令行系统

日常聊天Cherry Studio ↗编程开发Codex / TRAE ↗图片创作模型输入能力 ↗AI AgentOpenClaw / Hermes ↗

01 充值添加账户余额→02 创建 Key创建时显示一次→03 选模型并测试复制示例调用

前往 API Key 页面余额 / 充值浏览模型与价格 →

02 / 环境准备

先准备三项信息

所有请求经过 LingGuo AI 网关；示例只使用你自己的 Key，占位符不会包含真实凭据。

API Base URL

API KeyYOUR_API_KEY创建密钥 →

模型 ID查看模型 →

Key 创建后只显示一次。请存放在本机密钥管理器或环境变量中，不要贴到聊天、工单、截图或 URL 里。

配置助手

生成我的配置

客户端

OpenAI Compatible 设置

前往控制台创建 API Key →

终端环境变量 zsh

03 / 客户端

Cherry Studio

选择 OpenAI Compatible 服务商接入文本 Chat Completions。客户端可选能力还取决于 Cherry Studio 版本和模型。

安装并打开 Cherry Studio，进入「设置 → 模型服务」。
添加 OpenAI Compatible 服务商，名称填写 LingGuo AI。
API 地址填写下方地址，API Key 粘贴自己的密钥，再选择模型 ID。

服务商名称LingGuo AI

API 地址

模型 IDYOUR_MODEL_ID

打开 API Key 页面查看模型

当前 Chat Completions 仅实现文本输入输出；工具调用及图片生成未开放。请选择纯文本模型。

04 / 客户端

Codex CLI

需要 Responses 流式与工具调用支持

项目有非流式 /v1/responses，但当前对 stream: true 返回 501，Codex 工具调用生命周期也未完整兼容。因此暂不能承诺 Codex CLI 可直接完成编程工作流。

后端补齐并验证这些能力后可参考下方模板；当前模板不代表已验证可用。

~/.codex/config.toml TOML

设置环境变量并启动

使用 Playground 验证文本调用 →

05 / 客户端

Claude Code

暂未开放 Claude 原生协议

当前服务没有 Anthropic Messages 的 /v1/messages 路由，不能使用 ANTHROPIC_BASE_URL 直连。允许配置 OpenAI Compatible Provider 的客户端可使用 LingGuo AI 文本 Chat Completions；这不等于 Claude Code 原生协议支持。

查看已开放的文本 API 示例 →

06 / 客户端

Gemini CLI

Gemini 原生协议暂未开放

当前服务没有 Gemini 原生 API 路由。不要将 GOOGLE_GEMINI_BASE_URL 指向 LingGuo AI。支持 OpenAI Compatible 的客户端可按其文档配置文本 Chat Completions。

07 / 客户端

TRAE / TRAE SOLO

如当前 TRAE 版本提供自定义 Provider，可尝试配置 OpenAI Compatible Base URL、用户 API Key 与模型 ID。后端具备文本 Chat Completions；Responses 仅非流式，Anthropic 原生协议不可用。

自定义 Provider 取决于当前 TRAE 版本；TRAE SOLO 不保证支持所有连接方式。

OpenAI Compatible文本 Chat Completions 可用；工具调用未开放

Responses非流式可用；流式暂未开放

Anthropic原生 Messages 协议暂未开放

协议OpenAI Compatible · 文本

Base URL

模型 IDYOUR_MODEL_ID

08 / Agent

OpenClaw

Provider 配置项会随 OpenClaw 版本变化。按当前安装指引设置 OpenAI Compatible 文本模型；LingGuo AI 当前没有 Agent 工具调用、图片生成或视频生成接口。

安装与启动

npm install -g openclaw@latest
openclaw onboard
# 在向导中选自定义 OpenAI Compatible Provider
# 填写当前 API Base URL、YOUR_API_KEY 与模型 ID
openclaw gateway install
openclaw dashboard

聊天模型与图片 / 视频 / MCP 工具是独立配置。本指南只覆盖文本模型，不表示工具、图片或视频已接通。

09 / Agent

Hermes Agent

在 Hermes 模型设置中选择 Custom Endpoint，填入当前 Base URL、用户 API Key 和公开模型 ID。菜单名称可能随版本变化，请以本机帮助为准。

启动与工具列表

hermes model
# 选择 Custom Endpoint，填写 LingGuo AI Base URL
# API Key: YOUR_API_KEY · Model ID: YOUR_MODEL_ID
hermes
hermes tools

Chat Completions 未实现工具调用。hermes tools 可查看本机工具，但不代表这些工具可由 LingGuo AI 模型调用。

10 / 多模态

图片生成与编辑

图片生成与编辑 API 暂未开放

当前代码没有 /v1/images/generations 或 /v1/images/edits 路由。部分 Responses 模型注册图片输入能力，但这是图片理解输入，不是图片生成或编辑。请在模型目录查看能力。

查看模型能力 →

11 / 视频

视频生成

视频 API 暂未开放

当前有通用 Generation Task 的创建、查询和取消契约，但没有视频 Provider 执行、结果下载或视频内容接口，因此不提供会声称返回成片的 curl。失败时请勿重复创建任务。

12 / 工具与媒体

Agent / MCP / Skill / 媒体工具

Chat Completions 当前只提取文本消息并返回文本结果，没有转发 function/tool calls。MCP Server 和本机 Skill 属于客户端侧设置，与聊天模型路由分开管理。

OpenAI Compatible 文本可用：非流式与文本流式 Chat Completions

Responses有限可用：非流式；流式返回 501

Anthropic / Gemini 原生协议未开放

图片 / 视频生成与工具调用未开放

13 / 排查

常见问题

从哪里创建 API Key？

登录后打开 API Key 页面。创建前账户需有余额；Key 只显示一次，请立即保存。

模型 ID 填什么？

从模型目录选择 ID。页面下拉框读取真实 /v1/models 数据。

为什么请求报 401 或 403？

401 常见于 Key 无效、已禁用或 Bearer 格式错误；403 常与账户 API 权限、模型或分组授权有关。不要发送完整 Key。

Responses 能否用于 Codex？

当前 Responses 不支持流式，工具调用生命周期也未验证。Codex 状态标记为需要后端支持。

图片理解等于图片生成吗？

不是。模型图片输入能力用于理解图片，不代表存在图片生成或编辑 API。

14 / 技术测试

API 技术测试中心

连通性测试只读取公开模型目录，不会发起付费推理。Chat Completions 与 Responses 示例会消耗余额，运行前请确认模型和费用。查看 OpenAPI 接口参考 →

当前网关

尚未测试

Chat Completions · 文本

curl · zsh

Responses · 非流式

Responses streaming 当前返回 501

curl · 当前系统

HTTP 状态排查

状态	常见原因	检查方法
400 / 422	参数、模型或素材格式错误	核对 JSON 与模型能力
401	API Key 无效或格式错误	检查 Bearer Key；不要提交完整 Key
403	账户、模型或分组权限	检查账户状态和模型访问
404	Base URL 或路由错误	确认使用当前 /v1 地址
408 / 504	请求或上游超时	记录发生时间、模型 ID、请求 ID
429	余额、频率或并发限制	查看余额和使用额度
500 / 502 / 503	内部错误或上游暂不可用	保留脱敏错误及请求 ID 联系支持

排查时提供请求 ID、发生时间、模型 ID 与脱敏错误。客服不需要完整 API Key，也不要上传含密钥配置文件。

15 / 费用

费用与使用说明

API 调用从账户预付余额扣费。调用前查看模型价格，调用后在用量和日志页面查看记录。

按 Token 用量计费

公开文本模型按 Token 用量计费：输入、输出、缓存命中的输入分别按 /v1/models 中 pricing 字段公示的每 100 万 Token 单价计算（input_per_1m_usd / output_per_1m_usd / cached_input_per_1m_usd），以积分计，1 积分 = $1。
每次成功调用按实际用量向上取整到 $0.01，最低 $0.01。pricing.mode 为 per_call 的模型仍按 fixed_price_cents 单次计费。
请求前会按“输入内容的字节数上限 + 输出上限”冻结预估金额，完成后按实际用量结算并释放剩余部分；余额（含可用的赠送额度）不足以覆盖预估金额时返回 HTTP 402。
未设置 max_tokens / max_output_tokens 时，默认输出上限为 8,192 Token（不超过模型上限），达到上限时返回 finish_reason: "length" 并按已生成 Token 计费。设置更小的上限可以降低冻结金额。
单次输入超过 272,000 Token 时，按上游长上下文规则：输入单价 ×2、输出单价 ×1.5。
上游失败、请求被拒绝，或流式输出在上游完成前中断的，不扣费，冻结金额全额释放。
新人赠送额度仅可用于指定模型，单次输出上限 1,024 Token。价格调整至少提前 7 日公布，详见《价格与积分说明》。

账户余额与充值打开 Billing →模型价格与能力浏览模型 →用量记录查看消耗 →

模型目录展示当前公开模型字段；价格以模型目录与账户账单为准。注册能力不保证上游运行时一定可用。

连接你的 AI，几分钟开始使用。