快速开始

Ling.AI 是面向业务系统的 AI API Gateway：对外提供 OpenAI 兼容 /v1/*，同时兼容 Anthropic 与 Gemini 原生协议；内部负责鉴权、模型路由、供应商适配、用量审计、账务结算和用户控制台展示。

前置要求

接入前先确认账号、Key、模型和余额四件事。接口路由存在不代表当前账号一定能调用所有模型，最终可用性以模型目录、API Key 权限和账户额度共同决定。

  • 注册账号： 访问 Ling.AI 注册页 完成注册，或前往 登录页 登录
  • 创建 API Key： 在用户控制台创建 Key，可按需配置 IP 白名单和模型权限
  • 确认模型： 先请求 GET /v1/models，或查看 模型目录，不要硬编码外部平台的静态型号
  • 确认额度： 钱包余额、套餐、免费额度和赠送额度会参与准入、预扣费、结算和回滚
  • 开发环境： Python 3.8+、Node.js 18+，或任意可发送 HTTPS JSON 请求的客户端

当前公开入口以 /v1 为主，并保留协议族原生路径

Auth 中间件接受 Authorization、x-api-key、x-goog-api-key 三种 Header 写法。通用入口走 /v1；Anthropic Messages 使用 /anthropic/v1/messages；Gemini 原生 generateContent 使用 /gemini/v1beta/models/{model}:generateContent，官方 REST ?key= 仅用于 Gemini 原生路径。

选择接入方式

新项目建议从 OpenAI 兼容 /v1 开始，因为它覆盖聊天、Responses、图片、视频、向量和音频转写。只有在现有客户端强依赖 Anthropic 或 Gemini 原生协议时，再切换到对应原生入口。

OpenAI SDK 推荐

最通用的接入方式，适合聊天、推理、多模态输入、工具调用和流式输出。模型 ID 请使用 /v1/models 返回的 id。

curl 
# 使用 OpenAI 兼容协议
curl https://api.vip.lingapi.ai/v1/chat/completions \
  -H "Authorization: Bearer <你的 API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5-plus",
    "messages": [{"role": "user", "content": "请介绍 Ling.AI 的接入方式"}]
  }'
Python 
from openai import OpenAI

client = OpenAI(
    base_url="https://api.vip.lingapi.ai/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)
TypeScript 
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.vip.lingapi.ai/v1',
  apiKey: '<你的 API_KEY>'
});

const response = await client.chat.completions.create({
  model: 'qwen3.5-plus',
  messages: [
    { role: 'system', content: '你是 Ling.AI 接入助手。' },
    { role: 'user', content: '请介绍当前系统开放了哪些接口。' }
  ]
});

console.log(response.choices[0].message.content);

Responses API 统一响应

与 Chat 共享鉴权、模型授权和账务链路。它更适合内置工具编排，例如联网搜索、网页抓取、代码解释器、文搜图、图搜图、知识检索和 MCP。

curl 
# 使用 Responses API
curl https://api.vip.lingapi.ai/v1/responses \
  -H "Authorization: Bearer <你的 API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5-plus",
    "input": [
      {
        "role": "user",
        "content": [{"type": "input_text", "text": "请总结 Ling.AI 的接入方式"}]
      }
    ]
  }'

Anthropic 协议兼容 Anthropic

如果客户端已经使用 Anthropic SDK 或 Messages API 请求体，可直接请求 POST /anthropic/v1/messages。API Key 与 /v1 通用，网关会完成协议转换、路由与结算。

curl 
# 使用 Anthropic 兼容协议
curl https://api.vip.lingapi.ai/anthropic/v1/messages \
  -H "x-api-key: <你的 API_KEY>" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "qwen3.5-plus",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'

Gemini 协议兼容 Gemini

如果客户端已经使用 Google GenAI generateContent 格式，可请求 POST /gemini/v1beta/models/{model}:generateContent。模型名位于 URL 路径中；鉴权支持 x-goog-api-key、Bearer 和官方 REST ?key= 写法。

curl 
# 使用 Gemini generateContent 兼容协议
curl https://api.vip.lingapi.ai/gemini/v1beta/models/qwen3.5-plus:generateContent \
  -H "x-goog-api-key: <你的 API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "你好"}]}
    ],
    "generationConfig": {"maxOutputTokens": 1024}
  }'

直接 HTTP 调用 兼容 Header

如果您的客户端不方便设置 Bearer Token，也可以继续请求 /v1 路由，并改用 x-api-key 或 x-goog-api-key 传递同一把 API Key；两个兼容 Header 二选一即可。

curl 
# 使用兼容 Header 访问同一套 /v1 接口；x-api-key 与 x-goog-api-key 二选一
curl https://api.vip.lingapi.ai/v1/chat/completions \
  -H "x-api-key: <你的 API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5-plus",
    "messages": [{"role": "user", "content": "请列出当前公开 API"}]
  }'

curl https://api.vip.lingapi.ai/v1/chat/completions \
  -H "x-goog-api-key: <你的 API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5-plus",
    "messages": [{"role": "user", "content": "请列出当前公开 API"}]
  }'

API 端点参考

接口 路径 认证方式 适合场景
Chat POST /v1/chat/completions Authorization / x-api-key / x-goog-api-key 最通用的聊天与工具调用入口
Responses POST /v1/responses Authorization / x-api-key / x-goog-api-key 统一输出结构、兼容 Responses 风格请求
Anthropic POST /anthropic/v1/messages x-api-key / Bearer Anthropic 协议格式兼容入口
Gemini POST /gemini/v1beta/models/{model}:generateContent x-goog-api-key / Bearer / ?key Google GenAI generateContent 协议格式兼容入口
Models GET /v1/models Authorization / x-api-key / x-goog-api-key 查询当前实例已启用模型
Image POST /v1/images/generations Authorization / x-api-key / x-goog-api-key 图像生成
Image Edit POST /v1/images/edits Authorization / x-api-key / x-goog-api-key 图像编辑
Video POST /v1/videos/generations Authorization / x-api-key / x-goog-api-key 视频生成
Embedding POST /v1/embeddings Authorization / x-api-key / x-goog-api-key 向量生成与检索场景
Audio POST /v1/audio/transcriptions Authorization / x-api-key / x-goog-api-key 音频转写
Task GET /v1/tasks/:taskId Authorization / x-api-key / x-goog-api-key 异步任务状态查询
Health GET /v1/health 通常无需鉴权 网关最小存活探测，不返回连接容量等内部细节
Cache GET /v1/cache/health Authorization / x-api-key / x-goog-api-key 缓存子系统健康检查（仅限已认证调用）

能力概览

通过网关可以统一访问以下能力；每一类能力都经过同一套鉴权、限流、计费、日志和用户中心展示链路。

聊天与推理

多轮对话、系统提示、函数调用、联网搜索、结构化输出和流式响应

图像与视频

图像生成、图像编辑、视频生成/编辑、异步任务提交和任务状态轮询

搜索与工具

Responses 工具编排、联网搜索、网页抓取、代码执行、知识检索和 MCP

向量与音频

文本向量、多模态向量、语音转写和 Qwen-Omni 音视频输入输出

下一步

完成基本接入后，您可以：

  • Keys 在控制台管理 API Key、状态、IP 白名单和模型授权
  • Models 通过 /v1/models 获取当前启用模型列表，并对照公开模型目录确认能力标签
  • Streaming 对聊天、Responses 和工具场景接入 SSE，必要时读取最后的 usage chunk
  • Usage 在控制台查看请求量、Token、缓存命中、费用、模型分布和 API Key 维度统计
  • Wallet 在钱包页核对余额、赠送额度、套餐消耗和账单明细
  • Advanced 了解供应商路由、故障回退、提示缓存和工具计费边界

安全提示

请勿将 API Key 硬编码在代码中，建议使用环境变量管理：

export LING_AI_API_KEY="sk-xxxxxxxx"

工具集成

以下工具已支持直接接入 Ling.AI：

工具 类型 集成方式
Claude Code AI 编程助手 配置 base_url 指向 /v1，使用 OpenAI 兼容协议
Zed Editor 代码编辑器 手动配置 /v1 与可用模型列表
Cline VS Code AI 助手 使用 OpenAI 兼容协议
Cherry Studio 跨平台客户端 配置 Ling.AI 作为后端
OpenCode 开源 AI 编程工具 使用 OpenAI 兼容协议
认证指南 →