Аутентификация

Все эндпоинты (кроме служебных) требуют API-ключ в заголовке Authorization:

Authorization: Bearer <API-ключ>

Ключ выдаётся в кабинете разработчика на aihere.ru. Ключ привязан к вашему аккаунту AiHere — баланс и лимиты общие с кабинетом.

• Невалидный или отсутствующий ключ → 401;
• Временная недоступность сервиса проверки ключа → 503 (повторите запрос позже).

Не встраивайте ключ в браузерный или мобильный код — вызывайте Api Dev со своего бэкенда.

Rate-limit

Лимиты действуют на группу эндпоинтов (на клиента/IP). Отдельные эндпоинты могут иметь более строгий лимит — он указан в описании эндпоинта.

Группа	Лимит по умолчанию
/images/*	10 запросов/мин
/videos/*	5 запросов/мин
/sounds/*	5 запросов/мин
/files/upload-by-url	20 запросов/мин
/files/upload-by-base64, /files/upload-by-stream	10 запросов/мин
/balance, /stats	30 запросов/мин
/callback/secret	10 запросов/мин

При превышении — 429 Too Many Requests. При поллинге статуса задачи опрашивайте не чаще 1 раза в 3 секунды (см. стратегию поллинга).

Биллинг

• Оплата в рублях; баланс — GET /balance.
• Стоимость зависит от модели и параметров (длительность, разрешение, режим) и списывается в момент постановки задачи.
• Если обратиться к провайдеру не удалось — списанные средства возвращаются. При финальном fail задачи возврат ставится автоматически (best-effort); актуальный баланс всегда виден через GET /balance.

Идемпотентность

Явных ключей идемпотентности нет: каждый POST создаёт новую задачу и списывает стоимость. Дедупликацию (например, по task_id внешней системы или хешу запроса) реализуйте на своей стороне и не повторяйте запрос при сетевом таймауте, не проверив список задач через /stats (recent_tasks).

Формат ответов

Успешное создание задачи:

{ "task_id": 123 }

Статус задачи (GET /task/{task_id}):

{
  "status": "success",
  "result_urls": ["https://storage.yandexcloud.net/.../api-results/123/0.mp4"],
  "error": null
}

Ошибка (FastAPI-стиль, поле detail):

{ "detail": "Insufficient balance" }

Ошибка валидации тела → 422 со списком полей:

{
  "detail": [
    { "loc": ["body", "prompt"], "msg": "field required", "type": "value_error.missing" }
  ]
}

Коды ошибок

Код	Значение
401	Нет или невалидный API-ключ
402	Недостаточно средств на балансе
422	Тело запроса не прошло валидацию (см. detail[].loc)
429	Превышен rate-limit группы
502	Ошибка апстрим-провайдера генерации
503	Провайдер или сервис баланса недоступен — средства возвращены, повторите позже

Загрузка референсов

Многие эндпоинты принимают публичные URL изображений/аудио/видео. Локальные файлы сначала загрузите через /files/* — вернётся публичный URL, который можно передать в генерацию.