> ## 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.

# Integration guide

> Learn how to quickly integrate with HaiRoute LLM gateway, supporting OpenAI Chat Completions, OpenAI Responses, and Claude APIs

HaiRoute LLM gateway supports three API protocols: OpenAI Chat Completions, OpenAI Responses, and Anthropic Claude Messages. You can get started in three steps: get your API key, call the API, and connect to AI tools.

## Step 1: Get your API key

1. Register and log in to the [HaiRoute console](https://hairoute.ai)
2. Navigate to **Token management** in the left sidebar
3. Click **Create API Key**, enter a name, and generate your key
4. Copy and securely store the generated API key (it is shown only once)

<Warning>
  Keep your API key secure. Do not expose it in client-side code or public repositories.
</Warning>

## Step 2: Call the API

HaiRoute offers three API formats. Choose the one required by your client or SDK; the model ID itself does not determine the protocol.

| Protocol                | Endpoint                    | Use it when                                                  |
| ----------------------- | --------------------------- | ------------------------------------------------------------ |
| OpenAI Chat Completions | `POST /v1/chat/completions` | Your SDK or tool expects the Chat Completions API            |
| OpenAI Responses        | `POST /v1/responses`        | Your SDK or tool expects the Responses API                   |
| Anthropic Messages      | `POST /v1/messages`         | Your SDK or tool expects the Claude / Anthropic Messages API |

### Which protocol should I use?

Select the protocol required by the client or SDK first. If it supports more than one format, use the following guidance:

* **Choose Chat Completions** for the broadest compatibility. It is the best default for existing OpenAI-compatible applications, older SDKs, and tools that send conversation history in `messages`.
* **Choose Responses** for new integrations that explicitly use the OpenAI Responses API or need its `input`-based request format and Responses-specific features. See [Responses format API](/docs/en/api-reference/chat/responses-format).
* **Choose Anthropic Messages** for Claude Code, Anthropic SDKs, and other Claude ecosystem tools that expect the native Messages format.

<Note>
  Do not select a protocol based only on the model name. The same model can be called through different supported protocols; the client request format determines the correct endpoint.
</Note>

### OpenAI format

For OpenAI-compatible models, using the `POST /v1/chat/completions` protocol.

<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": "Hello, introduce yourself please"}
      ]
  }

  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": "Hello, introduce yourself please"}
          ]
      }
      """;

  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: "Hello, introduce yourself please" }
      ]
    })
  });

  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": "Hello, introduce yourself please"}
      ]
    }'
  ```
</CodeGroup>

### OpenAI Responses format

For SDKs and tools that use the OpenAI Responses API, send requests to `POST /v1/responses`. HaiRoute supports streaming, tool calling, structured outputs, reasoning configuration, and web-search options on this endpoint.

See [Responses format API](/docs/en/api-reference/chat/responses-format) for the request format and examples.

### Claude format

For Anthropic Claude models, using the `POST /v1/messages` protocol.

<Note>
  When calling the Claude format API, include the `anthropic-version` header. The recommended value is `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": "Hello, introduce yourself please"}
      ]
  }

  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": "Hello, introduce yourself please"}
          ]
      }
      """;

  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: "Hello, introduce yourself please" }
      ]
    })
  });

  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": "Hello, introduce yourself please"}
      ]
    }'
  ```
</CodeGroup>

## Step 3: Connect to AI tools

Once you have your API key and the API is verified, you can connect HaiRoute to popular AI coding tools.

### Cursor

1. Open Cursor, go to **Settings** > **Models**
2. Enter your API key in the **OpenAI API Key** field
3. Set **OpenAI Base URL** to `https://api.hairoute.ai/v1`
4. Save and select from the available models in the model list

### Claude Code

Claude Code supports two setup methods: configure a provider through CC Switch, or configure the Claude Code CLI directly with `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, and `ANTHROPIC_MODEL`.

For the complete screenshots and model-mapping steps, see [Claude Code via CC Switch](/docs/en/tools/claude-code).

### Open Code

1. Add hairoute directly from the OpenCode TUI:

Launch the OpenCode TUI
Type /connect
In the provider list, choose "Other" (custom endpoint)
Fill in:
Base URL: [https://api.hairoute.ai/v1](https://api.hairoute.ai/v1)
API Key: your hairoute API key
After saving, type /models and switch to the newly added model

2. Configure provider and base URL in the `opencode.json` file at your project root:

```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>
  For more AI tool integration guides, see the [AI tool integration](/docs/en/tools/claude-code) section.
</Tip>

## Next steps

* See the [API reference](/docs/en/api-reference/chat/openai-format) for complete endpoint parameters
* See [Model list](/docs/en/api-reference/models/list-models) for available models
* See [Rate limits](/docs/en/others/rate-limits) for API call limits