API 文档

FangKa Ai 兼容 Anthropic / OpenAI API 格式，无缝切换，即改即用。

简介

FangKa Ai 提供统一的 API 网关服务，通过一个 API Key 即可访问 Claude、GPT、Gemini、DeepSeek 等多种主流大模型。接口与 Anthropic / OpenAI 官方完全兼容，现有代码仅需修改 Base URL 即可接入，无需更改任何业务逻辑。

认证方式

所有 API 请求都需要在 HTTP Header 中携带 API Key 进行身份认证。FangKa Ai 支持以下两种认证格式，你可以根据使用的 SDK 选择对应的方式：

方式一：Anthropic 原生格式

适用于 Anthropic SDK 或直接调用 Anthropic 兼容端点：

x-api-key: sk-fkai-xxxxxxxxxxxx

方式二：Bearer Token 格式

适用于 OpenAI SDK 或通用 HTTP 客户端：

Authorization: Bearer sk-fkai-xxxxxxxxxxxx

Base URL

根据你使用的 SDK 类型，选择对应的 Base URL：

版本控制

使用 Anthropic 兼容端点时，需要在请求头中指定 API 版本：

anthropic-version: 2023-06-01

当前支持的版本为 2023-06-01，建议始终显式指定版本号以确保接口行为一致。

Messages API

Messages API 是最核心的接口，用于发送消息并获取 AI 模型的回复。完全兼容 Anthropic Messages API 规范。

请求体参数

基础请求示例

curl https://fkai.cc/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-fkai-xxxx" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "什么是 API 网关？请简要说明。"}
    ]
  }'

响应格式

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "API 网关是一个服务器，充当 API 消费者与后端服务之间的中间层..."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 156
  }
}

stop_reason 说明

多轮对话

通过在 messages 数组中交替排列 user 和 assistant 角色的消息，可以实现多轮对话。模型会根据完整的对话历史生成回复。

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "我正在学习 Python，你能帮我吗？"},
    {"role": "assistant", "content": "当然可以！Python 是一门很棒的编程语言。你想从哪个方面开始学习呢？"},
    {"role": "user", "content": "我想了解列表推导式怎么用"},
    {"role": "assistant", "content": "列表推导式是 Python 中非常优雅的语法..."},
    {"role": "user", "content": "能给我一个实际的例子吗？"}
  ]
}

多模态 / 视觉

支持发送图片给模型进行视觉理解和分析。在 content 中使用数组格式，混合 image 和 text 类型：

Base64 方式（推荐）

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgo..."
          }
        },
        {
          "type": "text",
          "text": "请详细描述这张图片的内容"
        }
      ]
    }
  ]
}

URL 方式

{
  "type": "image",
  "source": {
    "type": "url",
    "url": "https://example.com/image.jpg"
  }
}

Streaming（流式输出）

设置 "stream": true 启用 Server-Sent Events (SSE) 流式输出，可实时逐字获取模型生成的内容，大幅降低首字延迟（TTFT）。

请求示例

curl https://fkai.cc/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-fkai-xxxx" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "写一首关于编程的短诗"}
    ]
  }'

SSE 事件类型

SSE 数据格式示例

event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","model":"claude-sonnet-4-20250514"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"代码"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"如诗"}}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":42}}

event: message_stop
data: {"type":"message_stop"}

Models API

查询当前可用的模型列表及详细信息。

响应示例

{
  "data": [
    {
      "id": "claude-sonnet-4-20250514",
      "name": "Claude Sonnet 4",
      "provider": "anthropic",
      "max_tokens": 8192
    },
    {
      "id": "claude-opus-4-20250514",
      "name": "Claude Opus 4",
      "provider": "anthropic",
      "max_tokens": 32768
    },
    {
      "id": "gpt-4o",
      "name": "GPT-4o",
      "provider": "openai",
      "max_tokens": 16384
    },
    {
      "id": "gemini-2.5-pro",
      "name": "Gemini 2.5 Pro",
      "provider": "gemini",
      "max_tokens": 65536
    }
  ]
}

