Документация

Быстрый старт

1. 1. Зарегистрируйтесь
2. 2. Пополните баланс и создайте API-ключ в кабинете.
3. 3. Подставьте ключ в сниппет ниже и выполните запрос.

curl https://apimira.com/v1/chat/completions \
  -H "Authorization: Bearer am-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": "Привет!"
      }
    ]
  }'

base_url — это адрес выше с суффиксом /v1. Модель задаётся параметром model.

Model ID берётся из каталога целиком, вместе с префиксом до «/»: например google/gemini-3.7-flash или anthropic/claude-sonnet-4.6.

Подключение программ

Любая программа с OpenAI-совместимым API подключается тремя значениями (Claude Code и Anthropic SDK — исключение, у них свой протокол; смотрите карточку ниже):

Если поле называется просто «Base URL» — путь /chat/completions программа добавит сама, дописывать его не нужно. И следите, чтобы в адресе не получилось /v1/v1.

Быстрая проверка ключа без программы — выполните запрос из блока «Быстрый старт» выше.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ApiMira": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ApiMira",
      "options": {
        "baseURL": "https://apimira.com/v1",
        "apiKey": "am-ВАШ_КЛЮЧ"
      },
      "models": {
        "openai/gpt-5.4-mini": { "name": "GPT-5.4 Mini" },
        "anthropic/claude-sonnet-4.6": { "name": "Claude Sonnet 4.6" }
      }
    }
  }
}

Чат — генерация ответа

POST /v1/chat/completions

Генерация ответа модели. Поддерживает stream=true (SSE). Формат запроса и ответа — как у OpenAI.

Стриминг: передайте "stream": true. Чанки приходят в формате data: {...} и завершаются data: [DONE].

Поддержано: текстовый чат (включая вызовы инструментов через tools и tool_choice), картинки на вход у моделей с такой способностью, генерация и редактирование изображений, генерация видео. В чате response_format, functions, audio и modalities по-прежнему отвечают 400 — параметр не игнорируется молча.

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

Тело POST /v1/chat/completions. Обязательны только model и messages — всё остальное можно не передавать, у каждого поля есть разумное значение по умолчанию.

Что приходит в ответе

Формат совпадает с OpenAI, поэтому официальные SDK разбирают его без переделок.

Картинки на вход

Модель, которая умеет смотреть на картинки, принимает их прямо в переписке: скриншот ошибки, фото чека, макет. Отдельного эндпоинта не нужно — картинка едет частью сообщения рядом с текстом, тем же POST /v1/chat/completions. То же самое работает на /v1/messages и /v1/responses.

Как передать картинку

В сообщении роли user поле content становится массивом частей: текст — часть типа text, картинка — часть типа image_url, у которой url это строка вида data:image/png;base64,… — тип картинки и её байты в base64. Порядок частей сохраняется: модель видит их в том порядке, в котором вы прислали. Поле detail (auto, low, high) передаётся модели как есть. Сообщение может состоять из одних картинок, без текста.

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Что написано на этом скриншоте?" },
    {
      "type": "image_url",
      "image_url": { "url": "data:image/png;base64,iVBORw0KGgo…", "detail": "auto" }
    }
  ]
}

Внешние ссылки шлюз не скачивает: картинка по http или https возвращает 400 invalid_request с подсказкой. Кодируйте файл в base64 сами — это одна строка в любом языке.

curl https://apimira.com/v1/chat/completions \
  -H "Authorization: Bearer am-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": [
      { "type": "text", "text": "Что написано на этом скриншоте?" },
      { "type": "image_url", "image_url": { "url": "data:image/png;base64,'"$(base64 -w0 shot.png)"'" } }
    ]}]
  }'

Пределы

