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

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

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

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

curl https://your-domain.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 не списывают рубли за токены. На одного клиента действует общий лимит 50 запросов в сутки и 20 запросов в минуту по всем API-ключам. Суточный счетчик обновляется в 00:00 UTC. При исчерпании лимита API вернет 429 FREE_DAILY_LIMIT_EXCEEDED.

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

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

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

ID задания

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

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

Ошибки возвращаются как {"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 автоматически выбирает доступный бесплатный маршрут в пределах общего дневного лимита клиента.

Сейчас шлюз принимает текстовые Chat Completions. Генерация изображений, видео, аудио, 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);

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

Ключ определяет клиента. Для каждого запроса сохраняются модель, входные и выходные токены, стоимость, себестоимость и версия цены. До вызова резервируется сумма, после usage происходит списание и освобождение остатка. Один рубль = 1 000 000 micros. Заголовок X-ApiraCloud-Cost-Micros и поле gateway.charged_micros возвращаются в обычном ответе; для SSE смотрите итог в кабинете.

Розничная ставка = базовая цена × настроенный курс × 1,40. Кэш и временные скидки не меняют две опубликованные ставки автоматически. Поэтому фактическая наценка запроса может отличаться. Новые тарифы вступают в силу после подтверждения администратора.

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

В кабинете → Использование доступны последние задания и сводка по моделям за месяц. Администратор видит также клиентов, себестоимость и разницу. API сводок: /api/client/usage-summary и /api/admin/usage-summary, параметры from, to в ISO UTC, интервал [from, to). Эти маршруты требуют сессионную cookie, а не Bearer API-ключ.

Скачать полную документацию API — форматы, ограничения, биллинг, административные методы и настройка Telegram.