API 接入文档

发给 Agent（推荐）

把下面这段发给你正在用的 Agent（AI 助手），让它帮你完成接入。

模型路由切到 FlyHub
注册全部已上架 Remote MCP

请根据 https://flyhub.com.cn/v1/catalog/agents/setup.md，使用 FlyHub API Key <FLYHUB_API_KEY> 完成接入。

登录后可直接带上真实 Key

Skill 仍从能力详情页单独安装。Agent 会按接入说明执行；自己写 HTTP 或配环境变量，请看下面各节。

一、Base URL 与请求头

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

Base URL：https://api.flyhub.com.cn
鉴权：API Key（控制台创建）。两种请求头都接受：Authorization: Bearer <Key> 与 x-api-key: <Key>—— Anthropic 系客户端（anthropic-sdk、Claude Code 的 ANTHROPIC_API_KEY 等）只发后者，可直接使用，无需改装成 Bearer。
协议：Anthropic、OpenAI 兼容，以及图像、视频、MCP、Skill

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

Base URL

https://api.flyhub.com.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>

二、可用模型

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

bash

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

当前已上架模型（对话、生图、生视频、音频、向量；对话客户端只接 family=chat）：

OpenAI

gpt-5.6-solgpt-5.6-terragpt-6-astragpt-6-solgpt-6.1-sol

Anthropic

claude-fable-5-1claude-haiku-4-5claude-opus-5claude-sonnet-5claude-fable-5claude-haiku-5-5claude-opus-4-7claude-opus-4-6claude-opus-4-8claude-sonnet-4-6claude-opus-5-5claude-sonnet-5-5

DeepSeek

deepseek-v4-prodeepseek-flash

Kimi

kimi-k3

智谱

glm-5.3glm-5.3-flash

字节跳动

doubao-seedance-2-0doubao-seedance-2-0-fastdoubao-seedance-2-0-minidoubao-seedance-2-5

厂商	模型 ID
OpenAI	`gpt-5.6-solgpt-5.6-terragpt-6-astragpt-6-solgpt-6.1-sol`
Anthropic	`claude-fable-5-1claude-haiku-4-5claude-opus-5claude-sonnet-5claude-fable-5claude-haiku-5-5claude-opus-4-7claude-opus-4-6claude-opus-4-8claude-sonnet-4-6claude-opus-5-5claude-sonnet-5-5`
DeepSeek	`deepseek-v4-prodeepseek-flash`
Kimi	`kimi-k3`
智谱	`glm-5.3glm-5.3-flash`
字节跳动	`doubao-seedance-2-0doubao-seedance-2-0-fastdoubao-seedance-2-0-minidoubao-seedance-2-5`

三、Anthropic 原生格式

端点：POST /v1/messages

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

3.1 基础请求

bash

curl https://api.flyhub.com.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.com.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.com.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.com.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.com.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.com.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 请使用 Anthropic 原生格式（/v1/messages），否则会返回 400。

bash

curl https://api.flyhub.com.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.com.cn/v1",
)

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

4.5 Embeddings

平台接口已就绪（POST /v1/embeddings），但目录里目前没有上架 embedding 模型，未上架的模型名会被拒绝（400 模型不存在或未上架）。上架后此处示例可直接使用。

bash

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

五、图像生成

端点：POST /v1/images/generations；改图另走 POST /v1/images/edits，但只有声明支持改图的模型才有这个端点。鉴权与对话相同（同一把 API Key，Authorization: Bearer）。模型是否吃源图，以模型详情页「输入类型」或 GET /v1/models 里的image.supports_edits 为准。

同步请求，服务端可能占用连接 120–300 秒；客户端 HTTP timeout 请设为 ≥ 300 秒。
推荐 response_format: "url"；b64_json 单张可达数 MB，易触发体积或超时限制。
尺寸与质量在请求体传 size / quality，不要做成独立模型名。
计费按返回图片张数结算（单价 × data.length）。请求体 n 为预留上限；上游少返回时按实际张数扣费。

5.1 生成图像

端点：POST /v1/images/generations

bash

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

成功时 data[] 含 url（推荐）或 b64_json：

json

{
  "created": 1752345600,
  "data": [
    {"url": "https://example.com/generated-image.png"}
  ]
}

5.2 编辑图像

仅 supports_edits=true 的模型可用；未声明改图的模型请走 5.1 生成。端点：POST /v1/images/edits，以 multipart/form-data 上传源图。同样为同步长请求，timeout 建议 ≥ 300 秒。

bash

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

六、视频生成

端点：POST /v1/videos（创建）、GET /v1/videos/{id}（查状态）、GET /v1/videos/{id}/content（下载）、DELETE /v1/videos/{id}（取消）。鉴权与对话相同（同一把 API Key，Authorization: Bearer）。

