Документация/API Reference
Public API v1

Полная справка API и интеграций

Единый OpenAI-compatible API для текста, embeddings и медиа. Эта страница описывает контракт для человека и автономного AI-агента в production.

llms.txt (Markdown)OpenAPI 3.1 JSON
Start here

Базовые правила

Base URL

https://crea-ai.ru/v1. Передавайте public model slug из GET /models, а не внутренний ID провайдера.

Авторизация

Все вызовы кроме чтения каталога требуют Authorization: Bearer <API_KEY>. Храните ключ в переменной окружения.

Надёжные повторы

Для оплачиваемых операций используйте уникальный Idempotency-Key и повторяйте запрос только с тем же ключом.

Chat completions

POST /v1/chat/completions

Основной endpoint для диалога и agent loop. Обязательны model и messages. Роли: system, user, assistant, tool. temperature: 0–2.

streamtrue включает Server-Sent Events. Обрабатывайте события до [DONE].
routingmode, provider, max_cost_rub и data_retention; заголовки имеют приоритет.
billingУспешный ответ включает стоимость, request_id и версию тарифа.
ExamplecURL chat completion
curl https://crea-ai.ru/v1/chat/completions \
  -H "Authorization: Bearer $AI_HUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agent-turn-001" \
  -H "X-Routing-Mode: stable" \
  -H "X-Max-Cost-RUB: 10" \
  -d '{"model":"claude-best","messages":[{"role":"system","content":"Отвечай кратко."},{"role":"user","content":"Составь план релиза."}],"temperature":0.2}'
ExampleNode.js + OpenAI SDK streaming
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.AI_HUB_API_KEY, baseURL: "https://crea-ai.ru/v1" });
const stream = await client.chat.completions.create({
  model: "gpt-coding", stream: true,
  messages: [{ role: "user", content: "Explain this diff" }]
});
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
Embeddings and responses

Семантический поиск и Responses API

POST /v1/embeddings принимает строку, массив строк или токены. Используйте модель с capability embeddings; доступны dimensions, encoding_format (float/base64) и user.

POST /v1/responses — OpenAI Responses-совместимый вход для моделей с capability responses. Для привычного сообщения и streaming выбирайте chat/completions.

Examplebatch embeddings
curl https://crea-ai.ru/v1/embeddings \
  -H "Authorization: Bearer $AI_HUB_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: index-doc-42" \
  -d '{"model":"embedding-text-3-small","input":["Документ о продукте","Инструкция для агента"],"encoding_format":"float"}'
Media tasks

Изображения и видео: асинхронный цикл

Создание медиа возвращает task. Сохраните task.id, опрашивайте состояние с backoff и скачивайте результат после succeeded.

Exampleimage generation task
POST /v1/images/generations
{"model":"image-best","prompt":"Minimalist editorial cover about AI agents","size":"1024x1024","n":1,"routing":{"mode":"stable","max_cost_rub":"25"}}

201 Created
{"object":"task","id":"task_123","status":"succeeded","result_url":"https://crea-ai.ru/v1/tasks/task_123/content","retention_expires_at":"2026-07-18T10:00:00.000Z"}

POST /images/generations

model, prompt, size, n (1–4), response_format и routing. Создаёт task.

POST /videos/generations

Создаёт video task и отвечает 202. Планируйте polling.

GET /tasks/{id}

queued, running, succeeded, failed, cancelled. GET /content вернёт 307 на файл; учитывайте retention_expires_at.

Routing & operations

Контроль цены, скорости и трассировки

X-Routing-Modebalanced (по умолчанию), cheap, fast, stable или fixed.
X-ProviderЗапрашивает поддерживаемого провайдера при разрешении политикой ключа.
X-Max-Cost-RUBВерхняя граница стоимости операции в рублях. Рекомендуется для агентов.
X-Request-IDВаш ID корреляции; сервер возвращает его в ответе. Сохраняйте request_id из ошибки или billing.
Rate limitПри 429 читайте Retry-After и делайте backoff с тем же Idempotency-Key.
Errors

Предсказуемая обработка ошибок

Ошибка содержит message, type, code, request_id и retryable. Повторяйте только retryable: true. Для 400 исправьте тело, 401 — ключ, 404 — slug/task ID; reserved endpoints вернут 501.

Exampleretryable error
{"error":{"message":"Rate limit exceeded.","type":"rate_limit_error","code":"rate_limit_exceeded","request_id":"req_abc123","retryable":true}}
Agent checklist

Инструкция для AI-агентов

  1. До первого вызова и при model_not_found обновляйте GET /v1/models.
  2. Сохраняйте Idempotency-Key и не создавайте новый ключ для сетевого повтора.
  3. Указывайте X-Max-Cost-RUB при ограниченном бюджете и сохраняйте billing.request_id.
  4. Обрабатывайте streaming через SSE, media — polling. Публичных webhook endpoint’ов в API v1 нет.
  5. Не считайте audio/files/edit endpoints рабочими до явной публикации: сейчас они зарезервированы.