API 接入文档

请将 <FLYHUB_API_KEY> 替换为控制台创建的 API Key，并妥善保管，切勿提交到代码仓库或暴露在前端。

Base URL：https://api.flyhub.cn
鉴权：API Key（控制台创建，与 LiteLLM Virtual Key 一一对应）
协议：Anthropic 原生（/v1/messages）、OpenAI 兼容（/v1/chat/completions、/v1/responses）、Gemini 原生（/v1beta/models/{model}:generateContent）、图像（/v1/images）、MCP 调用、Skill 安装包

一、Base URL 与请求头

根据所用模型选择对应的兼容格式与鉴权 Header：

Base URL

https://api.flyhub.cn/v1

OpenAI SDK 的 base_url 需包含 /v1

不同协议使用不同的鉴权 Header，请按协议选择：

协议	Header
Anthropic	x-api-key: <FLYHUB_API_KEY> anthropic-version: 2023-06-01
OpenAI	Authorization: Bearer <FLYHUB_API_KEY>
Gemini	Authorization: Bearer <FLYHUB_API_KEY>

二、可用模型

通过 GET /v1/models 实时获取完整模型列表：

bash

curl https://api.flyhub.cn/v1/models \
  -H "Authorization: Bearer <FLYHUB_API_KEY>"

当前可用模型（示例，以接口返回为准）：

OpenAI

gpt-5.6-solgpt-5.6-terragpt-5.6-luna

Anthropic

claude-fable-5-1claude-opus-5claude-sonnet-5claude-haiku-4-5

Google

gemini-3.1-progemini-3.7-flashgemini-3.5-flash-lite

DeepSeek

deepseek-v4-prodeepseek-v4-flashdeepseek-v4-flash-vision-exp

Kimi

kimi-k3

智谱 GLM

glm-5.3glm-5.3-flash

通义千问

qwen3.8-maxqwen3.7-plusqwen3.8-flash

厂商	模型 ID
OpenAI	`gpt-5.6-solgpt-5.6-terragpt-5.6-luna`
Anthropic	`claude-fable-5-1claude-opus-5claude-sonnet-5claude-haiku-4-5`
Google	`gemini-3.1-progemini-3.7-flashgemini-3.5-flash-lite`
DeepSeek	`deepseek-v4-prodeepseek-v4-flashdeepseek-v4-flash-vision-exp`
Kimi	`kimi-k3`
智谱 GLM	`glm-5.3glm-5.3-flash`
通义千问	`qwen3.8-maxqwen3.7-plusqwen3.8-flash`

能力广场已上架模型：

OpenAI

gpt-5.6-sol

OpenAI

gpt-5.6-terra

OpenAI

gpt-5.6-luna

Anthropic

claude-fable-5-1

Anthropic

claude-opus-5

Anthropic

claude-sonnet-5

Anthropic

claude-haiku-4-5

Google

gemini-3.1-pro

Google

gemini-3.7-flash

Google

gemini-3.5-flash-lite

DeepSeek

deepseek-v4-pro

DeepSeek

deepseek-v4-flash

DeepSeek

deepseek-v4-flash-vision-exp

Kimi

kimi-k3

智谱

glm-5.3

智谱

glm-5.3-flash

通义千问

qwen3.8-max

通义千问

qwen3.7-plus

通义千问

qwen3.8-flash

厂商	模型 ID
OpenAI	`gpt-5.6-sol`
OpenAI	`gpt-5.6-terra`
OpenAI	`gpt-5.6-luna`
Anthropic	`claude-fable-5-1`
Anthropic	`claude-opus-5`
Anthropic	`claude-sonnet-5`
Anthropic	`claude-haiku-4-5`
Google	`gemini-3.1-pro`
Google	`gemini-3.7-flash`
Google	`gemini-3.5-flash-lite`
DeepSeek	`deepseek-v4-pro`
DeepSeek	`deepseek-v4-flash`
DeepSeek	`deepseek-v4-flash-vision-exp`
Kimi	`kimi-k3`
智谱	`glm-5.3`
智谱	`glm-5.3-flash`
通义千问	`qwen3.8-max`
通义千问	`qwen3.7-plus`
通义千问	`qwen3.8-flash`

三、Anthropic 原生格式

端点：POST /v1/messages

Claude 模型建议优先使用 Anthropic 原生协议，可保留提示缓存、extended thinking 等能力；通过 OpenAI 兼容格式调用 Claude 可能导致能力缺失或成本上升。

3.1 基础请求

bash

curl https://api.flyhub.cn/v1/messages \
  -H "x-api-key: <FLYHUB_API_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ]
  }'

示例响应：

json

