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

# 接入指南

> 了解如何快速接入 HaiRoute 大模型网关，支持 OpenAI Chat Completions、OpenAI Responses 和 Claude 接口

HaiRoute 大模型网关支持 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Claude Messages 三种主流 API 协议，你只需三步即可完成接入：获取 API Key、调用 API、接入 AI 工具。

## 第一步：获取 API Key

1. 注册并登录 [HaiRoute 控制台](https://hairoute.ai)
2. 进入左侧菜单 **令牌管理**
3. 点击 **创建 API Key**，填写名称后生成密钥
4. 复制并妥善保存生成的 API Key（仅创建时可见一次）

<Warning>
  请妥善保管 API Key，不要在客户端代码或公开仓库中暴露密钥。
</Warning>

## 第二步：调用 API

HaiRoute 提供三种接口格式。请根据客户端或 SDK 所要求的协议选择；模型 ID 本身不决定使用哪种协议。

| 协议                      | 接口地址                        | 适用场景                                        |
| ----------------------- | --------------------------- | ------------------------------------------- |
| OpenAI Chat Completions | `POST /v1/chat/completions` | SDK 或工具要求使用 Chat Completions API            |
| OpenAI Responses        | `POST /v1/responses`        | SDK 或工具要求使用 Responses API                   |
| Anthropic Messages      | `POST /v1/messages`         | SDK 或工具要求使用 Claude / Anthropic Messages API |

### 什么时候推荐使用哪种协议？

首先以客户端或 SDK 要求的协议为准。如果客户端同时支持多种格式，可按以下建议选择：

* **优先选择 Chat Completions**：兼容性最广，适合已有的 OpenAI 兼容应用、较早版本的 SDK，以及使用 `messages` 传递对话历史的工具；不确定时可将其作为默认选择。
* **选择 Responses**：适合新接入且明确采用 OpenAI Responses API 的应用，或需要 `input` 请求格式及 Responses 专属能力的场景。详见 [Responses 格式 API](/docs/zh/api-reference/chat/responses-format)。
* **选择 Anthropic Messages**：适合 Claude Code、Anthropic SDK，以及其他要求原生 Messages 格式的 Claude 生态工具。

<Note>
  不要仅根据模型名称选择协议。同一模型可以通过多种已支持的协议调用，正确的接口地址由客户端所使用的请求格式决定。
</Note>

### OpenAI 格式

适用于 OpenAI 系列模型，兼容 `POST /v1/chat/completions` 协议。

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://api.hairoute.ai/v1/chat/completions"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "model": "gpt-4o",
      "messages": [
          {"role": "user", "content": "你好，请介绍一下自己"}
      ]
  }

  response = requests.post(url, json=data, headers=headers)
  print(response.json())
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.http.HttpRequest.BodyPublishers;

  String apiKey = "YOUR_API_KEY";
  String body = """
      {
          "model": "gpt-4o",
          "messages": [
              {"role": "user", "content": "你好，请介绍一下自己"}
          ]
      }
      """;

  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.hairoute.ai/v1/chat/completions"))
      .header("Authorization", "Bearer " + apiKey)
      .header("Content-Type", "application/json")
      .POST(BodyPublishers.ofString(body))
      .build();

  HttpClient client = HttpClient.newHttpClient();
  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.hairoute.ai/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "gpt-4o",
      messages: [
        { role: "user", content: "你好，请介绍一下自己" }
      ]
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```curl cURL theme={null}
  curl -X POST "https://api.hairoute.ai/v1/chat/completions" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [
        {"role": "user", "content": "你好，请介绍一下自己"}
      ]
    }'
  ```
</CodeGroup>

### OpenAI Responses 格式

对于使用 OpenAI Responses API 的 SDK 和工具，请调用 `POST /v1/responses`。HaiRoute 在该接口上支持流式响应、工具调用、结构化输出、推理配置及网络搜索选项。

请求格式与示例请查看 [Responses 格式 API](/docs/zh/api-reference/chat/responses-format)。

