Подключение занимает пару минут

ApiraCloud поддерживает формат Chat Completions. В большинстве OpenAI-совместимых библиотек достаточно заменить адрес API и ключ.

Base URL этого сервера: . API-ключ берётся в кабинете → API-ключи.

Первый запрос

curl https://apiracloud.ru/v1/chat/completions \
  -H "Authorization: Bearer mg_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8472-summary" \
  -d '{
    "model": "apiracloud/free",
    "messages": [{"role":"user","content":"Привет!"}],
    "max_tokens": 800
  }'

Авторизация

Ключ передается только в заголовке Authorization: Bearer. Полный ключ показывается один раз при создании; храните его как пароль.

Бесплатные модели

Модели с суффиксом :free и роутер apiracloud/free не списывают рубли за токены. На одного клиента действует общий лимит 25 запросов в сутки и 10 запросов за скользящий час по всем API-ключам. Суточный счетчик обновляется в 00:00 UTC. При исчерпании лимита API вернет 429 FREE_DAILY_LIMIT_EXCEEDED или 429 FREE_HOURLY_LIMIT_EXCEEDED.

Бесплатные маршруты подходят для тестов и небольших задач. Их доступность и задержка могут меняться; конкретную модель выбирайте по ID, а apiracloud/free используйте для автоматического выбора доступного бесплатного маршрута.

Потоковые ответы

Передайте "stream": true. Читайте SSE-события data: {JSON}, текст находится в choices[].delta.content; завершение — data: [DONE]. Сетевой чанк может содержать часть события: нужен буфер. Usage приходит в конце. Если расход не получен, запрос остаётся usage_pending с удержанным резервом.

ID задания

Каждый ответ содержит X-Request-Id. По нему можно найти токены, стоимость, задержку и состояние расчета в кабинете.

Для медиа дополнительно проверяйте X-ApiraCloud-Billing-Status. Значение usage_pending означает, что файл уже получен, но поставщик ещё не подтвердил финальную стоимость. Не повторяйте такой запрос: итоговое списание появится в кабинете после автоматической сверки.

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

Ошибки возвращаются как {"error":{"code":"…","message":"…","request_id":"…"}}. До создания запроса ID может отсутствовать. Повтор с тем же Idempotency-Key и телом возвращает 202 со статусом уже существующего задания. Исходный ответ не воспроизводится. Изменённое тело с прежним ключом — 409.

• 400 — параметры или контекст; 401 — ключ; 402 — недостаточно баланса.
• 403 — запрет доступа; 404 — модель не найдена; 413 — слишком большое тело.
• 429 — RPM/TPM или бюджет; 502/503/504 — поставщик, маршрут или таймаут.

Каталог и поддерживаемые операции

GET /v1/models доступен без ключа. Берите идентификатор модели из поля id. Цены текстовых моделей указаны в ₽ за миллион токенов. apiracloud/free автоматически выбирает доступный бесплатный маршрут в пределах общего дневного лимита клиента.

Для доступных моделей поддерживаются текстовые запросы POST /v1/chat/completions, изображения POST /v1/images, озвучка POST /v1/audio/speech, распознавание POST /v1/audio/transcriptions, аудиодиалог POST /v1/audio/generations, анализ медиа POST /v1/media/understand и видео POST /v1/videos. Доступность конкретной операции зависит от модели и её настроенного тарифа; в каталоге нажмите «Подключить по API», чтобы увидеть подходящий маршрут и ID. Чат на сайте — дополнительный способ попробовать текстовые модели. Embeddings и Responses API пока не поддерживаются.

Параметры запроса

Обязательны model и messages (1–200 сообщений, content — строка). Роли: system, developer, user, assistant, tool. Массивы контента и assistant.tool_calls пока не поддерживаются.

• max_tokens или max_completion_tokens — положительное целое; по умолчанию 1024.
• temperature: 0–2; top_p: 0–1; stream: true/false.
• seed, stop, presence_penalty, frequency_penalty, tools, tool_choice, response_format — зависят от модели. Полный цикл tool calling пока не реализован.
• Тело до 2 MiB, текст сообщений до 1 500 000 байт. Параметры n, plugins, provider, modalities не принимаются.

Пример Python

import os, uuid
from openai import OpenAI
client = OpenAI(base_url=os.environ["APIRACLOUD_BASE_URL"],
                api_key=os.environ["APIRACLOUD_API_KEY"], max_retries=0)
result = client.chat.completions.create(
    model="apiracloud/free",
    messages=[{"role":"user", "content":"Привет!"}],
    max_tokens=256,
    extra_headers={"Idempotency-Key": str(uuid.uuid4())})
print(result.choices[0].message.content)

Пример JavaScript

const response = await fetch(`${baseURL}/chat/completions`, {
  method: "POST",
  headers: {Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID()},
  body: JSON.stringify({model:"apiracloud/free", max_tokens:256,
    messages:[{role:"user", content:"Привет!"}]})
});
const result = await response.json();
if (!response.ok) throw new Error(result.error?.message);
if (response.status === 202) console.log(result.id, result.status);
else console.log(result.choices[0].message.content);

Как считается расход

Цена указана в каталоге отдельно для входных и выходных токенов. Итоговую стоимость каждого запроса можно посмотреть в кабинете. Перед запросом сумма временно резервируется, а после ответа неизрасходованный остаток освобождается.

История и отчёты

В кабинете → Использование доступны последние запросы и расходы по моделям. Для интеграций есть клиентская сводка /api/client/usage-summary.

Скачать документацию API — форматы запросов и ответы сервиса.