Public API v1

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

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

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.

tools / tool_choiceFunction calling для моделей с capability tools. Gateway возвращает tool_calls; инструмент выполняет ваш клиент и отправляет результат следующим сообщением role=tool. Несовместимый маршрут автоматически заменяется совместимым.
streamtrue включает Server-Sent Events. Обрабатывайте события до [DONE].
routingmode, provider, max_cost_rub и data_retention; заголовки имеют приоритет.
billingУспешный ответ включает стоимость, request_id и версию тарифа.
asynctrue принудительно ставит запрос в очередь; ответ 202 с object: "ai.job" и status_url.
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-sonnet-4-6","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-5-4-codex", stream: true,
  messages: [{ role: "user", content: "Explain this diff" }]
});
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
ExampleFunction calling: two turns
const first = await client.chat.completions.create({
  model: "gpt-coding",
  messages: [{ role: "user", content: "Какая погода во Владивостоке?" }],
  tools: [{ type: "function", function: { name: "get_weather", description: "Current weather", parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] } } }],
  tool_choice: "auto"
});
// Execute first.choices[0].message.tool_calls locally, then send its result:
const final = await client.chat.completions.create({ model: "gpt-coding", messages: [
  { role: "user", content: "Какая погода во Владивостоке?" }, first.choices[0].message,
  { role: "tool", tool_call_id: first.choices[0].message.tool_calls[0].id, content: '{"temperature":18}' }
] });
Function calling

Инструменты для agent loop

Выбирайте модель, у которой GET /v1/models содержит capability tools. Это свойство публикуется для каждой модели отдельно и означает, что crea-ai подтвердил её совместимость с function calling.

1. Опишите функции

Передайте tools с JSON Schema параметров. Используйте tool_choice: "auto" для выбора моделью, "required" для обязательного вызова или объект с именем функции для точного выбора.

2. Выполните вызов

Ответ с finish_reason: "tool_calls" содержит message.tool_calls. Функцию выполняет ваше приложение, а не API. У assistant message может быть content: null.

3. Верните результат

Отправьте исходное assistant message и сообщение role: "tool" с тем же tool_call_id. Для SSE читайте delta.tool_calls; async jobs и webhooks сохраняют те же поля.

Проверка входаНекорректный tool, tool_choice, tool_call_id или история assistant tool_calls возвращают HTTP 400 invalid_request_error.
Нет совместимой моделиHTTP 400 с code tool_calling_unsupported. Запрос не отправляется во внешнюю инфраструктуру.
Маршрутизацияcrea-ai автоматически использует совместимый и экономичный маршрут; публичный slug модели и контракт API не меняются.
Актуальные модели

Выбирайте канонический slug из каталога

Каталог обновляется вместе с доступными маршрутами. Не используйте внутренние ID провайдеров или устаревшие агрегирующие slug. Для tools выбирайте только модели, у которых capabilities.includes("tools"): это означает, что в данный момент есть проверенный совместимый маршрут.

Для изображений используйте gpt-image-2, nano-banana-2, nano-banana-2-lite, grok-imagine, qwen-text-to-image или seedream. Для embeddings — модели с capability embeddings. Endpoint GET /v1/models — единственный источник доступных на текущий момент slug и цен.

ExampleПолучение модели из live-каталога
const catalog = await fetch("https://crea-ai.ru/v1/models").then((response) => response.json());

const model = catalog.data.find((item) =>
  item.id === "gemini-3-7-flash" && item.capabilities.includes("chat")
);

const completion = await client.chat.completions.create({
  model: model.id,
  messages: [{ role: "user", 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"}'
Search

POST /v1/search

serper.model возвращает Google web/news/images/maps и другие типы поиска. Обязательны model, type и q; цена успешного Serper-вызова — 0,30 ₽.

tavily.model поддерживает search, extract, map, crawl и research. Для них укажите operation и соответствующее поле query, urls, url или input. Документированные параметры Tavily передаются без изменений. Цена — 0,912 ₽ за фактический credit; один вызов отображается одной операцией billing.

ExampleSerper news search
curl https://crea-ai.ru/v1/search \
  -H "Authorization: Bearer $AI_HUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: search-001" \
  -d '{"model":"serper.model","type":"news","q":"AI news","gl":"ru","hl":"ru","location":"Moscow, Russia"}'
ExampleTavily advanced search
curl https://crea-ai.ru/v1/search \
  -H "Authorization: Bearer $AI_HUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tavily-001" \
  -d '{"model":"tavily.model","operation":"search","query":"AI news","search_depth":"advanced","max_results":5}'
Media tasks

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

Создание медиа выполняется синхронно: запрос блокируется до завершения генерации (до 10 мин для image, до 20 мин для video). При успехе возвращает 201 Created с object: "task", result_url и billing. Сохраните task.id для повторной проверки через GET /tasks/{id}.

Exampleimage generation task
POST /v1/images/generations
{"model":"gpt-image-2","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 /files

multipart/form-data, поле file: одно изображение до 10 MB. Ответ содержит временный private-S3 image_url; исходник хранится не более 12 часов.

POST /images/edits

model, prompt и HTTPS image_url. Передайте URL из /files или публичный URL; результат возвращается как task.

POST /images/generations

model, prompt, size, n (1–4), response_format и routing. Возвращает task с result_url.

POST /videos/generations

model, prompt, size, n (1), input_image_url (для image-to-video) и routing. Возвращает task с result_url (MP4). До 20 мин.

GET /tasks/{id}

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

Image edit flowPOST /files → получите image_url → POST /images/edits. Cleanup worker удаляет весь S3-префикс задачи по истечении 12 часов.
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.
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.
Async jobs

Длинные chat-запросы через очередь

POST /chat/completions с async

Передайте async: true или wait_timeout_ms. Ответ 202 с object: "ai.job", status_url и expires_at.

GET /jobs/{id}

Статусы: queued, running, succeeded, failed, retry_scheduled, expired.

POST /jobs/{id}/cancel

Отмена job. Webhook-уведомление отправляется при указании webhook_url (HTTPS) и webhook_secret.

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. Для длинных chat-запросов используйте async: true + GET /v1/jobs/{id}.
  5. Для локального image edit загрузите файл через POST /v1/files, затем передайте его image_url в POST /v1/images/edits.
  6. Media (image/video) выполняется синхронно: запрос блокируется до завершения. Сохраняйте task.id и проверяйте через GET /v1/tasks/{id}.
  7. Audio и video edit endpoints пока зарезервированы.