# AI API Hub — документация для AI-агентов и разработчиков

> Публичная OpenAI-compatible API-платформа. Документ актуален для API v1.

## Канонические URL

- Документация: https://crea-ai.ru/docs
- Полная справка: https://crea-ai.ru/docs/api-reference
- Машиночитаемая OpenAPI-спецификация: https://crea-ai.ru/docs/openapi.json
- API base URL: https://crea-ai.ru/v1
- Каталог моделей: GET https://crea-ai.ru/v1/models

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

Все защищённые запросы используют заголовок `Authorization: Bearer $AI_HUB_API_KEY`.

```bash
curl https://crea-ai.ru/v1/chat/completions \
  -H "Authorization: Bearer $AI_HUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-best","messages":[{"role":"user","content":"Привет!"}]}'
```

## Рабочие endpoints

| Метод | Путь | Назначение |
| --- | --- | --- |
| GET | /v1/models | Модели, capabilities, публичные slugs и цены |
| GET | /v1/models/stats | Сводная статистика каталога |
| GET | /v1/models/{slug}/pricing | Тарификация одной модели |
| POST | /v1/chat/completions | Chat Completions, включая SSE stream |
| POST | /v1/responses | OpenAI Responses-совместимый вход для chat-capable моделей |
| POST | /v1/embeddings | Векторные представления |
| POST | /v1/images/generations | Генерация изображений; возвращает задачу |
| POST | /v1/videos/generations | Создание video-задачи; асинхронно |
| GET | /v1/tasks/{id} | Состояние media-задачи |
| POST | /v1/tasks/{id}/cancel | Отмена media-задачи |
| GET | /v1/tasks/{id}/content | Редирект на готовый файл |

Не используйте /v1/files, /v1/audio/*, /v1/images/edits и /v1/videos/edits в production: сейчас они отвечают 501 (reserved/not enabled).

## Совместимость и выбор модели

API совместим с OpenAI SDK: задайте `baseURL: "https://crea-ai.ru/v1"`. Всегда используйте public model slug из `GET /v1/models`, а не ID апстрим-провайдера. Для чата подходят модели с capability `chat`; для embeddings — `embeddings`; изображения и видео выбирайте по `image`/`video`.

## Chat Completions

Обязательные поля: `model`, `messages[]`. Поддерживаются роли `system`, `user`, `assistant`, `tool`; `content` можно передавать в OpenAI-совместимом формате. Дополнительные поля: `temperature` (0–2), `stream` и `routing`.

При `stream: true` ответ — Server-Sent Events; завершение обозначается `data: [DONE]`.

## Маршрутизация, лимиты и идемпотентность

Передайте `routing` в JSON или заголовки:

- `X-Routing-Mode`: `balanced` (default), `cheap`, `fast`, `stable` или `fixed`.
- `X-Provider`: фиксирует поддерживаемого провайдера, когда политика ключа это разрешает.
- `X-Max-Cost-RUB`: максимально допустимая стоимость операции в рублях.
- `Idempotency-Key`: уникальный ключ логической операции. Обязателен для безопасных повторов при timeout/сбоях сети.
- `X-Request-ID`: можно передать свой корреляционный ID; сервер возвращает его в ответе.

Ответы с успешным списанием содержат `billing` (currency, charged, request_id, price_version_id). Не повторяйте запрос с новым idempotency key, пока не проверите результат исходного.

## Asynchronous media workflow

1. POST /v1/images/generations или /v1/videos/generations.
2. Сохраните `task.id`.
3. Опросите GET /v1/tasks/{id} с экспоненциальной паузой.
4. При `status: "succeeded"` скачайте `result_url` либо GET /v1/tasks/{id}/content с редиректами.
5. Результаты хранятся ограниченное время; поле `retention_expires_at` — источник истины.

Статусы задачи: `queued`, `running`, `succeeded`, `failed`, `cancelled`.

## Ошибки и повторы

Ошибка имеет envelope `error.message`, `error.type`, `error.code`, `error.request_id`, `error.retryable`. Повторять с тем же Idempotency-Key допустимо только ошибки с `retryable: true` (например 429, временная недоступность провайдера, 5xx). Для 400, 401, 404 и 501 исправьте запрос вместо retry.

## Рекомендации для автономных AI-агентов

1. До первого вызова и при ошибке `model_not_found` обновляйте GET /v1/models.
2. Привязывайте каждый task/request к своему Idempotency-Key и сохраняйте request_id.
3. Устанавливайте X-Max-Cost-RUB для ограниченного бюджета и выбирайте routing.mode осознанно.
4. Не включайте API-ключи в prompts, репозитории, логи или сообщения инструментов.
5. Обрабатывайте SSE построчно, а media-задачи — через polling; webhooks публичным API v1 пока не предоставляет.

Полные JSON-примеры, SDK-конфигурации, схемы и таблица полей: https://crea-ai.ru/docs/api-reference