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

# API Reference

> Поддержка протоколов OpenAI и Anthropic Claude — выбирайте удобный

RuAPI поддерживает **два API-протокола одновременно**: классический OpenAI-совместимый и нативный Anthropic Claude-совместимый. Один и тот же API ключ работает с обоими.

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

**Шпаргалка:**

|                       | OpenAI-совместимый             | Anthropic                          |
| --------------------- | ------------------------------ | ---------------------------------- |
| `base_url`            | `https://www.ruapi.ai/v1`      | `https://www.ruapi.ai` (без `/v1`) |
| Эндпоинт              | `POST /v1/chat/completions`    | `POST /v1/messages`                |
| Заголовок авторизации | `Authorization: Bearer sk-...` | `x-api-key: sk-...`                |

## Базовый URL

Адрес зависит от протокола — это главное, где можно ошибиться:

**OpenAI-совместимый** — с `/v1`:

```
https://www.ruapi.ai/v1
```

**Anthropic** — без `/v1` (SDK сам добавляет `/v1/messages`):

```
https://www.ruapi.ai
```

В таблицах эндпоинтов ниже пути указаны полностью — от корня домена. Аутентификация — через заголовок `Authorization: Bearer sk-...` (на `/v1/messages` подходит и `x-api-key`).

<Warning>
  Для Anthropic **не добавляйте** `/v1` в `base_url` — лишний `/v1` приведёт к ошибке **404**.
</Warning>

***

## Протокол OpenAI

Используйте этот протокол, если у вас уже есть код на официальном **OpenAI SDK** или совместимом фреймворке (LangChain, LlamaIndex, Vercel AI SDK и т. д.).

### Эндпоинт

```
POST https://www.ruapi.ai/v1/chat/completions
```

### Совместимость

Запрос/ответ совпадают с [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat). Поддерживаются:

* `messages` (с ролями `system` / `user` / `assistant` / `tool`)
* `model` — имя любой модели из каталога (включая Claude/Gemini/Grok/Qwen/MiniMax/GLM — мы конвертируем на лету)
* `stream: true` для streaming-ответов (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-ВАШ_КЛЮЧ",
    base_url="https://www.ruapi.ai/v1",
)

response = client.chat.completions.create(
    model="claude-opus-4-8",  # доступные модели — на www.ruapi.ai
    messages=[
        {"role": "system", "content": "Ты дружелюбный ассистент."},
        {"role": "user", "content": "Привет! Что ты умеешь?"},
    ],
    temperature=0.7,
)

print(response.choices[0].message.content)
print(f"Использовано токенов: {response.usage.total_tokens}")
```

### Пример: Node.js (OpenAI SDK)

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

const client = new OpenAI({
  apiKey: "sk-ВАШ_КЛЮЧ",
  baseURL: "https://www.ruapi.ai/v1",
});

const response = await client.chat.completions.create({
  model: "claude-opus-4-8", // можно вызывать Claude через протокол OpenAI; доступные модели — на www.ruapi.ai
  messages: [
    { role: "user", content: "Объясни квантовую запутанность простыми словами." },
  ],
});

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

### Пример: curl + streaming

```bash theme={null}
curl https://www.ruapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "Напиши хокку про код."}],
    "stream": true
  }'
```

***

## Протокол Claude

Используйте этот протокол, если ваш код написан под **Anthropic SDK** или вам нужны функции, специфичные для Claude (thinking-блоки, structured tool calls в нативном формате).

### Эндпоинт

```
POST https://www.ruapi.ai/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-ВАШ_КЛЮЧ",
    base_url="https://www.ruapi.ai",
)

response = client.messages.create(
    model="claude-opus-4-8",  # доступные модели — на www.ruapi.ai
    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-ВАШ_КЛЮЧ",
  baseURL: "https://www.ruapi.ai",
});

const response = await client.messages.create({
  model: "claude-opus-4-8", // доступные модели — на www.ruapi.ai
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Объясни принцип работы Rust borrow checker." },
  ],
});

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

### Пример: curl

```bash theme={null}
curl https://www.ruapi.ai/v1/messages \
  -H "x-api-key: sk-ВАШ_КЛЮЧ" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Напиши хокку про код."}]
  }'
```

<Note>
  Anthropic SDK ожидает заголовок `x-api-key` вместо `Authorization: Bearer`. RuAPI принимает оба варианта на эндпоинте `/v1/messages`.
</Note>

***

## Какой протокол выбрать

| Сценарий                                               | Используйте                           |
| ------------------------------------------------------ | ------------------------------------- |
| Вы уже на OpenAI SDK / LangChain / LlamaIndex          | **протокол OpenAI**                   |
| Вы пишете нативный Anthropic-код, нужны thinking-блоки | **протокол Claude**                   |
| Хотите вызвать Claude из существующего OpenAI-кода     | **протокол OpenAI** (мы конвертируем) |
| Хотите вызвать gpt-5.4 из Anthropic SDK                | **протокол Claude** (мы конвертируем) |

В любом случае — **один и тот же API ключ**, цена за токен не меняется, баланс общий.

## Список всех эндпоинтов

| Метод | Путь                       | Назначение                                |
| ----- | -------------------------- | ----------------------------------------- |
| POST  | `/v1/chat/completions`     | OpenAI Chat Completions                   |
| POST  | `/v1/messages`             | Claude Messages                           |
| POST  | `/v1/embeddings`           | Эмбеддинги (OpenAI совместимо)            |
| POST  | `/v1/images/generations`   | Генерация изображений (OpenAI совместимо) |
| POST  | `/v1/audio/transcriptions` | Транскрипция Whisper                      |
| POST  | `/v1/audio/speech`         | TTS — синтез речи                         |
| GET   | `/v1/models`               | Список доступных моделей                  |

Полный список с актуальными моделями — на странице **«Цены»** на [www.ruapi.ai](https://www.ruapi.ai).