异步任务。对外任务 ID 为 vid_ + ULID（例如 vid_01ARZ3NDEKTSV4RRFFQ69G5FAV）；轮询 / 下载 / 取消请原样回传。
按成片秒数计费（创建时按 seconds 预留，完成按实际时长结算，取消释放预留）。分辨率档位通过请求 size 选择（如 480p / 720p），不是单独模型名。
只有声明支持首帧图的模型（video.supports_first_frame=true）才接收首帧输入：用 multipart 的 input_reference 上传首帧图，与其它参数同一请求。不支持的模型不要传。
创建建议带 Idempotency-Key：相同 Key 重放返回同一 vid_*。
创建后多为 queued / in_progress，请轮询至 completed 再下载；运行中取消可能返回 409，预留仍会释放。

6.1 创建任务

端点：POST /v1/videos

bash

curl https://api.flyhub.com.cn/v1/videos   -H "Authorization: Bearer <FLYHUB_API_KEY>"   -H "Content-Type: application/json"   -H "Idempotency-Key: demo-seedance-001"   -d '{
    "model": "seedance-1.0-pro",
    "prompt": "A red cube slowly rotating on a white table, cinematic",
    "seconds": 5,
    "size": "1280x720"
  }'

成功时返回公开 id（vid_*）与初始 status：

json

{
  "id": "vid_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "object": "video",
  "model": "seedance-1.0-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1752345600,
  "seconds": "5",
  "size": "1280x720"
}

6.2 查询状态

端点：GET /v1/videos/{id}。用创建返回的 vid_* 轮询，直到 completed / failed / cancelled。

bash

curl https://api.flyhub.com.cn/v1/videos/vid_01ARZ3NDEKTSV4RRFFQ69G5FAV   -H "Authorization: Bearer <FLYHUB_API_KEY>"

6.3 下载内容

端点：GET /v1/videos/{id}/content。任务 completed 后下载媒体（如 video/mp4）。

bash

curl -L https://api.flyhub.com.cn/v1/videos/vid_01ARZ3NDEKTSV4RRFFQ69G5FAV/content   -H "Authorization: Bearer <FLYHUB_API_KEY>"   -o out.mp4

6.4 取消任务

端点：DELETE /v1/videos/{id}。未知 vid_* 返回 404；运行中取消可能返回 409，预留会释放。

bash

curl -X DELETE https://api.flyhub.com.cn/v1/videos/vid_01ARZ3NDEKTSV4RRFFQ69G5FAV   -H "Authorization: Bearer <FLYHUB_API_KEY>"

七、MCP 调用

本节是程序里直接 HTTP 调用 MCP。要把 Remote MCP 注册进 Cursor / Claude Code 等客户端，请用上方「发给 Agent」。

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

bash

curl -X POST https://api.flyhub.com.cn/v1/mcp/agentearth/invoke \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "GetAccountOverview",
    "arguments": {}
  }'

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

Remote MCP 客户端（Cursor、Claude Code 等）注册时填的就是上面这个地址 —— 它们发的是标准 JSON-RPC：initialize 与 tools/list不扣费，tools/call 按次计费。

bash

# 1) 握手（不计费）
curl -X POST https://api.flyhub.com.cn/v1/mcp/agentearth/invoke \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"cursor","version":"1"}}}'

# 2) 列工具（不计费）
curl -X POST https://api.flyhub.com.cn/v1/mcp/agentearth/invoke \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3) 调工具（按次计费）
curl -X POST https://api.flyhub.com.cn/v1/mcp/agentearth/invoke \
  -H "Authorization: Bearer <FLYHUB_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"GetAccountOverview","arguments":{}}}'

八、Skill 安装

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

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

九、接入 Agent 工具

接到 Cursor / Claude Code 等，优先用上方「发给 Agent」。下面是自己改环境变量或跑 CLI 的备选步骤。Claude Code 使用 Anthropic 协议，Codex / Cursor 等使用 OpenAI 协议，Gemini CLI 使用 Gemini 协议。

各工具的详细手动步骤，请见左侧 快速接入 Agent 目录，例如 DeepSeek Harness、Claude Code、Codex CLI、WorkBuddy。

下面这些工具可以用 FlyHub CLI 一键写入本地配置。先安装命令：

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

安装完成后，将 Key 换成控制台密钥并执行。一键安装只写对话模型；生图、生视频、音频、向量走模型详情页的专用端点，不要塞进模型选择器。各客户端的文件差异见左侧「快速接入 Agent」目录。

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>
flyhub setup workbuddy --key <FLYHUB_API_KEY>

Claude Code（Anthropic 协议）

bash

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

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

bash

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

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

Gemini CLI

bash

export GOOGLE_GEMINI_BASE_URL="https://api.flyhub.com.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 接入文档

发给 Agent（推荐）

一、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

五、图像生成

5.1 生成图像

5.2 编辑图像

六、视频生成

6.1 创建任务

6.2 查询状态

6.3 下载内容

6.4 取消任务

七、MCP 调用

八、Skill 安装

九、接入 Agent 工具

Claude Code（Anthropic 协议）

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

Gemini CLI

十、常见问题

收到 401 / 鉴权失败？

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

模型不可用？

超时或首字延迟高？

Key 安全