---
name: kosareva-api
description: Подключает проект к API kosareva.cloud — OpenAI- и Anthropic-совместимому шлюзу к Claude, GPT, Gemini, DeepSeek, Qwen, моделям Яндекса и другим с оплатой в рублях. Использовать, когда нужно перевести код с OpenAI SDK, Anthropic SDK, LangChain, Vercel AI SDK или cURL на kosareva.cloud, выбрать модель под задачу, настроить Claude Code или Codex CLI, добавить картинки, видео (/v1/videos), озвучку, распознавание речи (/v1/audio/transcriptions), эмбеддинги, или разобрать ошибки 401, 402, 404, 429, 504 от api.kosareva.cloud. Триггеры — «подключи kosareva», «kosareva.cloud API», «KOSAREVA_API_KEY», «переведи на kosareva», «base_url kosareva».
---

# Подключение проекта к API kosareva.cloud

kosareva.cloud — один API-ключ ко всем моделям каталога. Пути и форматы как у OpenAI,
поэтому подходят официальные SDK: в существующем коде меняются ключ, адрес и имя модели.
Модели Claude доступны ещё и в формате Anthropic (Messages API).

## Пять правил, которые нельзя нарушать

1. **Ключ — только из переменной окружения `KOSAREVA_API_KEY`.** Не вписывать в код,
   конфиги под git, логи и вывод в терминал. В `.env.example` — пустое значение,
   `.env` должен быть в `.gitignore` (проверь и допиши, если нет).
2. **Адрес зависит от SDK** — это главный источник ошибки 404:
   - OpenAI SDK и всё OpenAI-совместимое (LangChain, LlamaIndex, n8n, cURL):
     `https://api.kosareva.cloud/v1`
   - Anthropic SDK и Claude Code: `https://api.kosareva.cloud` — **без `/v1`**,
     путь `/v1/messages` SDK допишет сам. С `/v1` получится `/v1/v1/messages` и 404.
   - `https://kosareva.cloud/api/v1/…` — это API личного кабинета (баланс, ключи,
     счета), а не модели.
3. **Имя модели — как в каталоге:** латиница через дефисы — `claude-sonnet-5-5`,
   `gpt-5-6`. Без префикса вендора (`anthropic/…`), без даты версии. Точный список —
   `GET /v1/models`.
4. **Любой запрос к модели списывает деньги с баланса пользователя.** Не запускай
   платные проверки, тесты в цикле, генерацию картинок и видео без явного «да».
   Формулировка: «нужен один живой запрос к <модель>, около N копеек», где N =
   (токены входа × цена входа + max_tokens × цена выхода) / 1 000 000 по ценам из
   `references/models.md` или карточки модели. Бесплатно:
   `GET /v1/models` и `GET https://kosareva.cloud/api/v1/balance` — их и делает
   `scripts/check_connection.py`.
5. **Персональные данные в промптах** (ФИО, телефоны, ИНН, реквизиты) — предложи
   API Guard: `https://api.kosareva.cloud/guard/v1` для OpenAI SDK,
   `https://api.kosareva.cloud/guard` для Anthropic SDK. Данные заменяются заглушками
   до отправки в модель и возвращаются на место в ответе. ФИО Guard находит только
   с отчеством или инициалами, адреса и названия компаний не маскирует — скажи об этом.

## Порядок работы

1. **Осмотри проект.** Язык и SDK (`openai`, `anthropic`, `langchain-openai`,
   `@ai-sdk/*`, `llama-index`), где создаётся клиент, откуда берутся ключ и адрес
   (env, конфиг, хардкод), какие модели вписаны, есть ли стриминг, инструменты
   (tools), JSON-режим.
2. **Выбери формат.** По умолчанию — OpenAI-совместимый: работает со всеми моделями.
   Anthropic-формат оставляй, только если код уже на Anthropic SDK; через него
   доступны лишь модели Claude. Responses API (`/v1/responses`) — только модели OpenAI.
3. **Внеси минимальную правку:** ключ из `KOSAREVA_API_KEY`, адрес, имя модели.
   Логику, промпты и обработку ответов не переписывай.
4. **Подбери модель** по `references/models.md`. Если задача неясна — спроси одной
   фразой: «что важнее — качество, скорость или цена?».
5. **Задокументируй:** строка в `.env.example`, пара строк в README — откуда взять
   ключ (kosareva.cloud/panel/ → «API-ключи»).
