# Быстрый старт с API

> Подключение к ИИ-шлюзу OpenCheese: хост API и базовые URL, аутентификация Bearer и x-api-key, первый запрос curl и документация по API и инструментам.
>
> Веб-страница: https://opencheese.dev/ru/docs/ · Все страницы документации: https://opencheese.dev/ru/docs.md

OpenCheese AI — это ИИ-шлюз с API, совместимыми с OpenAI и Anthropic. Один API-ключ OpenCheese
открывает доступ ко всем моделям, включённым для вашего аккаунта, в том числе к бесплатным, а
каждый запрос записывается в панели вместе с расходом токенов и стоимостью.

Каждая страница этой документации доступна и в формате Markdown: добавьте `.md` к её адресу,
например [/ru/docs.md](https://opencheese.dev/ru/docs.md) для этой страницы.

## 1. Создайте API-ключ

Войдите на [opencheese.dev](https://opencheese.dev/ru/), откройте **API-ключи** и создайте ключ.
Храните его на сервере: никогда не встраивайте привилегированный ключ в публичный код фронтенда.

## 2. Хост API и базовые URL

Шлюз работает на `https://api.opencheese.dev` — это другой хост, не тот, где находится сайт.
Запросы к `opencheese.dev` вернут сайт, а не ответ API.

| Клиент | Базовый URL |
| --- | --- |
| SDK OpenAI и OpenAI-совместимые клиенты (OpenCode, Codex, Harness AI, Zed, Chatbox, RikkaHub) | `https://api.opencheese.dev/v1` |
| SDK Anthropic и Anthropic-совместимые клиенты (Claude Code, Claude Desktop) | `https://api.opencheese.dev` |

SDK Anthropic сами добавляют `/v1/messages`, поэтому их базовый URL не должен заканчиваться на
`/v1`. Некоторые приложения даже в режиме Anthropic просят адрес до `/v1` включительно; в
руководстве по каждому приложению ниже сказано, какой вариант ему нужен.

## 3. Аутентификация

Передавайте ключ как Bearer-токен:

```text
Authorization: Bearer YOUR_OPENCHEESE_API_KEY
```

Клиенты, работающие в формате Anthropic, могут вместо этого передавать его как
`x-api-key: YOUR_OPENCHEESE_API_KEY`.

В примерах ключ берётся из переменной `OPENCHEESE_API_KEY`. В ключе есть символы `$`, поэтому
задавайте переменную в одинарных кавычках: они оставляют эти символы как есть (в двойных кавычках
оболочка раскрыла бы их и испортила ключ):

```bash
export OPENCHEESE_API_KEY='YOUR_OPENCHEESE_API_KEY'
```

В PowerShell: `$env:OPENCHEESE_API_KEY = 'YOUR_OPENCHEESE_API_KEY'`.

## 4. Получите список моделей, доступных ключу

```bash
curl https://api.opencheese.dev/v1/models \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

Используйте `id` из этого списка. Доступ зависит от вашего тарифа и ограничений ключа по моделям,
поэтому не копируйте ID моделей из старых примеров. Все поля описаны на странице
[API моделей](https://opencheese.dev/ru/docs/models.md).

## 5. Отправьте первый запрос

OpenAI Chat Completions:

```bash
curl https://api.opencheese.dev/v1/chat/completions \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "messages": [{"role": "user", "content": "Hello"}]}'
```

Anthropic Messages:

```bash
curl https://api.opencheese.dev/v1/messages \
  -H "x-api-key: $OPENCHEESE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'
```

Через OpenAI Python SDK:

```python
from openai import OpenAI

client = OpenAI(base_url="https://api.opencheese.dev/v1", api_key="YOUR_OPENCHEESE_API_KEY")
reply = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "Hello"}],
)
print(reply.choices[0].message.content)
```

## 6. Объединяйте разговор в одну сессию

Передавайте один и тот же заголовок `opencheese-session-uuid` в каждом запросе одного разговора —
тогда панель покажет его как одну сессию. Запрос без этого заголовка образует отдельную сессию.
Когда его передавать, описано на странице [Сессии](https://opencheese.dev/ru/docs/sessions.md).

## Эндпоинты

| Эндпоинт | Протокол | Назначение |
| --- | --- | --- |
| `GET /v1/models` | OpenAI | [Модели, доступные ключу](https://opencheese.dev/ru/docs/models.md) |
| `POST /v1/chat/completions` | OpenAI | [Чат, потоковые ответы и инструменты](https://opencheese.dev/ru/docs/chat-completions.md) |
| `POST /v1/responses` | OpenAI Responses | [Клиенты Responses, например Codex](https://opencheese.dev/ru/docs/responses.md) |
| `POST /v1/messages` | Anthropic | [Claude Code и SDK Anthropic](https://opencheese.dev/ru/docs/messages.md) |
| `POST /v1/messages/count_tokens` | Anthropic | [Подсчёт токенов без оплаты](https://opencheese.dev/ru/docs/messages.md) |
| `POST /v1/images/generations` | OpenAI Images | [Генерация изображений](https://opencheese.dev/ru/docs/images.md) |
| `POST /v1/images/edits` | OpenAI Images (multipart) | [Редактирование изображений](https://opencheese.dev/ru/docs/images.md) |
| `GET /v1/images/capabilities` | OpenCheese | [Параметры моделей изображений](https://opencheese.dev/ru/docs/images.md) |
| `GET /v1/key` | OpenCheese | [Лимит расходов ключа и сколько уже потрачено](https://opencheese.dev/ru/docs/account.md) |
| `GET /v1/plan` | OpenCheese | [Окна тарифа и настройки оплаты с баланса](https://opencheese.dev/ru/docs/account.md) |
| `GET /v1/balance` | OpenCheese | [Баланс и расход за текущий месяц](https://opencheese.dev/ru/docs/account.md) |

Возможности — потоковые ответы, инструменты, изображения на входе, уровни рассуждений — зависят
от модели: прежде чем на них полагаться, проверьте модель в `/v1/models`.

## Все страницы

### Начало работы

- [Сессии](https://opencheese.dev/ru/docs/sessions.md): Один разговор — одна сессия: заголовок opencheese-session-uuid.

### Справочник API

- [Модели](https://opencheese.dev/ru/docs/models.md): GET /v1/models и значение каждого поля.
- [Chat Completions](https://opencheese.dev/ru/docs/chat-completions.md): POST /v1/chat/completions: потоковый ответ, инструменты, изображения, уровень рассуждений.
- [Responses](https://opencheese.dev/ru/docs/responses.md): POST /v1/responses: input, события потока, инструменты.
- [Messages](https://opencheese.dev/ru/docs/messages.md): POST /v1/messages и /v1/messages/count_tokens.
- [Изображения](https://opencheese.dev/ru/docs/images.md): Генерация и редактирование изображений через OpenAI Images API.
- [Ключ, тариф и баланс](https://opencheese.dev/ru/docs/account.md): GET /v1/key, /v1/plan и /v1/balance.
- [Ошибки и лимиты](https://opencheese.dev/ru/docs/errors.md): Формат ошибок, коды, лимиты запросов и повторные попытки.

### Инструменты разработки

- [Claude Code](https://opencheese.dev/ru/docs/claude-code.md): ANTHROPIC_BASE_URL, API-ключ и псевдонимы моделей в settings.json.
- [Claude Desktop](https://opencheese.dev/ru/docs/claude-desktop.md): Режим стороннего инференса с импортированным файлом конфигурации.
- [Codex](https://opencheese.dev/ru/docs/codex.md): Провайдер модели в config.toml на Responses API.
- [OpenCode](https://opencheese.dev/ru/docs/opencode.md): Автосинхронизация или OpenAI-совместимый провайдер в opencode.json.
- [Harness AI](https://opencheese.dev/ru/docs/harness-ai.md): Пользовательский провайдер и уровни рассуждений в settings.yaml.
- [Zed](https://opencheese.dev/ru/docs/zed.md): Провайдер openai_compatible в settings.json.
- [VS Code и JetBrains](https://opencheese.dev/ru/docs/ide.md): Расширения Claude Code и Codex на настройках CLI.

### Чат-приложения

- [RikkaHub](https://opencheese.dev/ru/docs/rikkahub.md): Провайдер OpenAI или Claude в Android-приложении.
- [Chatbox](https://opencheese.dev/ru/docs/chatbox.md): Провайдер, совместимый с OpenAI API, на телефоне или компьютере.
- [LobeHub](https://opencheese.dev/ru/docs/lobehub.md): Запись провайдера с правильным адресом для каждого формата.

## Ошибки

Большинство ошибок возвращается как HTTP-статус с телом ошибки в JSON. На `/v1/chat/completions`
проблемы, которые требуют ваших действий (недействительный ключ, лимит тарифа, пустой баланс),
приходят в виде ответа ассистента, чтобы чат-приложения показали вам сообщение. Все коды
перечислены на странице [Ошибки и лимиты запросов](https://opencheese.dev/ru/docs/errors.md).

## Тарифы и цены

Тарифы перечислены на [главной странице](https://opencheese.dev/ru/#pricing). Цены на каждую
модель указаны на странице **Цены** в панели после входа.

## Дополнительная помощь

- [FAQ](https://opencheese.dev/ru/faq/): настройка, модели, тарифы, платежи и решение проблем.
- Чат поддержки в панели или почта service@opencheese.dev.