• — Форматы: PNG, JPEG, WebP. Тип проверяется по первым байтам файла, а не по названию: «png» с чем-то другим внутри возвращает 400 у нас, не доходя до модели.
• — Одна картинка — до 5 МБ двоичных данных; в base64 тот же файл занимает примерно на треть больше.
• — До 50 картинок на запрос — считаются все картинки переписки, а не только последнего сообщения.
• — Тело запроса с картинками — до 24 МБ. Этот предел главнее числа картинок: 50 штук пройдут только мелкими.
• — Тело больше 2 МБ читается только по действующему ключу с положительным балансом, и на загрузку даётся 30 с — дальше 408 request_timeout с заголовком Retry-After. Число одновременных крупных загрузок ограничено: следующая получает 429 с Retry-After, повторите её через указанное время.
• — Больше 20 картинок в одном запросе часть моделей принимает только мелкими — до 2000 px по большей стороне.

Какие модели видят картинки

Способность проверена живой пробой, а не обещанием: сегодня картинки принимают 38 моделей каталога. У них же стоит пометка «Видит картинки» на странице «Модели», а GET /v1/account/pricing отдаёт их в поле capabilities. Модель без этой способности отвечает 400 unsupported_capability и денег не берёт.

openai/gpt-6-astra · openai/gpt-5.6-sol · openai/gpt-5.6-terra · openai/gpt-5.6-luna · openai/gpt-5.5 · openai/gpt-5.4-mini · openai/gpt-5.3-codex · anthropic/claude-fable-5.1 · anthropic/claude-fable-5 · anthropic/claude-fable-5-compressed-context · anthropic/claude-opus-5 · anthropic/claude-opus-4.8 · anthropic/claude-opus-4.7 · anthropic/claude-opus-4.6 · anthropic/claude-opus-4.5 · anthropic/claude-sonnet-4.6 · anthropic/claude-sonnet-4.5 · anthropic/claude-haiku-4.5 · google/gemini-3.7-flash · google/gemini-3.6-flash · google/gemini-3.1-pro-preview · google/gemini-3.1-flash-lite · google/gemini-3-flash-preview · google/gemini-2.5-pro · x-ai/grok-4.6 · x-ai/grok-4.5 · x-ai/grok-4.3 · x-ai/grok-build-0.1 · z-ai/glm-5.3 · z-ai/glm-5.3-flash · z-ai/glm-5.1 · moonshotai/kimi-k3 · moonshotai/kimi-k2.7-code · moonshotai/kimi-k2.5 · qwen/qwen3.8-max · xiaomi/mimo-v2.5-pro · xiaomi/mimo-v2.5 · minimax/minimax-m3

Сколько стоит картинка

Картинка тарифицируется входными токенами модели. Сколько их — решает модель: обычно около 1 089 токенов за кадр 1024×1024, у отдельных моделей в разы больше. Списывается ровно то, что модель вернула в usage.prompt_tokens, — та же формула, что у текста. Под запрос резервируется оценка с запасом, лишнее возвращается на баланс (см. «Цены и списания»). Оценка того же порядка приходит в ответе POST /v1/messages/count_tokens.

Картинки от агентов

Картинка из результата инструмента — агент прочитал файл-картинку или сделал скриншот — тоже доходит до модели. В протоколе OpenAI результат инструмента несёт только текст, поэтому шлюз передаёт такие картинки отдельным пользовательским ходом сразу после серии результатов; порядок переписки при этом сохраняется. Настраивать ничего не нужно.

На /v1/responses картинка — часть input_image; значение detail: original приравнивается к high. На /v1/messages это блок image с source типа base64; source типа url шлюз не скачивает, как и в чате. Блоки document и file по-прежнему отвечают 400: файлы на вход мы пока не принимаем.

Отказы

400 invalid_request — не тот формат, байты не совпали с типом, превышен размер или число картинок, картинка в сообщении system, developer или assistant. 400 unsupported_capability — модель не принимает картинки. 400 context_length_exceeded — картинки вместе с текстом не влезают в контекст модели. 408 request_timeout — тело не пришло целиком за отведённое время. 413 payload_too_large — тело больше предела. Ни один из этих отказов не тарифицируется.

Генерация изображений

POST /v1/images/generations