6. **Проверь бесплатно:**
   `python3 scripts/check_connection.py --model <модель>` (в Windows — `python`).
   Скрипт лежит в папке этого скилла; в Claude Code путь к ней — `${CLAUDE_SKILL_DIR}`.
   Он проверяет, что ключ виден, адрес отвечает и модель есть в списке, и показывает
   остаток баланса. Запросов к моделям не делает.
7. **Один платный запрос — только после подтверждения** пользователя, с `max_tokens`
   не больше 50: на большинстве текстовых моделей это копейки.

## Готовые правки

Python, OpenAI SDK:

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KOSAREVA_API_KEY"],
    base_url="https://api.kosareva.cloud/v1",
)
resp = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[{"role": "user", "content": "Привет!"}],
)
print(resp.choices[0].message.content)
```

Node.js, OpenAI SDK:

```js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KOSAREVA_API_KEY,
  baseURL: "https://api.kosareva.cloud/v1",
});
```

Python, Anthropic SDK (только модели Claude):

```python
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["KOSAREVA_API_KEY"],
    base_url="https://api.kosareva.cloud",  # без /v1
)
```

Если код берёт настройки только из окружения, менять его не нужно: OpenAI SDK читает
`OPENAI_API_KEY` и `OPENAI_BASE_URL`, Anthropic SDK — `ANTHROPIC_API_KEY` и
`ANTHROPIC_BASE_URL`. Тогда правка — в `.env`, а модель — там, где она задана.

LangChain, Vercel AI SDK, cURL, эмбеддинги, картинки, озвучка, распознавание речи,
видео, API кабинета и разбор ошибок — в `references/endpoints.md`.

## Агенты на ключе kosareva.cloud

Claude Code — три переменные окружения:

```bash
export ANTHROPIC_BASE_URL="https://api.kosareva.cloud"   # без /v1
export ANTHROPIC_AUTH_TOKEN="$KOSAREVA_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-5-5"
```

В PowerShell: `$env:ANTHROPIC_BASE_URL = "https://api.kosareva.cloud"` и так далее.

Codex CLI — провайдер в `~/.codex/config.toml`, ключ из окружения:

```toml
model = "gpt-5-6"
model_provider = "kosareva"

[model_providers.kosareva]
name = "kosareva.cloud"
base_url = "https://api.kosareva.cloud/v1"
env_key = "KOSAREVA_API_KEY"
wire_api = "responses"
```

## Частые ошибки

| Код | Что значит | Что делать |
|---|---|---|
| 401 | Ключ не найден или не принят | Скопирован не целиком, с пробелом, удалён в кабинете или передан не в том заголовке. Нужен `Authorization: Bearer …` (в формате Anthropic подходит и `x-api-key`). Ключ OpenAI или Anthropic не подходит |
| 402 | Закончились средства | Пополнить баланс в кабинете (карта или СБП от 50 ₽). Если деньги есть — проверить лимит ключа в рублях |
| 404 | Адрес без `/v1` или с лишним хвостом | Для OpenAI SDK ровно `…/v1`, для Anthropic SDK — без `/v1` |
| 400 «Такой модели нет в каталоге» | Неверное имя | Латиница через дефисы, без `anthropic/…`; список — `GET /v1/models` |
| 400 «не помещается в контекст» | История плюс `max_tokens` больше окна модели | Уменьшить `max_tokens` или сжать историю |
| 429 | Слишком много запросов подряд | Повтор с растущей паузой; при постоянной нагрузке — написать в поддержку |
| 504 | Модель не начала отвечать вовремя | Повторить, включить `stream: true`. Такой запрос не списывается |

Запрос, который закончился ошибкой, не списывается. Ошибки приходят в формате OpenAI,
объяснение по-русски — в `error.message`.

## Чего этот скилл не делает

- Не создаёт ключ и не пополняет баланс — это только в кабинете kosareva.cloud/panel/.
- Не гарантирует, что модель поддерживает нужный параметр (tools, JSON-режим,
  картинки на входе): смотри карточку модели на kosareva.cloud/prices/.
- Не переводит сам Cursor на ключ kosareva.cloud: с сентября 2026 облако Cursor закрыто
  для России, и свой ключ возвращает только чат. Подключить API к проекту, открытому
  в Cursor, скилл может — как и в любом другом редакторе.