> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiid.edu.kg/llms.txt
> Use this file to discover all available pages before exploring further.

# Соглашения о вызовах

> Описание аутентификации, структуры ошибок, общих перечислений и запросов асинхронных задач.

## Способы аутентификации

Все публичные интерфейсы по умолчанию используют Bearer Token:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Базовый адрес:

```text theme={null}
https://api.aiid.edu.kg
```

Хотя у некоторых нативных форматов или специализированных для модели интерфейсов пути отличаются, они по-прежнему используют ту же схему аутентификации по API Key.

## Структура ошибок

При поиске причин неудачных запросов в первую очередь обращайте внимание на:

* Код состояния HTTP
* `error.code`
* `error.message`

Типичная структура:

```json theme={null}
{
  "error": {
    "code": "invalid_request_error",
    "message": "the reason why error occurred"
  }
}
```

## Распространенные коды состояния

| HTTP | Значение                      | Рекомендация                                                       |
| ---- | ----------------------------- | ------------------------------------------------------------------ |
| 400  | Ошибка параметров запроса     | Проверьте обязательные поля, имя модели и параметры пути           |
| 401  | Ошибка аутентификации         | Проверьте, действителен ли API Key                                 |
| 404  | Путь или задача не существуют | Проверьте путь запроса и ID задачи                                 |
| 429  | Превышен лимит запросов       | Снизьте частоту или повторите попытку                              |
| 500  | Внутренняя ошибка сервера     | Зафиксируйте запрос и повторите попытку или обратитесь в поддержку |

## Общие перечисления состояний

Распространенные роли (Enum):

* `system`
* `user`
* `assistant`

Распространенные статусы длительных задач:

* `queued`
* `running`
* `succeeded`
* `failed`
* `in_progress`
* `completed`

Поля статуса, возвращаемые различными видео-интерфейсами, могут немного отличаться, но их семантика всегда связана с состояниями «В очереди / В процессе / Завершено / Ошибка».

## Запрос асинхронных задач

Текущая публичная документация ориентирована на «активный запрос результатов задачи». Распространенные методы включают:

* `GET /v1/videos/{task_id}`
* `GET /v1/responses/{response_id}`
* `GET /api/v3/contents/generations/tasks/{task_id}`
* `GET /suno/fetch/{task_id}`
* `GET /ent/v2/tasks/{task_id}/creations`
* `GET /v1beta/{operation_name}`

Рекомендации по интеграции:

* Используйте механизмы повторов и экспоненциальной задержки при запросе задач
* Обеспечьте персистентное хранение `task_id` или `operation_name`
* Запрос результатов как резервный механизм (fallback) для проверки статуса асинхронных задач