### Claude 格式

适用于 Anthropic Claude 系列模型，兼容 `POST /v1/messages` 协议。

<Note>
  调用 Claude 格式接口时，需要在请求头中额外携带 `anthropic-version`，推荐值为 `2023-06-01`。
</Note>

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://api.hairoute.ai/v1/messages"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
      "anthropic-version": "2023-06-01"
  }
  data = {
      "model": "claude-sonnet-4-0",
      "max_tokens": 1024,
      "messages": [
          {"role": "user", "content": "你好，请介绍一下自己"}
      ]
  }

  response = requests.post(url, json=data, headers=headers)
  print(response.json())
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.http.HttpRequest.BodyPublishers;

  String apiKey = "YOUR_API_KEY";
  String body = """
      {
          "model": "claude-sonnet-4-0",
          "max_tokens": 1024,
          "messages": [
              {"role": "user", "content": "你好，请介绍一下自己"}
          ]
      }
      """;

  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.hairoute.ai/v1/messages"))
      .header("Authorization", "Bearer " + apiKey)
      .header("Content-Type", "application/json")
      .header("anthropic-version", "2023-06-01")
      .POST(BodyPublishers.ofString(body))
      .build();

  HttpClient client = HttpClient.newHttpClient();
  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.hairoute.ai/v1/messages", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
      "anthropic-version": "2023-06-01"
    },
    body: JSON.stringify({
      model: "claude-sonnet-4-0",
      max_tokens: 1024,
      messages: [
        { role: "user", content: "你好，请介绍一下自己" }
      ]
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```curl cURL theme={null}
  curl -X POST "https://api.hairoute.ai/v1/messages" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "claude-sonnet-4-0",
      "max_tokens": 1024,
      "messages": [
        {"role": "user", "content": "你好，请介绍一下自己"}
      ]
    }'
  ```
</CodeGroup>

## 第三步：接入常用 AI 工具

获取 API Key 并验证 API 可用后，你可以将 HaiRoute 网关接入常用 AI 编程工具。

### Cursor

1. 打开 Cursor，进入 **Settings** > **Models**
2. 在 **OpenAI API Key** 处填入你的 API Key
3. 将 **OpenAI Base URL** 设置为 `https://api.hairoute.ai/v1`
4. 保存后即可在模型列表中选择支持的模型

### Claude Code

Claude Code 支持两种接入方式：通过 CC Switch 配置供应商，或直接通过 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_MODEL` 配置 Claude Code CLI。

完整截图和模型映射步骤请查看 [通过 CC Switch 接入 Claude Code](/docs/zh/tools/claude-code)。

### Open Code

1. 在 OpenCode TUI 中直接通过菜单添加hairoute

启动 OpenCode TUI 界面
输入 /connect 命令
在供应商列表中选择 「Other」（自定义端点）
根据提示填写：
Base URL：[https://api.hairoute.ai/v1](https://api.hairoute.ai/v1)
API Key：你的 hairoute API Key
保存后，输入 /models 切换到新添加的模型即可

2. 在项目根目录的 `opencode.json` 中配置 provider 和 Base URL：

```json theme={null}
"provider": {
    "hairoute": {
      "models": {
        "deepseek-v4-flash": {
          "name": "deepseek-v4-flash"
        },
        "deepseek-v4-pro": {
          "name": "deepseek-v4-pro"
        },
      },
      "name": "hairoute",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.hairoute.ai/v1"
      }
    }
  }
```

<Tip>
  更多 AI 工具的接入方式，请参考 [AI 工具接入](/docs/zh/tools/claude-code) 章节。
</Tip>

## 下一步

* 查看 [API 文档](/docs/zh/api-reference/chat/openai-format) 了解完整的接口参数
* 查看 [模型列表](/docs/zh/api-reference/models/list-models) 了解可用的模型
* 查看 [频率限制](/docs/zh/others/rate-limits) 了解 API 调用限制