Документация API
REST API для транскрибации аудио и видео. Платные клиенты используют для сторонних интеграций API-ключ, созданный в настройках аккаунта.
Базовый URL
https://scribe.uustudio.cc
Аутентификация
Сторонние интеграции должны передавать API-ключ платного аккаунта в заголовке Authorization.
Заголовок Authorization
Authorization: Bearer {token}Создавайте и отзывайте ключи на странице API-ключей в настройках. Эндпоинты входа приложения предназначены только для официальных клиентов.
Ответы об ошибках
Все ошибки возвращают JSON-тело с полем message .
Стандартная ошибка
{
"message": "Description of the error"
}Ошибка валидации (422)
{
"message": "The name field is required.",
"errors": {
"name": ["The name field is required."]
}
}| Статус | Описание |
|---|---|
| 401 | Не аутентифицирован (токен отсутствует или недействителен) |
| 403 | Запрещено или превышен лимит тарифа |
| 404 | Ресурс не найден |
| 422 | Валидация не удалась |
| 429 | Превышен лимит скорости или слишком много параллельных задач |
| 500 | Внутренняя ошибка сервера |
Лимиты скорости
Аутентифицированные API-эндпоинты ограничены 10 запросами в минуту на токен.
Лимиты использования
Доступность API
Сторонний REST API недоступен на бесплатном тарифе. Для создания и использования API-ключей перейдите на Pro или Max либо купите пакет с оплатой по мере использования.
- Макс. размер файла
- 2 ГБ
- Параллельные задачи
- Макс. 3
- Макс. повторов на задачу
- 3
Сравнение платных тарифов
| Функция | Pay as you go | Pro | Max |
|---|---|---|---|
| Загрузок в день | Безлимит | Безлимит | Безлимит |
| Форматы экспорта | Все | Все | Все |
| Приоритет задач | Средний | Средний | Высокий |
Сценарии работы
Загрузить аудио/видео файл
POST /api/uploads/sign→ Получить upload_id и информацию о частяхPUT {presigned_url}→ Загрузить каждую часть в хранилищеPOST /api/uploads/complete→ Завершить загрузку, автоматически создать задачуGET /api/tasks/{id}→ Опрашивать статус (pending -> scribing -> finished)GET /api/tasks/{id}/download/srt→ Экспортировать (опционально)
Создать задачу вручную
POST /api/tasks→ Создать с disk, path, nameGET /api/tasks/{id}→ Опрашивать статусGET /api/tasks/{id}→ Получить segments, summary, mindmap
Аутентификация
/api/loginАутентификация по email и паролю. Возвращает токен Sanctum.
Тело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| string | Yes | Email пользователя (макс. 255) | |
| password | string | Yes | Пароль пользователя |
Ответ 200
{
"token": "1|abc123...",
"user": {
"id": 1,
"name": "Zhang San",
"email": "[email protected]"
}
}Ограничено 5 попытками в минуту на email.
/api/registerСоздать новый аккаунт. Возвращает токен Sanctum.
Тело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| name | string | Yes | Отображаемое имя (макс. 255) |
| string | Yes | Уникальный email (макс. 255) | |
| password | string | Yes | Должен быть подтверждён |
| password_confirmation | string | Yes | Подтверждение пароля |
Ответ 201
{
"token": "1|abc123...",
"user": {
"id": 1,
"name": "Zhang San",
"email": "[email protected]"
}
}/api/logoutОтзывает текущий токен доступа.
Ответ 204
Не возвращает тело.
Задачи
/api/tasksСоздать задачу транскрибации. Макс. 3 параллельные задачи на пользователя.
Тело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| disk | string | Yes | r2 / remote / youtube Идентификатор источника хранения |
| name | string | Yes | Название задачи (макс. 255) |
| path | string | Yes | Путь к файлу или исходный URL |
| file | string | No | Исходное имя файла (макс. 255) |
| size | integer | No | Размер файла в байтах |
| duration | integer | No | Продолжительность в секундах |
| cost | integer | No | Стоимость в секундах |
| segments | array | No | Сегменты транскрипции |
| speaker_diarization | boolean | Нет | app.tasks.speaker_diarization_api_description |
Ответ 201
{
"id": 1,
"name": "Meeting Recording",
"status": "pending",
"speaker_diarization": true,
"created_at": "2026-03-02T10:30:00+08:00"
}Ошибки
| Статус | Описание |
|---|---|
| 403 | Бесплатные пользователи не могут отправлять ссылки YouTube через API. |
| 429 | Достигнут лимит параллельных задач (3) |
/api/tasks/{id}Получить полные детали задачи, включая результаты транскрибации.
Ответ
{
"id": 1,
"name": "Meeting Recording",
"file": "meeting.mp3",
"path": "2026-03-02/01HQX...mp3",
"disk": "r2",
"size": 50545869,
"duration": 1965,
"cost": 33,
"status": "finished",
"attempts": 1,
"quality": 3,
"created_at": "2026-03-02T10:30:00+08:00",
"updated_at": "2026-03-02T10:45:00+08:00",
"summary": "The meeting discussed three topics...",
"mindmap": "# Topic\n## Sub-topic 1",
"folder": "Work",
"tags": ["Work"],
"url": "https://youtube.com/watch?v=...",
"segments": [
{
"id": 1,
"start": 0,
"end": 5000,
"speaker": "Speaker 1",
"tokens": ["Okay", "so let's", "begin"],
"text": "Okay, so let's begin..."
}
],
"export": {
"allowed_formats": ["txt", "srt", "vtt", "csv", "pdf", "docx"],
"heavy_formats": ["pdf", "docx"],
"version": "20260302104500"
}
}Поля ответа
| Поле | Тип | Описание |
|---|---|---|
| disk | string|null | Диск хранения: r2 / remote / youtube |
| size | int|null | Размер файла в байтах |
| cost | int|null | Стоимость в секундах |
| attempts | int | Количество повторов |
| quality | int|null | Оценка качества (0-5) |
| summary | string|null | Резюме, сгенерированное ИИ |
| mindmap | string|null | Майндмэп, сгенерированный ИИ |
| folder | string|null | Имя первой метки (папка) |
| tags | array | Все имена меток |
| url | string|null | Исходный URL (для задач YouTube) |
| segments | array|null | Сегменты транскрипции |
| segments[].start | int | Время начала (мс) |
| segments[].end | int | Время окончания (мс) |
| segments[].text | string | Текст сегмента |
| segments[].speaker | string|null | Идентификатор спикера |
| segments[].tokens | array|null | Массив токенов слов |
| export | object | Метаданные экспорта (allowed_formats, heavy_formats, version) |
/api/tasksПараметры запроса
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| status | string | all | Фильтровать по статусу |
| search | string | — | Искать по имени |
| folder | string | — | Фильтровать по папке (или Uncategorized) |
| page | int | 1 | Номер страницы |
| per_page | int | 25 | Элементов на странице (макс. 100) |
Ответ
{
"data": [
{
"id": 1,
"name": "Meeting Recording",
"file": "meeting.mp3",
"disk": "r2",
"size": 50545869,
"duration": 1965,
"cost": 33,
"status": "finished",
"attempts": 1,
"quality": 3,
"folder": "Work",
"created_at": "2026-03-02T10:30:00+08:00"
}
],
"current_page": 1,
"last_page": 1,
"per_page": 25,
"total": 1
}/api/tasks/{id}/retryПовторить неудачную задачу. Устанавливает статус в pending (R2) или waiting (remote/YouTube). Макс. 3 повтора.
Ответ 200
{
"id": 1,
"status": "pending",
"attempts": 2
}/api/tasks/{id}/download/{format}Экспортировать транскрипт. Лёгкие форматы возвращают файл напрямую. Тяжёлые форматы (pdf/docx) могут возвращать 202 во время обработки.
Параметры пути
| Параметр | Описание |
|---|---|
| format | txt / srt / vtt / csv / pdf / docx |
Ответы
200 - Файл готов (лёгкие форматы)
Возвращает бинарный файл.
200 - Файл готов (тяжёлые форматы, JSON-запрос)
{
"status": "ready",
"url": "https://scribe.uustudio.cc/api/tasks/1/download/pdf"
}202 - Обработка тяжёлого формата
{
"status": "processing",
"message": "Your export is being generated. Please try again shortly."
}/api/tasks/{id}/audioПередавать исходный аудио- или видеофайл напрямую из хранилища (только R2).
Ответ
200 - Бинарный поток аудио- или видеофайла. Возвращает 404, если файл отсутствует или не хранится на диске R2.
/api/tasks/{id}/refresh-summaryОбновить и вернуть последнее резюме и майндмэп, сгенерированные ИИ.
Ответ
{
"summary": "The meeting discussed three topics...",
"mindmap": "# Topic\n## Sub-topic 1"
}/api/tasks/{id}Обновить поля задачи. Все поля опциональны.
Тело запроса
| Поле | Тип | Описание |
|---|---|---|
| name | string | Новое имя (макс. 255) |
| folder | string|null | Имя папки (null удаляет задачу из папки) |
| duration | integer | Продолжительность в секундах |
| cost | integer | Стоимость в секундах |
| segments | array | Полный массив сегментов для замены |
| text | string | Полный текст транскрипции |
| quality | integer | Оценка качества (0-5) |
| index | integer | Индекс сортировки задачи |
Ответ 200
Возвращает полный объект задачи (то же, что и Детали задачи).
/api/tasks/{id}Response 200
{
"message": "Task deleted successfully"
}/api/tasks/bulkУдалить несколько задач за раз. Будут удалены только задачи, принадлежащие аутентифицированному пользователю. ID, не принадлежащие пользователю, игнорируются.
Тело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| ids | array | Yes | Массив ID задач для удаления (мин 1) |
Ответ 200
{
"message": "2 task(s) deleted successfully",
"deleted_count": 2
}/api/tasks/bulk/moveПереместить несколько задач в папку за раз. Будут перемещены только задачи, принадлежащие аутентифицированному пользователю.
Тело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| ids | array | Yes | Массив ID задач для перемещения (мин 1) |
| folder | string | Yes | Имя целевой папки (макс 255) |
Ответ 200
{
"message": "2 task(s) moved to Work",
"moved_count": 2
}Загрузки
Многочастная загрузка/api/uploads/signТело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| file | string | Yes | Имя файла (должен использоваться поддерживаемый формат) |
| content_type | string | Yes | MIME-тип (должен соответствовать расширению файла) |
| size | integer | Yes | Размер файла в байтах (макс. 2 147 483 648 / 2 ГБ) |
| duration | integer | No | Продолжительность аудио в секундах |
Ответ
{
"path": "2026-03-02/01HQX...mp3",
"upload_id": "abc123",
"part_size": 5242880,
"part_count": 10,
"expires_at": "2026-03-02T10:40:00+08:00"
}/api/uploads/sign-partТело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| path | string | Yes | Путь загрузки (макс. 2048) |
| upload_id | string | Yes | ID загрузки (макс. 2048) |
| part_number | integer | Yes | Номер части (1-10000) |
Ответ
{
"url": "https://storage.example.com/...?X-Amz-...",
"headers": {
"Content-Type": "audio/mpeg"
}
}Используйте PUT с возвращёнными URL и заголовками для загрузки части.
/api/uploads/completeЗавершить многочастную загрузку. Автоматически создаёт задачу и возвращает 403, если API недоступен или превышен лимит тарифа.
Тело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| path | string | Yes | Путь загрузки (макс. 2048) |
| upload_id | string | Yes | ID загрузки (макс. 2048) |
| original_name | string | Yes | Исходное имя файла (должен использоваться поддерживаемый формат) |
| content_type | string | Yes | MIME-тип (должен соответствовать расширению файла) |
| size | integer | Yes | Размер файла в байтах (макс. 2 ГБ) |
| name | string | No | Название задачи (по умолчанию имя файла без расширения) |
| duration | integer | No | Продолжительность в секундах (мин. 1) |
| speaker_diarization | boolean | Нет | app.tasks.speaker_diarization_api_description |
Ответ 201
{
"message": "File uploaded to the upload server successfully.",
"task": {
"id": 1,
"name": "meeting",
"path": "2026-03-02/01HQX...mp3",
"size": 50545869,
"status": "pending",
"speaker_diarization": true
}
}/api/uploads/abortТело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| path | string | Yes | Путь загрузки (макс. 2048) |
| upload_id | string | Yes | ID загрузки (макс. 2048) |
Ответ
{
"message": "Multipart upload cancelled successfully."
}Папки
На основе меток/api/foldersСписок всех папок с количеством задач.
Ответ
{
"folders": [
{"id": 1, "name": "Work", "count": 5},
{"id": 2, "name": "Personal", "count": 3}
],
"uncategorized_count": 2,
"total_count": 10
}/api/foldersТело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| name | string | Yes | Имя папки (макс. 14 символов / 7 китайских символов, уникально для пользователя) |
Ответ 201
{
"id": 1,
"name": "Work"
}/api/folders/{name}Тело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| name | string | Yes | Новое имя папки (те же ограничения, что при создании) |
Ответ 200
{
"id": 1,
"name": "New Name"
}/api/folders/{name}Response 200
{
"message": "Folder deleted successfully"
}Пользователь
/api/userОтвет
{
"id": 1,
"name": "Zhang San",
"email": "[email protected]",
"avatar": "https://...",
"balance": {
"used_seconds": 9000,
"remaining_seconds": 36000,
"allowance_remaining_seconds": 30000,
"top_up_remaining_seconds": 6000,
"total_seconds": 45000,
"usage_percent": 20
},
"subscription": {
"plan": "year",
"plan_key": "max_yearly",
"tier": "max",
"billing_interval": "yearly",
"active": true,
"access_tier": "max"
},
"queue": {
"pending_count": 1,
"running_count": 1,
"failed_count": 0
}
}Поля баланса
| Поле | Тип | Описание |
|---|---|---|
| used_seconds | int | Использовано секунд с последнего месячного начисления |
| remaining_seconds | int | Оставшиеся секунды |
| total_seconds | int | Всего секунд |
| usage_percent | int | Процент использования (0-100) |
/api/userТело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| name | string | No | Отображаемое имя (макс. 255) |
| string | Нет | Новый email (должен быть уникальным) | |
| avatar | file | No | Файл изображения (макс. 5 МБ) |
Ответ 200
{
"id": 1,
"name": "New Name",
"email": "[email protected]",
"avatar": "https://..."
}Уведомления
/api/notificationsПолучить 10 последних уведомлений.
Ответ
[
{
"id": "abc123",
"title": "Task Completed",
"message": "Meeting Recording has been transcribed.",
"read_at": null,
"created_at": "2026-03-02T10:45:00+08:00"
}
]/api/notifications/mark-all-as-readОтметить все непрочитанные уведомления как прочитанные.
Response 200
{
"success": true
}Оплата
/api/checkout/{plan}Получить URL оформления заказа Paddle для тарифного плана.
Параметры пути
| Параметр | Описание |
|---|---|
| plan | test / month / year |
Ответ
Возвращает объект параметров оформления заказа Paddle. Возвращает 404 для недействительного тарифа.
/api/healthПубличный эндпоинт проверки работоспособности. Не требует аутентификации.
Ответ 200
{
"status": "ok"
}
/api/auth/social-loginАутентификация через Google OAuth. Создаёт аккаунт, если его нет.
Тело запроса
googleподдерживаемые провайдерыОтвет 200