OpenAI 兼容接口

FangKa Ai 同时提供完整的 OpenAI Chat Completions 兼容接口，无需修改代码即可从 OpenAI 迁移。

cURL 示例

curl https://fkai.cc/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-fkai-xxxx" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "你是一个专业的技术顾问。"},
      {"role": "user", "content": "解释一下微服务架构"}
    ],
    "max_tokens": 1024,
    "temperature": 0.7
  }'

Python (OpenAI SDK) 示例

from openai import OpenAI

client = OpenAI(
    api_key="sk-fkai-xxxx",
    base_url="https://fkai.cc/openai/v1"
)

# 非流式调用
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "你是一个专业的技术顾问。"},
        {"role": "user", "content": "解释微服务架构"}
    ]
)
print(response.choices[0].message.content)

# 流式调用
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

系统提示词

系统提示词用于定义 AI 的角色、行为方式和约束条件。它是独立于对话消息的顶层参数（与 OpenAI 将 system 放在 messages 中不同）。

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "system": "你是 FangKa Ai 的客服助手。请用专业但友好的语气回答用户关于产品和定价的问题。回答应简洁明了，如果不确定，请坦诚告知用户。",
  "messages": [
    {"role": "user", "content": "你们支持哪些模型？"}
  ]
}

Tool Use（工具调用）

允许模型调用你预定义的工具/函数来获取外部信息或执行操作。模型会智能判断何时需要使用工具，并生成符合你定义的参数格式的调用请求。

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "获取指定城市的当前天气信息",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "城市名称，如 北京、上海"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"],
            "description": "温度单位"
          }
        },
        "required": ["city"]
      }
    }
  ],
  "messages": [
    {"role": "user", "content": "北京今天天气怎么样？"}
  ]
}

工具调用流程

1. 发送带 tools 定义的请求 → 2. 模型返回 tool_use 内容块 → 3. 你执行工具并返回 tool_result → 4. 模型根据结果生成最终回复

工具调用响应示例

{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"city": "北京", "unit": "celsius"}
    }
  ]
}

返回工具结果

{
  "messages": [
    {"role": "user", "content": "北京今天天气怎么样？"},
    {"role": "assistant", "content": [
      {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "get_weather", "input": {"city": "北京"}}
    ]},
    {"role": "user", "content": [
      {"type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "北京：晴，28°C，湿度 45%"}
    ]}
  ]
}

Prompt Caching

对于 Anthropic 模型，支持 Prompt Caching 功能。将重复使用的系统提示词或上下文标记为可缓存，后续请求命中缓存时可大幅降低输入 Token 费用（降低约 90%）。

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "这里是你的很长的系统提示词...",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [
    {"role": "user", "content": "你好"}
  ]
}

错误处理

API 使用标准 HTTP 状态码。出错时，响应体包含结构化的 JSON 错误信息：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: Field required"
  }
}

推荐的重试策略

import time
import anthropic

client = anthropic.Anthropic(
    api_key="sk-fkai-xxxx",
    base_url="https://fkai.cc"
)

max_retries = 3
for attempt in range(max_retries):
    try:
        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=1024,
            messages=[{"role": "user", "content": "Hello"}]
        )
        break  # 成功则退出重试循环
    except anthropic.RateLimitError:
        wait = 2 ** attempt  # 1s, 2s, 4s 指数退避
        print(f"速率限制，{wait}s 后重试...")
        time.sleep(wait)
    except anthropic.APIStatusError as e:
        if e.status_code >= 500:
            time.sleep(2 ** attempt)
        else:
            raise  # 客户端错误无需重试

速率限制

速率限制取决于你的账户等级和套餐配置。超出限制时返回 429 状态码。可通过响应头获取限制详情：

SDK 支持

FangKa Ai 完全兼容 Anthropic 和 OpenAI 官方 SDK，你可以选择任一 SDK 接入。

只需在初始化 SDK 时指定 base_url 即可。详细的接入示例请参阅 快速上手教程。