{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [{"type": "text", "text": "我是 Claude..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 159, "output_tokens": 34}
}

3.2 流式输出（SSE）

添加 "stream": true，响应为 text/event-stream。事件顺序：message_start → content_block_delta → message_stop。

bash

curl https://api.flyhub.cn/v1/messages \
  -H "x-api-key: <FLYHUB_API_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "写一首短诗"}]
  }'

3.3 Python · anthropic SDK

python

from anthropic import Anthropic

client = Anthropic(
    api_key="<FLYHUB_API_KEY>",
    base_url="https://api.flyhub.cn",
)

resp = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.content[0].text)

四、OpenAI 兼容格式

端点：POST /v1/chat/completions（Chat Completions）、POST /v1/responses（Responses API，仅 GPT 系列）、POST /v1/embeddings（向量嵌入）

4.1 Chat Completions 基础请求

bash

curl https://api.flyhub.cn/v1/chat/completions \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'

响应遵循标准 OpenAI chat.completion 结构：

json

{
  "object": "chat.completion",
  "model": "gpt-5.6-sol",
  "choices": [
    {"index": 0, "message": {"role": "assistant", "content": "你好！"}, "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": 214, "completion_tokens": 3, "total_tokens": 217}
}

4.2 流式输出

添加 "stream": true，返回标准 OpenAI SSE 分片，以 data: [DONE] 结束。

bash

curl https://api.flyhub.cn/v1/chat/completions \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "stream": true,
    "messages": [{"role": "user", "content": "写一首短诗"}]
  }'

4.3 SDK 示例

from openai import OpenAI

client = OpenAI(
    api_key="<FLYHUB_API_KEY>",
    base_url="https://api.flyhub.cn/v1",
)

resp = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

4.4 Responses API

若应用已使用 OpenAI Responses API，可直接调用 /v1/responses。 仅支持 GPT 系列模型；Claude / Gemini 请分别使用 Anthropic 与 Gemini 原生格式，否则会返回 400。

bash

curl https://api.flyhub.cn/v1/responses \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "用一句话介绍 FlyHub"
  }'

python

from openai import OpenAI

client = OpenAI(
    api_key="<FLYHUB_API_KEY>",
    base_url="https://api.flyhub.cn/v1",
)

resp = client.responses.create(
    model="gpt-5.6-sol",
    input="用一句话介绍 FlyHub",
)
print(resp.output_text)

4.5 Embeddings

bash

curl https://api.flyhub.cn/v1/embeddings \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "FlyHub 统一能力路由"
  }'

五、Gemini 原生格式

端点：POST /v1beta/models/{model}:generateContent

5.1 基础请求

bash

curl https://api.flyhub.cn/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "用一句话介绍你自己"}]}
    ]
  }'

示例响应：

json

{
  "candidates": [
    {
      "content": {"role": "model", "parts": [{"text": "我是 Gemini..."}]},
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {"promptTokenCount": 12, "candidatesTokenCount": 22, "totalTokenCount": 34}
}

5.2 流式输出

使用 streamGenerateContent 并添加 alt=sse 查询参数。

bash

curl "https://api.flyhub.cn/v1beta/models/gemini-3.7-flash:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "写一首短诗"}]}
    ]
  }'

5.3 环境变量

若工具或 SDK 支持自定义 Gemini Base URL，可如下配置：

bash

export GOOGLE_GEMINI_BASE_URL="https://api.flyhub.cn"
export GEMINI_API_KEY="<FLYHUB_API_KEY>"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

不同 Gemini SDK 的字段名可能为 base_url、baseURL、apiEndpoint 等，核心原则是将 Base URL 指向 https://api.flyhub.cn 并使用 FlyHub API Key。

六、图像生成

图像模型使用独立的 /v1/images 端点，鉴权方式为 Authorization: Bearer。

6.1 生成图像

端点：POST /v1/images/generations

bash

curl https://api.flyhub.cn/v1/images/generations \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "一只橘猫在键盘上打字的插画风格图片"
  }'

响应中 data[0].b64_json 为 Base64 编码图像。建议将超时设为 300 秒，图像生成耗时较长。

json

{
  "created": 1752345600,
  "data": [
    {"b64_json": "iVBORw0KGgo..."}
  ]
}

6.2 编辑图像

端点：POST /v1/images/edits，以 multipart/form-data 上传源图。

bash

curl https://api.flyhub.cn/v1/images/edits \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -F model="gpt-image-1" \
  -F image="@photo.png" \
  -F prompt="把背景替换成星空"

七、MCP 调用

端点：POST /v1/mcp/{slug}/invoke，与模型共用同一 API Key。

bash

curl -X POST https://api.flyhub.cn/v1/mcp/dingtalk-sheets/invoke \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "records/query",
    "arguments": {"table": "订单表"}
  }'