POST /v1/images/generations — синхронно, тело и ответ совместимы с OpenAI Images. Списывается фиксированная цена за изображение, умноженная на количество (n).

curl https://apimira.com/v1/images/generations \
  -H "Authorization: Bearer am-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "a red cat wearing glasses",
    "n": 1
  }'

Модель должна быть типа «изображение» (см. GET /v1/models). Ответ — массив data, в каждом элементе b64_json: кадр в base64. Ссылку мы не отдаём, даже если её дала модель, — кадр приезжает байтами. У потокенной модели в ответе есть usage: ровно те числа, по которым списано. Заголовок x-request-id в ответе — идентификатор записи списания, по нему запрос находится в GET /v1/account/usage.

Редактирование изображений

POST /v1/images/edits

POST /v1/images/edits меняет готовую картинку по текстовому описанию: заменить фон, дорисовать деталь, повторить стиль. Тело — multipart/form-data, как в OpenAI Images API: файл (или несколько) плюс prompt. Ответ — кадр в base64.

curl https://apimira.com/v1/images/edits \
  -H "Authorization: Bearer am-ВАШ_КЛЮЧ" \
  -F model=openai/gpt-image-2 \
  -F prompt="Замени фон на светлый градиент" \
  -F image=@cat.png

Ответ:

{
  "created": 1757700000,
  "data": [{ "b64_json": "iVBORw0KGgo…" }],
  "usage": { "input_tokens": 116, "output_tokens": 1650, "total_tokens": 1766 }
}

Формат кадра выбирает модель: одна отдаёт PNG, другая JPEG. Мы его не обещаем и не переделываем — читайте data[0].b64_json как байты картинки, а тип при необходимости определяйте по первым байтам.

Поле usage приходит не всегда: у модели с ценой за кадр его нет вовсе — платится кадр, а не токены. Разбивка input_tokens_details и output_tokens_details появляется только тогда, когда её дала модель: проверяйте наличие поля, а не рассчитывайте на него.

Поля запроса

Принимаем и модели не пересылаем

quality, user, background со значением opaque или auto, input_fidelity со значением low. Запрос с ними работает, но результат и цена остаются такими, как без них.

Цены и списания

Цена — как у генерации той же моделью, отдельного тарифа за правку нет. У потокенной модели считаются вход и выход по её ставкам, и usage в ответе показывает ровно те числа, по которым списано. У модели с ценой за кадр списывается цена кадра, умноженная на число кадров. Под запрос резервируется оценка с запасом, лишнее возвращается; сбой модели не стоит ничего.

Заголовок Content-Length обязателен: загрузка без него (chunked) возвращает 400 invalid_request. Если клиент шлёт файл потоком, прочитайте его в память или укажите размер сами.

В ответе есть заголовок x-request-id — идентификатор записи списания. По нему запрос находится в GET /v1/account/usage (поле id) и в кабинете; SDK OpenAI кладёт его в request_id.

Какие модели редактируют

Сегодня редактирование включено у 2 моделей каталога. У них стоит пометка «Редактирование» на странице «Модели», а GET /v1/account/pricing отдаёт способность image_edit в поле capabilities.

openai/gpt-image-2 · google/gemini-3.1-flash-image-preview

Генерация видео

POST /v1/videos/generations

Видео генерируется асинхронно: запрос создаёт задачу и сразу возвращает её id. Параметр seconds обязателен — это длительность ролика, от неё считается цена.

curl https://apimira.com/v1/videos/generations \
  -H "Authorization: Bearer am-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "alibaba/wan-2.6",
    "prompt": "a paper boat drifting on a calm pond",
    "seconds": 5
  }'

# {"id": "9b2f…", "status": "processing", "created": 1755648000}

GET /v1/jobs/{id}

Готовность опрашивайте раз в 5–10 секунд. status: processing — ещё идёт, succeeded — готово (в ответе url ролика), failed — не вышло (поле error). Генерация занимает от 30 секунд до 3 минут. Ссылка ведёт в хранилище поставщика — скачайте файл сразу после получения.

