> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fortapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 参考

> 同时支持 OpenAI 协议和 Anthropic Claude 协议，按需选择

FortAPI **同时支持两种 API 协议**：经典的 OpenAI 兼容，和原生 Anthropic Claude 兼容。**同一把 API key 在两边都能用**。

<CardGroup cols={2}>
  <Card title="OpenAI 协议" icon="plug">
    `POST /v1/chat/completions` —— 行业标准，几乎所有 SDK 和框架都支持。
  </Card>

  <Card title="Claude 协议" icon="brain">
    `POST /v1/messages` —— Anthropic 原生格式，支持 thinking 块和 MCP。
  </Card>
</CardGroup>

## 基础 URL

```
https://www.fortapi.com/v1
```

所有端点都挂在 `/v1` 下。鉴权通过 `Authorization: Bearer sk-...` 头。

<Note>
  用 **OpenAI 协议**时 base\_url 要带 `/v1`（`https://www.fortapi.com/v1`）；用 **Anthropic SDK** 时 `ANTHROPIC_BASE_URL` 填到根域 **不带 `/v1`**（`https://www.fortapi.com`），SDK 会自己补 `/v1/messages`，多写 `/v1` 反而会 404。
</Note>

***

## OpenAI 协议

如果你的代码已经在用 **OpenAI 官方 SDK** 或兼容框架（LangChain、LlamaIndex、Vercel AI SDK 等），用这个协议。

### 端点

```
POST https://www.fortapi.com/v1/chat/completions
```

### 兼容性

请求/响应格式与 [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat) 完全一致。支持：

* `messages`（角色 `system` / `user` / `assistant` / `tool`）
* `model` —— 模型库里任意模型名（包括 Claude/Gemini/Grok，我们会自动转换协议）
* `stream: true` 流式响应（Server-Sent Events）
* `tools` / `tool_choice` —— function calling
* `temperature`、`top_p`、`max_tokens` 等参数

### Python 示例（OpenAI SDK）

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的KEY",
    base_url="https://www.fortapi.com/v1",
)

response = client.chat.completions.create(
    model="你的模型名",  # 可用模型名见主站价格页面
    messages=[
        {"role": "system", "content": "你是一个友好的助手。"},
        {"role": "user", "content": "你好！你能做什么？"},
    ],
    temperature=0.7,
)

print(response.choices[0].message.content)
print(f"消耗 token: {response.usage.total_tokens}")
```

### Node.js 示例（OpenAI SDK）

```javascript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-你的KEY",
  baseURL: "https://www.fortapi.com/v1",
});

const response = await client.chat.completions.create({
  model: "你的模型名", // 用 OpenAI 协议调 Claude 也可以（可用模型名见主站价格页面）
  messages: [
    { role: "user", content: "用大白话解释量子纠缠。" },
  ],
});

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

### curl 示例（带 streaming）

```bash theme={null}
# 把 "你的模型名" 换成主站价格页面上的任意模型名
curl https://www.fortapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的模型名",
    "messages": [{"role": "user", "content": "写一首关于代码的俳句。"}],
    "stream": true
  }'
```

把 `你的模型名` 换成主站价格页面上的任意模型名。

***

## Claude 协议

如果你的代码用 **Anthropic SDK**，或者你需要 Claude 特有的功能（thinking 块、原生格式 tool calls），用这个协议。

### 端点

```
POST https://www.fortapi.com/v1/messages
```

### 兼容性