请求体中的 tool 为 MCP 工具名，arguments 为工具参数。可在能力广场 · MCP查看各服务的工具列表与示例。

八、Skill 交付

Skill 只提供安装包，不在平台上运行，也不计费。在能力广场 · Skill详情页复制安装说明，发给你的 Agent；由 Agent 按说明把文件写到本地。

请根据 https://flyhub.cn/v1/catalog/skills/install.md，安装 @flyhub/code-reviewer

九、接入 Agent 工具

Claude Code 使用 Anthropic 协议，Codex / Cursor 等使用 OpenAI 协议，Gemini CLI 使用 Gemini 协议。只需将 Base URL 与 API Key 环境变量指向 FlyHub，无需修改工具本身。

各工具的详细安装与一键配置步骤，请见左侧 快速接入 Agent 目录，例如 DeepSeek Harness、Claude Code、Codex CLI。

命令行类工具可使用 FlyHub CLI 一键写入本地配置。先安装命令：

# 安装 FlyHub CLI
curl -fsSL https://flyhub.cn/install.sh | bash
export PATH="$HOME/.flyhub/bin:$PATH"

安装完成后，将 Key 换成控制台密钥并执行：

bash

flyhub setup list
flyhub setup deepseek-harness --key <FLYHUB_API_KEY>
flyhub setup codex --key <FLYHUB_API_KEY>
flyhub setup claude-code --key <FLYHUB_API_KEY>
flyhub setup gemini --key <FLYHUB_API_KEY>
flyhub setup kimi --key <FLYHUB_API_KEY>

Claude Code（Anthropic 协议）

bash

export ANTHROPIC_BASE_URL="https://api.flyhub.cn"
export ANTHROPIC_API_KEY="<FLYHUB_API_KEY>"

OpenAI 协议工具（Codex / Cursor / Cline 等）

bash

export OPENAI_BASE_URL="https://api.flyhub.cn/v1"
export OPENAI_API_KEY="<FLYHUB_API_KEY>"

OpenAI SDK 的 base_url 需包含 /v1 后缀（即 https://api.flyhub.cn/v1）。

Gemini CLI

bash

export GOOGLE_GEMINI_BASE_URL="https://api.flyhub.cn"
export GEMINI_API_KEY="<FLYHUB_API_KEY>"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

十、常见问题

收到 401 / 鉴权失败？

先核对协议与 Header 的对应关系：Anthropic 使用 x-api-key；OpenAI / Gemini 使用 Authorization: Bearer。确认 Key 完整、无多余空格，且在控制台未被删除。OpenAI SDK 的 base_url 需带 /v1，Anthropic SDK 则不需要。

用 OpenAI 格式调 Claude 报错或效果差？

Claude 模型请优先使用 Anthropic 原生协议（/v1/messages）。Claude Code 等 Agent 工具必须配置 Anthropic 协议。通过 OpenAI 兼容格式调用 Claude 可能丢失提示缓存、thinking 等能力，仅适合简单对话。/v1/responses 不支持 Claude / Gemini。

模型不可用？

先调用 GET /v1/models 获取实时列表，核对模型 ID 拼写（小写、连字符），并确认端点与模型协议匹配。

超时或首字延迟高？

大型推理模型首 token 可能需要数秒至数十秒，不代表请求失败。生产环境建议开启 stream: true 改善体感延迟，并适当增大客户端读取超时。网关支持最长 600 秒响应。

Key 安全

使用环境变量或密钥管理服务存储 Key，不要硬编码、提交 Git 或打包进前端 / 公开客户端。若怀疑泄露，请立即在控制台删除并轮换。

准备好了？登录控制台 · 充值 · 创建 API Key

获取 API Key 查看定价

FlyHub API 接入文档

一、Base URL 与请求头

二、可用模型

三、Anthropic 原生格式

3.1 基础请求

3.2 流式输出（SSE）

3.3 Python · anthropic SDK

四、OpenAI 兼容格式

4.1 Chat Completions 基础请求

4.2 流式输出

4.3 SDK 示例

4.4 Responses API

4.5 Embeddings

五、Gemini 原生格式

5.1 基础请求

5.2 流式输出

5.3 环境变量

六、图像生成

6.1 生成图像

6.2 编辑图像

七、MCP 调用

八、Skill 交付

九、接入 Agent 工具

Claude Code（Anthropic 协议）

OpenAI 协议工具（Codex / Cursor / Cline 等）

Gemini CLI

十、常见问题

收到 401 / 鉴权失败？

用 OpenAI 格式调 Claude 报错或效果差？

模型不可用？

超时或首字延迟高？

Key 安全