curl https://apimira.com/v1/jobs/JOB_ID \
  -H "Authorization: Bearer am-ВАШ_КЛЮЧ"

# {"id": "9b2f…", "status": "succeeded", "url": "https://…/clip.mp4"}

Списание = цена за секунду × seconds. Деньги резервируются при создании задачи и списываются только когда ролик готов; если генерация не удалась — резерв возвращается полностью.

Модели и длительности

Модель должна быть типа «видео» (см. GET /v1/models). Цены за секунду — на странице моделей.

Эндпоинты

Цены и списания

Как это устроено

• — Баланс пополняется заранее — счетов в конце месяца и подписок нет.
• — За каждый запрос списывается его собственная стоимость: она зависит от модели и от количества токенов.
• — Баланс уменьшается сразу после ответа. Когда денег не хватает, запрос отвечает ошибкой 402 — в минус аккаунт не уходит.

Как считается стоимость

У каждой модели своя цена, указанная за 1 миллион токенов, — отдельно за вход (ваш запрос) и отдельно за выход (ответ модели). Выход почти всегда дороже входа. Актуальные цены всех моделей — в каталоге «Модели и цены».

вход   =  токены_входа   / 1 000 000 × цена_входа
выход  =  токены_выхода  / 1 000 000 × цена_выхода
──────────────────────────────────────────────────
итого  =  вход + выход

Каждая половина округляется вверх до одной миллионной доллара. Количество токенов берётся из ответа модели — то самое поле usage, которое вы видите в своём коде.

Пример расчёта

модель:       openai/gpt-5.4-mini
цена входа:   $0.12 за 1M токенов
цена выхода:  $0.64 за 1M токенов
запрос:       1 200 токенов входа, 800 токенов выхода

вход      1 200 / 1 000 000 × $0.12  = $0.000144
выход     800 / 1 000 000 × $0.64    = $0.000512
────────────────────────────────────────────────
списано:                             = $0.000656

Цены в примере не выдуманы — они подставляются из живого каталога, так же как в счёт.

Скидка за кэш

Если в начале запроса идёт тот же текст, что и в предыдущем — системный промпт, инструкции, длинный контекст, — модель берёт его из кэша, и мы считаем эти токены по льготной ставке. Включать ничего не нужно: кэш срабатывает сам, когда одинаковый префикс приходит подряд и он достаточно длинный (примерно от тысячи токенов). Первый запрос, который кладёт текст в кэш, не дорожает: он стоит ровно столько же, сколько без кэша.

вход  =  (токены_входа − токены_кэша) / 1 000 000 × цена_входа
      +  токены_кэша / 1 000 000 × цена_кэш-входа

Сколько токенов пришло из кэша, видно в ответе: usage.prompt_tokens_details.cached_tokens, на эндпоинте /v1/messages — usage.cache_read_input_tokens. Те же числа лежат в кабинете, в GET /v1/account/usage и в выгрузке CSV. Ставка кэш-входа указана на странице «Модели» и в GET /v1/account/pricing. Скидка есть не у всех моделей: там, где ставка не указана, кэш считается по обычной цене входа.

Бронь на время запроса

Пока модель отвечает, никто не знает, каким длинным окажется ответ. Поэтому перед обращением к модели на балансе временно резервируется худший случай:

бронь  =  токены_входа / 1 000 000 × цена_входа
       +  max_tokens / 1 000 000 × цена_выхода

Если на бронь не хватает, запрос отклоняется сразу, ещё до обращения к модели. Когда ответ получен, списывается фактическая стоимость, а остаток брони возвращается на баланс в тот же момент.

тот же запрос,  max_tokens: 4 000

забронировано:     $0.002704
списано по факту:  $0.000656
вернулось:         $0.002048

Ставьте max_tokens близко к ожидаемой длине ответа: чем он больше, тем крупнее бронь и тем меньше баланса остаётся на параллельные запросы. Если max_tokens не задан, бронь считается по потолку в 32 000 токенов.

