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

API modelka

API для расшифровки аудио и ограниченного использования текстовых моделей. Совместим с базовыми запросами OpenAI SDK; поддерживаемые параметры и ограничения описаны ниже. Новые оплаты открываются после проверки платёжного цикла.

Базовый URL и авторизация

base https://api.modelka.pro/v1

Все запросы — с заголовком Authorization: Bearer <ваш ключ mk-…>. Ключ выпускается в личном кабинете. Ключ храните в секрете; на сервере — только его хеш.

Быстрый старт (OpenAI SDK)

from openai import OpenAI
client = OpenAI(base_url="https://api.modelka.pro/v1", api_key="mk-…")
resp = client.chat.completions.create(
    model="modelka/large",
    messages=[{"role": "user", "content": "Привет"}],
)
print(resp.choices[0].message.content)

Модели

Доступны только эти три имени: другое имя модели или полный URI провайдера гейтвей отклоняет с ошибкой 400. Актуальный список — GET /v1/models.

Модели в закрытом тесте

На главной перечислены модели, которых пока нет в открытой продаже: Claude, Gemini, Llama, DeepSeek, Mistral, Grok, Qwen, GigaChat, а также генерация изображений (Kandinsky, Midjourney, Flux) и видео (Sora, Veo).

Подключаются по отдельному согласованию, в рамках закрытого теста. Тарификация, лимиты и сроки обсуждаются индивидуально: часть моделей требует отдельного согласия правообладателя, часть — оплаты в валюте, поэтому в общий прайс и в GET /v1/models они не входят. Запрос такой модели через API сейчас вернёт 400.

Чтобы получить доступ — напишите нам с описанием задачи и ожидаемого объёма.

Генерация текста

POST /v1/chat/completions

Базовый формат — OpenAI Chat Completions. Только текстовые сообщения с ролями system/user/assistant; максимум 100 сообщений и 100 000 байт JSON сообщений. max_tokens: 1–4096 (по умолчанию 4000). Стриминг, tools, изображения и несколько вариантов ответа не поддерживаются. Используйте "stream": false.

Стоимость: modelka/lite — 0,20 ₽, modelka/large — 0,40 ₽ за 1000 входящих и исходящих токенов. До отправки резервируется верхняя граница стоимости, после ответа списывается фактическое число токенов. При ошибке резерв средств пользователя возвращается. В аудиопакете есть отдельный ограниченный бонус для текста: 24,75 / 37,25 / 147,50 ₽ соответственно. Общая продажа API-баланса на старте закрыта.

curl https://api.modelka.pro/v1/chat/completions \
  -H "Authorization: Bearer mk-…" \
  -H "Content-Type: application/json" \
  -d '{"model":"modelka/large","messages":[{"role":"user","content":"Привет"}]}'

Распознавание речи

POST /v1/audio/transcriptions

Multipart-форма: file, model=modelka/asr, необязательный language. MP3, M4A, WAV, OGG: до 50 МБ и до 30 минут на запрос. В Telegram — до 20 МБ. Ответ содержит text, language, duration и массив segments с таймстемпами (start, end в секундах).

Покупка начисляет ровно 30, 60 или 300 минут. Перед распознаванием резервируется длительность декодированного файла с округлением вверх до миллисекунды. Успешная обработка расходует этот резерв; ошибка сервиса возвращает минуты. Автопродления и регулярных списаний нет. Две обработки одновременно на аккаунт; до 6 стартов аудиозапросов и 10 текстовых запросов в минуту.

Для сетевых повторов передавайте один и тот же Idempotency-Key (16–128 ASCII-символов) с неизменными аудио, моделью и языком. В течение 10 минут ответ может быть повторно выдан из ограниченного кэша памяти без нового списания. После истечения кэша или перезапуска вернётся 409: повторного обращения к провайдеру не будет. Защита ключа действует 30 дней; новый ключ означает новый оплачиваемый запрос. Без этого заголовка повторная отправка считается отдельным запросом. Общий лимит параллелизма платформы может быть ниже лимита аккаунта.

curl https://api.modelka.pro/v1/audio/transcriptions \
  -H "Authorization: Bearer mk-…" \
  -F model=modelka/asr \
  -F file=@meeting.mp3

Сервисные эндпоинты

GET /v1/models

GET /v1/account/balance

Баланс доступен только по активному ключу. Пример:

{"status":"ok","balance_rub":24.75,"audio_minutes_remaining":29.5,
"audio_minutes_total":30,"audio_minutes_reserved":0.5,
"has_audio_pack":true,"general_api_enabled":false}

Остатки уже учитывают резервы. general_api_enabled сообщает, открыта ли продажа общего API-баланса; аудиобонус для текста учитывается отдельно от минут. Минуты доступны по всем ключам одного аккаунта, а не дублируются на каждый ключ.

Ошибки и лимиты

При 429 учитывайте Retry-After, при 503 подождите восстановления сервиса. API ограничивает также общие расходы провайдера и параллелизм. Заголовок X-Request-ID, если присутствует, помогает поддержке найти технический сбой; не присылайте свой ключ или запись.

Данные и оплата

Облачное аудио обрабатывает Yandex SpeechKit, текст — YandexGPT. Локальный режим приложения не использует эти API. Содержимое не записывается в платёжную БД и аналитику. Подробнее: данные аудиосервиса и бота.

Начисление выполняется только после проверенного серверного подтверждения оплаты. Страница возврата из платёжной формы сама не подтверждает покупку. Для возврата используйте историю в кабинете или /return НОМЕР в боте; создание заявки ещё не означает возврат денег. Telegram использует Stars, сайт — рубли; это разные каталоги цен, без фиксированного обменного курса.

Получить ключ →