API 文档

快速开始

注册 AI-KEY 账号，在控制台创建 API Key，即可使用任何 OpenAI / Claude 兼容客户端发起请求。推荐使用 API 专用域名 api.ai-key.top，主站域名 ai-key.top 仅作为兼容入口。

不知道怎么填？ 直接用 ⚡ 接入向导 —— 选客户端、填 Key，自动生成正确配置并能在线自检。
最容易踩的坑：Base URL 要不要带 /v1。 OpenAI 兼容客户端填 https://api.ai-key.top/v1（带 /v1）； Claude / Gemini SDK 填 https://api.ai-key.top（不带 /v1，SDK 自动补）。切勿重复成 .../v1/v1/...。

POST /v1/chat/completions

    
    curl "https://api.ai-key.top/v1/chat/completions"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "YOUR_MODEL",
    "messages": [{"role":"user","content":"你好!"}],
    "stream": false
  }'
  

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_KEY",
    base_url="https://api.ai-key.top/v1",
)
r = client.chat.completions.create(
    model="YOUR_MODEL",
    messages=[{"role":"user","content":"你好!"}],
)
print(r.choices[0].message.content)

JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.AI_KEY,
    baseURL: "https://api.ai-key.top/v1",
});
const r = await client.chat.completions.create({
    model: "YOUR_MODEL",
    messages: [{role:"user",content:"你好!"}],
});

Claude SDK (Python)

from anthropic import Anthropic

client = Anthropic(
    api_key="YOUR_KEY",
    base_url="https://api.ai-key.top",
)
msg = client.messages.create(
    model="YOUR_CLAUDE_MODEL",
    max_tokens=1024,
    messages=[{"role":"user","content":"你好!"}],
)
print(msg.content[0].text)

Google GenAI SDK

from google import genai
from google.genai.types import HttpOptions

client = genai.Client(
    api_key="YOUR_KEY",
    http_options=HttpOptions(
        base_url="https://api.ai-key.top",
    ),
)
r = client.models.generate_content(
    model="YOUR_MODEL",
    contents="你好!",
)

认证

所有 API 请求通过 HTTP Header 认证。支持以下两种格式：

Header	值	适用场景
`Authorization`	`Bearer sk-xxxxxxxx`	OpenAI SDK 兼容
`x-api-key`	`sk-xxxxxxxx`	Claude SDK 兼容 (配合 `anthropic-version`)
`x-goog-api-key`	`sk-xxxxxxxx`	Gemini SDK 兼容

API Key 在控制台 → 令牌页面创建。 请勿在代码中硬编码 Key，使用环境变量。

Base URL

主入口

https://api.ai-key.top/v1

所有 OpenAI-compatible SDK 使用此地址

Claude SDK

https://api.ai-key.top

Anthropic SDK 使用此地址（不带 /v1）

Gemini SDK

https://api.ai-key.top

Google GenAI SDK 使用此地址

兼容别名

https://ai-key.top/v1

主站兼容入口；推荐优先使用 api.ai-key.top

模型列表

GET /v1/models

获取当前可用模型列表。根据请求头自动切换 OpenAI / Claude / Gemini 返回格式。

    
    curl "https://api.ai-key.top/v1/models"   -H "Authorization: Bearer YOUR_API_KEY"
  

GET /v1/models/{model}

获取指定模型详情。

Chat Completions

OpenAI Compatible

POST /v1/chat/completions

    
    curl "https://api.ai-key.top/v1/chat/completions"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "YOUR_MODEL",
    "messages": [
      {"role":"system","content":"You are helpful."},
      {"role":"user","content":"介绍一下 AI 网关"}
    ],
    "temperature": 0.7,
    "stream": true
  }'
  

Streaming 流式响应

设置 stream: true 启用 SSE 流式输出：

  
  from openai import OpenAI

client = OpenAI(
    api_key="YOUR_KEY",
    base_url="https://api.ai-key.top/v1",
)
stream = client.chat.completions.create(
    model="YOUR_MODEL",
    messages=[{"role":"user","content":"讲个故事"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Completions (Legacy)

OpenAI Compatible

POST /v1/completions

    
    curl "https://api.ai-key.top/v1/completions"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"YOUR_MODEL","prompt":"用一句话介绍 AI","max_tokens":50}'
  

Responses

OpenAI Responses

POST /v1/responses

    
    curl "https://api.ai-key.top/v1/responses"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"YOUR_MODEL","input":"介绍一下 AI","stream":false}'
  

POST /v1/responses/compact

对话上下文压缩。

Embeddings

OpenAI Compatible

POST /v1/embeddings

    
    curl "https://api.ai-key.top/v1/embeddings"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"YOUR_MODEL","input":"向量化这段文本"}'
  

POST /v1/engines/{model}/embeddings

OpenAI 旧版 Embeddings 兼容路径。

Messages (Claude API)

Anthropic Compatible

完全兼容 Anthropic Messages API。使用 Claude SDK 时，将 base_url 设为 https://api.ai-key.top。

POST /v1/messages

    
    curl "https://api.ai-key.top/v1/messages"   -H "x-api-key: YOUR_API_KEY"   -H "anthropic-version: 2023-06-01"   -H "content-type: application/json"   -d '{
    "model": "YOUR_CLAUDE_MODEL",
    "max_tokens": 1024,
    "messages": [{"role":"user","content":"你好!"}]
  }'
  

Gemini API

Google Compatible

兼容 Google AI Gemini API。使用 x-goog-api-key 头或在查询参数中传 ?key=。

GET /v1beta/models