请求/响应格式与 [Anthropic Messages API](https://docs.anthropic.com/claude/reference/messages_post) 完全一致。支持：

* `messages` 数组（Claude 原生格式）
* `system` 作为单独字段
* `model` —— Claude 模型名或其他（我们会转成 Claude 协议）
* `max_tokens`（Claude 必填）
* `stream: true`
* `tools` / `tool_choice`
* `thinking` —— 推理模型的思考模式

### Python 示例（Anthropic SDK）

```python theme={null}
from anthropic import Anthropic

client = Anthropic(
    api_key="sk-你的KEY",
    base_url="https://www.fortapi.com",
)

response = client.messages.create(
    model="你的模型名",  # 可用模型名见主站价格页面
    max_tokens=1024,
    system="你是一个技术专家。",
    messages=[
        {"role": "user", "content": "什么是 CAP 定理？"},
    ],
)

print(response.content[0].text)
print(f"消耗：input={response.usage.input_tokens}, output={response.usage.output_tokens}")
```

### Node.js 示例（Anthropic SDK）

```javascript theme={null}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "sk-你的KEY",
  baseURL: "https://www.fortapi.com",
});

const response = await client.messages.create({
  model: "你的模型名", // 可用模型名见主站价格页面
  max_tokens: 1024,
  messages: [
    { role: "user", content: "解释 Rust borrow checker 的工作原理。" },
  ],
});

console.log(response.content[0].text);
```

### curl 示例

```bash theme={null}
# 把 "你的模型名" 换成主站价格页面上的任意模型名
curl https://www.fortapi.com/v1/messages \
  -H "x-api-key: sk-你的KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的模型名",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "写一首关于代码的俳句。"}]
  }'
```

把 `你的模型名` 换成主站价格页面上的任意模型名。

<Note>
  Anthropic SDK 用的是 `x-api-key` 头，不是 `Authorization: Bearer`。FortAPI 在 `/v1/messages` 端点上 **两种头都接受**。
</Note>

***

## 该选哪个协议

| 场景                                       | 用                    |
| ---------------------------------------- | -------------------- |
| 已经在用 OpenAI SDK / LangChain / LlamaIndex | **OpenAI 协议**        |
| 写原生 Anthropic 代码，需要 thinking 块           | **Claude 协议**        |
| 现有 OpenAI 代码想调 Claude                    | **OpenAI 协议**（我们会转换） |
| Anthropic SDK 想调 GPT 模型                  | **Claude 协议**（我们会转换） |

不管哪个 —— **同一把 API key**，每 token 同价，余额同账户。

***

## 更多用法

下面用 OpenAI 协议演示，Claude 协议的等价写法见各自 SDK 文档。

### 流式响应（消费 SSE）

开 `stream: true` 后，响应是一串 Server-Sent Events：每行以 `data: ` 开头，最后以 `data: [DONE]` 收尾。官方 SDK 已经替你解析好，直接遍历即可。

<CodeGroup>
  ```python Python theme={null}
  stream = client.chat.completions.create(
      model="你的模型名",  # 可用模型名见主站价格页面
      messages=[{"role": "user", "content": "从 1 数到 5"}],
      stream=True,
  )
  for chunk in stream:
      delta = chunk.choices[0].delta.content
      if delta:
          print(delta, end="", flush=True)
  ```

  ```javascript Node.js theme={null}
  const stream = await client.chat.completions.create({
    model: "你的模型名", // 可用模型名见主站价格页面
    messages: [{ role: "user", content: "从 1 数到 5" }],
    stream: true,
  });
  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || "");
  }
  ```
</CodeGroup>

### 工具调用（function calling）

模型决定要调用哪个函数并返回参数，**你**在本地执行函数，再把结果作为 `role: "tool"` 消息回传，模型据此产出最终回答。

```python theme={null}
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询某个城市的当前天气",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

messages = [{"role": "user", "content": "北京现在天气怎么样？"}]
resp = client.chat.completions.create(
    model="你的模型名",  # 需为支持工具调用的模型，可用模型名见主站价格页面
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

msg = resp.choices[0].message
if msg.tool_calls:
    call = msg.tool_calls[0]
    # 自己执行函数（这里用假数据），把结果回传
    messages.append(msg)
    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": '{"temp": "26°C", "weather": "晴"}',
    })
    final = client.chat.completions.create(model="你的模型名", messages=messages)
    print(final.choices[0].message.content)
```

### 视觉 / 多模态

把一条 `user` 消息的 `content` 写成数组，混入 `image_url`。图片可以是 URL，也可以是 `data:` base64：

```python theme={null}
response = client.chat.completions.create(
    model="你的模型名",  # 需为支持视觉的模型，可用模型名见主站价格页面
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图里有什么？"},
            {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}},
            # base64：{"url": "data:image/jpeg;base64,<BASE64_DATA>"}
        ],
    }],
)
print(response.choices[0].message.content)
```

### 嵌入向量 / 图片 / 音频

<CodeGroup>
  ```python Embeddings theme={null}
  emb = client.embeddings.create(
      model="你的模型名",  # 需为嵌入模型，可用模型名见主站价格页面
      input="要向量化的文本",
  )
  print(len(emb.data[0].embedding))
  ```

  ```python 图片生成 theme={null}
  img = client.images.generate(
      model="你的模型名",  # 需为绘图模型，可用模型名见主站价格页面
      prompt="一只在敲代码的柴犬，扁平插画风",
      size="1024x1024",
  )
  print(img.data[0].url)
  ```

  ```bash 语音转文字 theme={null}
  curl https://www.fortapi.com/v1/audio/transcriptions \
    -H "Authorization: Bearer sk-你的KEY" \
    -F file=@audio.mp3 \
    -F model="你的模型名"
  ```

  ```bash 文字转语音 theme={null}
  curl https://www.fortapi.com/v1/audio/speech \
    -H "Authorization: Bearer sk-你的KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"你的模型名","input":"你好，世界","voice":"alloy"}' \
    --output speech.mp3
  ```
</CodeGroup>

***

## 全部端点

| 方法   | 路径                         | 用途                            |
| ---- | -------------------------- | ----------------------------- |
| POST | `/v1/chat/completions`     | OpenAI Chat Completions       |
| POST | `/v1/messages`             | Claude Messages（Anthropic 原生） |
| POST | `/v1/responses`            | OpenAI Responses API          |
| POST | `/v1/embeddings`           | 嵌入向量（OpenAI 兼容）               |
| POST | `/v1/images/generations`   | 图片生成（OpenAI 兼容）               |
| POST | `/v1/audio/transcriptions` | 语音转文字                         |
| POST | `/v1/audio/speech`         | 文字转语音（TTS）                    |
| POST | `/v1/rerank`               | 重排序                           |
| POST | `/v1/moderations`          | 内容审核                          |
| POST | `/v1/video/generations`    | 视频生成                          |
| GET  | `/v1/models`               | 模型列表                          |
| POST | `/v1beta/models/*`         | Gemini 原生协议                   |
| POST | `/mj/*`                    | Midjourney 绘图                 |
| POST | `/suno/*`                  | Suno 音乐生成                     |

完整带模型清单的列表在主站「价格」页看。具体到每个端点支持哪些模型，以价格页与控制台「模型」列表为准。