ИИ-генерации¶

Общая схема для всех генераций. Генерация - асинхронная задача ИИ. Методы доступны ролям teacher и school_admin; каждый видит только свои генерации, чужая отвечает 404.

Порядок работы:

Создайте генерацию методом нужного вида; ответ 202 содержит объект «Генерация» со статусом pending.
Опрашивайте «Статус генерации» раз в 3-5 секунд, пока статус не станет completed или failed.
Заберите результат: файл - по download_url, данные - из result.

Таймаута нет: задача может час ждать в очереди в pending. После failed создайте новую генерацию: повтора нет. Лимитов на число генераций нет. Статусы - в разделе «Статусы и коды».

Вид	`kind`	Результат
Презентация по плану урока	`presentation`	Файл pptx или pdf по `download_url`
Smart questions	`smart_questions`	`result.questions`
Диктант	`dictation`	Аудио ogg по `download_url`, `result.text` и `result.alignment`
Тест для Доды	`doda_test`	Заполненный тест Доды, `result.test_id`; метод - в разделе «Дода: тесты»

Объект «Генерация»¶

Параметр	Тип	Описание
`id`*	uuid	id генерации
`kind`*	string	Вид генерации
`status`*	string	`pending`, `in_progress`, `completed` или `failed`
`params`*	object	Параметры запроса, как их прислал клиент; у генераций из файла ещё `file_name`
`result`	object	Результат, формат зависит от вида; `null`, пока его нет
`progress`	object	Ход работы, формат не фиксирован; например `{"current_step": 3, "max_steps": 4}`
`error`	string	Техническая причина `failed` для логов и поддержки
`download_url`	string	Временная ссылка на файл; только у `completed` презентации и диктанта
`download_url_expires_at`	datetime	Когда ссылка перестанет работать: через 15 минут; за новой - запросите генерацию снова
`created_at`*	datetime	Когда создана
`updated_at`*	datetime	Когда изменилась
`finished_at`	datetime	Когда стала `completed` или `failed`

{
  "id": "c39b6a52-1f0e-4a5b-8c7d-9e0f1a2b3c4d",
  "kind": "presentation",
  "status": "completed",
  "params": {"file_name": "План урока дроби.docx", "format": "pptx", "style": "lesson", "teacher_prompt": null},
  "result": null,
  "progress": {"current_step": 4, "max_steps": 4},
  "error": null,
  "download_url": "https://storage.example/korifei/deck.pptx?X-Amz-Signature=...",
  "download_url_expires_at": "2026-11-10T10:21:40Z",
  "created_at": "2026-11-10T10:00:00Z",
  "updated_at": "2026-11-10T10:06:40Z",
  "finished_at": "2026-11-10T10:06:40Z"
}

Ошибки, общие для методов создания:

Код ошибки	Когда
`400`	Файл не `.docx` и не `.pdf`, или содержимое не совпадает с расширением
`401`	Нет токена
`413`	Файл больше 20 МБ
`422`	Неверные поля
`502`	Недоступно хранилище файлов или Дода
`503`	ИИ временно недоступен; генерация записана как `failed`

Статус генерации¶

Возвращает генерацию со статусом и результатом.

Запрос: GET {API_URL}/v1/generations/{generation_id}, авторизация - токен.

Ответ 200: объект «Генерация».

Код ошибки	Когда
`404`	Генерации нет или она чужая

Список генераций¶

Возвращает генерации владельца токена, новые первыми.

Запрос: GET {API_URL}/v1/generations, авторизация - токен.

Параметр	Тип	Описание
`kind`	string	В строке запроса: `presentation`, `smart_questions`, `dictation` или `doda_test`
`page`, `page_size`	integer	В строке запроса: пагинация

Ответ 200: страница с items - объектами «Генерация».

Скачивание файла¶

Отдаёт файл по download_url; ссылка может вести и на другой сервер.

Запрос: GET {API_URL}/v1/files/{bucket}/{key}?expires=...&signature=....

Авторизация - подпись в ссылке; адрес берётся из download_url целиком.

Ответ 200: файл как вложение. Content-Type - по виду файла: аудио диктанта audio/ogg, презентация application/pdf или application/vnd.openxmlformats-officedocument.presentationml.presentation.

Код ошибки	Когда
`404`	Ссылка подделана, истекла, или файла нет