Когда денег не берут

Ошибка на стороне модели (502, 504) — списания нет, бронь возвращается целиком. Отклонённый запрос — неверный ключ, нехватка баланса, неподдерживаемый параметр, слишком большое тело — тоже бесплатен: до модели он не дошёл. Оценка токенов через /v1/messages/count_tokens бесплатна всегда.

Где смотреть расходы

В кабинете. На странице ключа — журнал запросов с моделью, токенами и стоимостью каждого, выгрузка в CSV и график по дням. В разделе «Расход» — сводка за период и разбивка по моделям. Тексты запросов и ответов мы не сохраняем: в статистике только эти счётчики.

Account API — баланс, цены и статистика ключа

Read-only API вашего аккаунта: баланс, розничные цены и usage ключа из собственного бэкенда — без захода в кабинет. Раздел кабинета «Управление аккаунтом» собирает базовый URL и готовые сниппеты.

Авторизация — тем же ключом, что и запросы к моделям: заголовок Authorization: Bearer. Разрешён только GET; ключ должен быть активен (пауза и отзыв дают 401). Не передавайте ключ в URL и не используйте в браузерном коде. Статистика считается в разрезе ключа, которым сделан запрос; баланс и цены общие для аккаунта.

Параметры query

Все параметры необязательны. Значение за границами — 400 invalid_request с именем параметра в param.

Примеры

curl https://apimira.com/v1/account/balance \
  -H "Authorization: Bearer am-ВАШ_КЛЮЧ"

# {"object": "account.balance", "balance_usd": 4.981234, "currency": "USD"}

curl "https://apimira.com/v1/account/usage?days=7&limit=25" \
  -H "Authorization: Bearer am-ВАШ_КЛЮЧ"

Ответ:

{
  "object": "list",
  "days": 7,
  "limit": 25,
  "page": 0,
  "has_more": false,
  "data": [
    {
      "id": "9b2f…",
      "created_at": "2026-08-21T09:58:12.000Z",
      "model": "openai/gpt-5.4-mini",
      "operation": "chat",
      "status": "success",
      "tokens_in": 1200,
      "cached_tokens_in": 0,
      "images_in": 0,
      "tokens_out": 800,
      "cost_usd": 0.000656,
      "price_input_usd_per_1m_tokens": 0.12,
      "price_cached_input_usd_per_1m_tokens": 0.0168,
      "price_output_usd_per_1m_tokens": 0.64,
      "price_generation_usd": null,
      "latency_ms": 812
    }
  ]
}

Ответ /v1/account/analytics — один объект с полями:

totals · models[] · daily[] · errors.by_code[]

Ошибки

Конверт ошибок общий для всего шлюза (см. раздел «Ошибки»). Здесь встречаются:

401 invalid_api_key · 400 invalid_request · 429 rate_limited

Лимиты и ограничения

Лимиты защищают и вас, и шлюз: случайный цикл в коде не должен выжигать баланс за минуту.

Превышение частоты — это 429 rate_limited: подождите и повторите, ключ не блокируется и не штрафуется. Тело больше 2 МБ читается только по действующему ключу с положительным балансом: на загрузку даётся 30 с, а число одновременных крупных загрузок ограничено — лишняя получает 429 с заголовком Retry-After. Лимит расходов и расписание вы задаёте сами в кабинете на странице ключа. Перебор неверных ключей с одного адреса дополнительно замедляется.

Коды ошибок

Все ошибки приходят в одном формате — таком же, как у OpenAI, поэтому SDK разбирают их сами:

{
  "error": {
    "message": "The model `openai/gpt-9` does not exist or is disabled.",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}

Опирайтесь на code: он машиночитаемый и не меняется. Текст message написан для человека и со временем может стать другим. Поле param указывает на конкретное поле запроса, если ошибка в нём.

Ни одна ошибка из таблицы не тарифицируется. Если запрос не дошёл до модели или модель ответила ошибкой, деньги не списываются, а бронь возвращается на баланс целиком.

Частые вопросы