获取 Gemini 格式的模型列表。

POST /v1beta/models/{model}:generateContent

    
    curl "https://api.ai-key.top/v1beta/models/YOUR_MODEL:generateContent"   -H "x-goog-api-key: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "contents": [{"parts": [{"text": "你好!"}]}]
  }'
  

图片生成

Multimodal

POST /v1/images/generations

    
    curl "https://api.ai-key.top/v1/images/generations"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "YOUR_MODEL",
    "prompt": "一只可爱的橘猫在太空站",
    "n": 1,
    "size": "1024x1024"
  }'
  

POST /v1/images/edits

图片编辑 (DALL-E 格式)。

音频 (Audio)

Multimodal

POST /v1/audio/speech

TTS 文本转语音。

POST /v1/audio/transcriptions

语音转文字 (Whisper)。

POST /v1/audio/translations

语音翻译。

视频生成

Multimodal

POST /v1/video/generations

Sora 兼容视频生成。

GET /v1/video/generations/{task_id}

查询视频任务状态。

POST /v1/videos

通用视频生成。

GET /v1/videos/{task_id}

查询视频任务。

Rerank

POST /v1/rerank

    
    curl "https://api.ai-key.top/v1/rerank"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "YOUR_MODEL",
    "query": "什么是 AI 网关",
    "documents": ["AI 网关是...", "支付网关是...", "CDN 是..."]
  }'
  

Realtime

WebSocket

GET /v1/realtime

WebSocket 实时语音对话 (OpenAI Realtime API 兼容)。

Moderations

Content Safety

POST /v1/moderations

    
    curl "https://api.ai-key.top/v1/moderations"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"YOUR_MODEL","input":"Hello"}'
  

客户端配置

以下客户端可直接填入 Base URL + API Key 使用：

Cherry Studio

设置 → 模型服务 → 添加 OpenAI 兼容提供商，API 地址: https://api.ai-key.top

Lobe Chat

设置 → OpenAI → 接口代理地址: https://api.ai-key.top/v1

NextChat (ChatGPT-Next-Web)

设置 → 自定义接口地址: https://api.ai-key.top

OpenCat

添加团队 → Domain: api.ai-key.top, Token: your key

DeepChat

安装提供商 → API 地址: https://api.ai-key.top/v1

AI as Workspace

设置 OpenAI 提供商: https://api.ai-key.top/v1

AMA 问天

设置 API 服务器: https://api.ai-key.top

Cursor / Windsurf

Settings → OpenAI Base URL: https://api.ai-key.top/v1

流式与网络

AI 对话接口支持 SSE 流式响应。客户端设置 stream: true 后，应使用不会缓存、不会压缩、不会缓冲响应体的网络链路。

HTTPS

API Key 会随请求发送，必须使用 HTTPS。HTTP 请求会自动跳转到 HTTPS。

SSE 流式

如果回答先卡住、再一次性出现，通常是中间代理开启了 buffering、缓存或压缩。

Cloudflare

如启用 Cloudflare 代理，SSL/TLS 使用 Full (strict)，并对 api.ai-key.top/* 与 ai-key.top/v1/* 设置 Cache Bypass。

流式测试

  
  curl -N --no-buffer "https://api.ai-key.top/v1/chat/completions"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "YOUR_MODEL",
    "stream": true,
    "messages": [{"role":"user","content":"请连续输出一段测试文本"}]
  }'

部署提示
反向代理需要关闭响应缓冲和缓存：proxy_buffering off、proxy_request_buffering off、proxy_cache off，并返回 X-Accel-Buffering: no。Cloudflare WAF 对 API 超限建议返回 429/Block，不建议使用 Challenge，因为桌面客户端和 SDK 通常无法处理挑战页。

常见问题

401 Unauthorized

API Key 无效或缺失。检查是否正确传递 Authorization: Bearer YOUR_KEY，确认 Key 未过期或禁用。

402 / Budget Exceeded

账户余额不足。请在控制台充值或检查 API Key 预算设置。也可能是因为上游渠道 API Key 预算耗尽，系统正在切换渠道中。

503 No Available Channel

当前模型没有可用上游渠道。可能是模型名称错误或所有上游渠道暂时不可用。用 GET /v1/models 确认模型名称是否正确。

405 Method Not Allowed

HTTP 方法错误。检查接口使用的是 GET 还是 POST，参考本文档每个接口的标注。

CORS / Preflight 失败

浏览器跨域请求需要服务端支持 OPTIONS 预检。使用服务端 SDK（Python/Node.js）可避免此问题。

提示
遇到问题请先查看控制台的日志页面，确认请求是否到达、选择了哪个渠道、上游返回了什么状态码。也可直接测试 Playground。

快速开始

Python (OpenAI SDK)

JavaScript / TypeScript

Claude SDK (Python)

Google GenAI SDK

认证

Base URL

主入口

Claude SDK

Gemini SDK

兼容别名

模型列表

Chat Completions

Streaming 流式响应

Completions (Legacy)

Responses

Embeddings

Messages (Claude API)

Gemini API

图片生成

音频 (Audio)

视频生成

Rerank

Realtime

Moderations

客户端配置

Cherry Studio

Lobe Chat

NextChat (ChatGPT-Next-Web)

OpenCat

DeepChat

AI as Workspace

AMA 问天

Cursor / Windsurf

流式与网络

推荐 API 入口

HTTPS

SSE 流式

Cloudflare

流式测试

常见问题

401 Unauthorized

402 / Budget Exceeded

503 No Available Channel

405 Method Not Allowed

CORS / Preflight 失败