Справочник
Все эндпоинты, HTTP-статусы и машинные коды ошибок
Все эндпоинты
| Метод и путь | Что делает | Страница |
|---|---|---|
GET /health | Проверка живости сервиса | — |
POST /v3/transcriptions/sync/create | Синхронная транскрипция (файл) | Транскрипции |
POST /v3/transcriptions/async/create | Асинхронная транскрипция (файл/ссылка) | Транскрипции |
POST /v3/transcriptions/stream/create | Сессия потоковой транскрипции | Транскрипции |
GET /v3/transcriptions/status/:id | Статус и результат задачи | Транскрипции |
GET /v3/models | Список моделей | Модели |
POST /v3/chat/completions/create | Генерация текста | Chat Completions |
POST /v3/embeddings/create | Эмбеддинги | Эмбеддинги |
POST /v3/billing/calculate | Цена задачи (без списаний) | Стоимость |
Дружелюбная карта HTTP-статусов
| HTTP | Типичный type | Как реагировать клиенту |
|---|---|---|
| 200/201/202 | — | Успех |
| 400 | invalid_request_error | Исправить запрос (см. param) |
| 401 | authentication_error | Проверить API-ключ |
| 402 | insufficient_quota | Пополнить баланс |
| 403 | permission_error | Проверить права аккаунта (заблокирован?) |
| 404 | not_found_error | У транскрипции нет доступа или она удалена |
| 409 | invalid_request_error | Конфликт состояний (например, вебхук обновляют у заблокированного) |
| 429 | rate_limit_error | Подождать Retry-After секунд и повторить |
| 5xx | server_error | Наша сторона; повторить с задержкой |
Детали — на странице Формат ответов и ошибок.
Машинные коды ошибок
Наиболее частые code для программной обработки:
code | Когда |
|---|---|
invalid_api_key | Нет/плохой ключ, ключ отозван, аккаунт заблокирован |
insufficient_balance | Не хватает средств на резерв или списание |
rate_limit_exceeded | Превышен лимит 10 rps на аккаунт |
too_many_concurrent_jobs | Много одновременных задач на аккаунт |
download_failed | Не удалось скачать медиа по ссылке |
unsupported_format | Формат медиа не поддерживается |
file_too_large | Файл больше лимита |
duration_exceeded | Длительность медиа больше лимита режима |
task_failed | Задача упала при распознавании |
user_blocked | Аккаунт заблокирован |
key_limit_exceeded | Больше 100 ключей на аккаунт |
model_not_found | Неизвестная модель |
Пара слов напоследок
- Секрет ключа показывается один раз — храните бережно.
- Для длинных задач включите вебхуки: меньше опросов, быстрее реакция.
- Статусы и результат всегда можно перечитать через
GET /status/:id— то, что вебхук потерялся, не проблема: итоговый ответ лежит в статусе. - При проблемах смотрите на
typeиcodeошибки: 4xx — с клиентом, 5xx — с нами, повторяйте с паузой.
Вопросы и обратная связь — пишите нам. Хорошей интеграции!