# 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-sonnet-4-6","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 и async jobs |
| POST | /v1/responses | OpenAI Responses-совместимый вход для chat-capable моделей |
| POST | /v1/embeddings | Векторные представления |
| POST | /v1/search | Serper Google search и Tavily search/extract/map/crawl/research |
| POST | /v1/images/generations | Генерация изображений; возвращает задачу |
| POST | /v1/files | Загрузка исходного изображения в private S3; возвращает временный image_url |
| POST | /v1/images/edits | Редактирование по HTTPS URL исходного изображения; возвращает задачу |
| POST | /v1/videos/generations | Генерация видео; возвращает задачу с результатом |
| GET | /v1/tasks/{id} | Состояние media-задачи |
| POST | /v1/tasks/{id}/cancel | Отмена media-задачи |
| GET | /v1/tasks/{id}/content | Редирект на готовый файл |
| GET | /v1/jobs/{id} | Состояние асинхронной chat-задачи |
| POST | /v1/jobs/{id}/cancel | Отмена асинхронной chat-задачи |

Не используйте /v1/audio/* и /v1/videos/edits в production: сейчас они отвечают 501 (reserved/not enabled). Для локального файла вызовите `POST /v1/files` с `multipart/form-data` и полем `file` (одно изображение до 10 MB), затем передайте возвращённый `image_url` в `POST /v1/images/edits`. Исходник и результат хранятся в private S3 не более 12 часов.

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

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

## Актуальные семейства моделей

- Claude: `claude-haiku-4-5`, `claude-sonnet-4-5`, `claude-sonnet-4-6`, `claude-sonnet-5`, `claude-opus-4-5`, `claude-opus-4-6`, `claude-opus-4-7`, `claude-fable-5`.
- GPT / Codex: `gpt-5-2`, `gpt-5-4`, `gpt-5-5`, `gpt-5-codex`, `gpt-5-1-codex`, `gpt-5-2-codex`, `gpt-5-3-codex`, `gpt-5-4-codex`, `gpt-5-6-luna`, `gpt-5-6-terra`, `gpt-5-6-sol`.
- Gemini: `gemini-2-5-flash`, `gemini-2-5-pro`, `gemini-3-1-flash-lite`, `gemini-3-1-pro`, `gemini-3-flash`, `gemini-3-5-flash`, `gemini-3-pro`, `gemini-3-6-flash`, `gemini-3-7-flash`.

## Gemini 3.7 Flash

`gemini-3-7-flash` is a verified OpenRouter route for chat and Responses workloads. It uses `balanced` routing by default; `cheap` still selects the lowest eligible provider cost. Current retail pricing is 58.5675 RUB / 1M input tokens and 292.8375 RUB / 1M output tokens.

```bash
curl https://crea-ai.ru/v1/chat/completions \
  -H "Authorization: Bearer $AI_HUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-3-7-flash","messages":[{"role":"user","content":"Give a concise release summary."}]}'
```
- Другие LLM: `qwen-3-6-flash`, `qwen-3-6-plus`, `qwen-3-6-27b`, `qwen-3-coder-plus`, `qwen-3-7-flash`, `qwen-3-7-max`, `glm-5-2`, `deepseek-v4-flash`, `deepseek-v4-flash-latest`, `deepseek-v4-pro`, `kimi-k3`, `kimi-k2-6`, `kimi-k2-7-code`, `minimax-m3`, `mimo-v2-5-pro`, `grok-4-5`.
- Image: `gpt-image-2`, `nano-banana-2`, `nano-banana-2-lite`, `grok-imagine`, `qwen-text-to-image`, `seedream`.
- Video: `gemini-omni-video`, `wan-2-7-text-to-video`, `wan-2-7-image-to-video`, `wan-2-7-videoedit`, `grok-imagine-video-1-5-preview`, `grok-imagine-image-to-video`, `grok-imagine-text-to-video`, `kling-3-0-video`, `happyhorse-1-1-image-to-video`, `happyhorse-1-1-text-to-video`, `happyhorse-1-1-reference-to-video`.

Получайте `GET /v1/models` перед первым вызовом: этот список отражает текущую доступность, capability и цену маршрута.

## Search: Serper и Tavily

`serper.model` использует `POST /v1/search` с полями `type` и `q`. `tavily.model` использует тот же endpoint с `operation: "search" | "extract" | "map" | "crawl" | "research`; обязательны соответственно `query`, `urls`, `url`, `url` или `input`. Параметры Tavily передаются upstream без изменений. Цена Tavily — 0.912 RUB за фактический API credit из ответа `usage.credits`; успешный gateway вызов остаётся одной billing-операцией. Не доступны account-scoped Tavily usage/logs/key endpoints.

## Grok 4.6

`grok-4-6` is a verified OpenRouter route for chat and Responses workloads. It has a 500K-token context window, uses `balanced` routing by default, and costs 312.36 RUB / 1M input tokens and 937.08 RUB / 1M output tokens at retail.

## GLM 5.3 and Qwen3.8 27B


`glm-5-3` is a verified OpenRouter route for chat and Responses with a 1M-token context window. Retail pricing is 218.652 RUB / 1M input tokens and 687.192 RUB / 1M output tokens.


`qwen-3-8-27b` is a verified OpenRouter multimodal chat and Responses route (text, image and video input). The live provider context limit is 262,144 tokens. Retail pricing is 62.472 RUB / 1M input tokens and 468.54 RUB / 1M output tokens.

```bash
curl https://crea-ai.ru/v1/chat/completions \
  -H "Authorization: Bearer $AI_HUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-3-8-27b","messages":[{"role":"user","content":"Summarize this request in one sentence."}]}'
```

## Chat Completions

## Function calling / tools

`POST /v1/chat/completions` accepts OpenAI-compatible `tools` and `tool_choice`. Use only a model whose `GET /v1/models` entry has capability `tools`: this is the authoritative per-model indication that function calling is available. crea-ai automatically selects a verified compatible execution route and can switch routes without changing the public model slug.

### Function-calling contract

1. Send a non-empty `tools` array. Every item has `type: "function"`, a function `name`, and an optional JSON Schema `parameters` object.
2. Set `tool_choice` to `"auto"`, `"none"`, `"required"`, or `{ "type": "function", "function": { "name": "..." } }`.
3. When the response has `finish_reason: "tool_calls"`, execute each call in your application. crea-ai never executes customer functions.
4. Send the original assistant message, followed by one `role: "tool"` message per call. Each tool result must use the corresponding `tool_call_id`.
5. The final model response is a normal assistant message. A tool call can have `content: null`.

Tools work in synchronous requests, SSE streaming, async jobs and webhook payloads. In SSE, calls arrive in `choices[].delta.tool_calls`. Invalid definitions, invalid assistant/tool history, or a model without capability `tools` return HTTP 400 with an OpenAI-style `invalid_request_error`; an unavailable compatible route uses code `tool_calling_unsupported`.

The API does not execute functions. When the assistant returns `message.tool_calls` and `finish_reason: "tool_calls"`, execute each function in your application, then make the next chat request with the prior assistant message plus `{ "role": "tool", "tool_call_id": "...", "content": "..." }`. Invalid tool definitions and unavailable tool-capable routes return a 400 OpenAI-style error (`tool_calling_unsupported`). SSE returns tool calls in `delta.tool_calls`.

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

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

### Асинхронные chat-задачи (jobs)

Если запрос длинный или передан `async: true`, API создаёт job и отвечает `202 Accepted`:

```json
{"id":"job_abc","object":"ai.job","status":"queued","status_url":"/v1/jobs/job_abc","expires_at":"2026-07-31T12:00:00Z"}
```

Поля для async-режима:
- `async: true` — принудительная постановка в очередь.
- `wait_timeout_ms` (0–30000) — бюджет ожидания для sync-режима; при превышении запрос переходит в очередь.
- `webhook_url` (HTTPS) — URL для уведомления о завершении job.
- `webhook_secret` (16–256 chars) — секрет для подписи webhook.

Статусы job: `queued`, `running`, `succeeded`, `failed`, `retry_scheduled`, `expired`. Опрашивайте `GET /v1/jobs/{id}` или отменяйте через `POST /v1/jobs/{id}/cancel`.

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

Передайте `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`.

### Изображения

`POST /v1/images/generations` выполняется синхронно: запрос блокируется до завершения генерации (до 10 минут). При успехе возвращает `201 Created` с `object: "task"`, `result_url` и `billing`. Поля: `model`, `prompt`, `size`, `n` (1–4), `response_format` и `routing`.

### Видео

`POST /v1/videos/generations` выполняется синхронно: запрос блокируется до завершения генерации (до 20 минут). При успехе возвращает `201 Created` с `object: "task"`, `result_url` и `billing`. Поля: `model`, `prompt`, `size`, `n` (1), `input_image_url` (для image-to-video) и `routing`. Видео сохраняется в S3 как MP4; retention 12 часов.

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

Ошибка имеет 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