Основные понятияТранскрипции

Транскрипции

Транскрипция — это один аудио- или видеоисточник, обработанный QuillAI: от момента отправки, через распознавание речи и опциональную структуризацию, до готового текста, сегментов и субтитров, которые вы получаете обратно.

Жизненный цикл

Каждая Транскрипция проходит через небольшой набор состояний. Новые задачи стартуют в queued, переходят в processing, когда их подхватывает воркер, и завершаются одним из трёх терминальных состояний: completed, failed или cancelled.

queued

Принята и ждёт воркера.

processing

Идёт загрузка, распознавание или структуризация.

completed

Успешно завершена. Поле result заполнено.

failed

Остановлена ошибкой. См. поле error.

cancelled

Вы отменили её через DELETE до завершения.

Поинты списываются только когда Транскрипция достигает статуса completed. Задачи failed и cancelled бесплатны.

Объект Transcription

Ниже — полностью заполненная Транскрипция в статусе completed, которую возвращает GET /v1/transcriptions/{id}.

transcription.jsonjson

{
  "id": "trs_01HZXK9P2Q7R8S4T5V6W7X8Y9Z",
  "status": "completed",
  "progress": 1,
  "source": {
    "type": "youtube",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "options": {
    "speaker_recognition": true,
    "structure": true
  },
  "duration_seconds": 842,
  "points_spent": 28,
  "result": {
    "text": "Welcome back to the channel. Today we're talking about...",
    "segments": [
      { "start": 0.12, "end": 3.48, "text": "Welcome back to the channel.", "speaker": "Speaker 1" },
      { "start": 3.48, "end": 7.92, "text": "Today we're talking about distributed systems.", "speaker": "Speaker 1" }
    ],
    "structured": {
      "title": "Distributed Systems in Practice",
      "summary": "A walkthrough of consensus, replication, and failure modes.",
      "toc": [{ "title": "Introduction", "start": 0 }, { "title": "Consensus", "start": 124 }],
      "paragraphs": [{ "start": 0, "end": 120, "text": "Welcome back to the channel..." }],
      "highlights": ["Consensus is the hardest part of distributed systems."],
      "terms": ["Paxos", "Raft", "CRDT"]
    },
    "subtitles": {
      "vtt": "https://storage.quillhub.ai/subtitles/abc.vtt",
      "srt": "https://storage.quillhub.ai/subtitles/abc.srt"
    }
  },
  "webhook_url": "https://example.com/hooks/quillai",
  "error": null,
  "metadata": { "project_id": "proj_42" },
  "created_at": "2026-04-23T10:14:22Z",
  "completed_at": "2026-04-23T10:17:55Z"
}

Поля верхнего уровня: id, status, progress, source, options, duration_seconds, language, points_spent, result, webhook_url, error, metadata, created_at и completed_at.

Справочник полей

Поле	Тип	Описание
`id`	string	Уникальный идентификатор с префиксом trs_.
`status`	enum	Одно из queued, processing, completed, failed, cancelled.
`progress`	number	Число от 0 до 1 — прогресс пайплайна.
`source`	object	Описание входа: type (youtube, instagram, direct, upload) и url.
`options`	object	Опции запроса: language, speaker_recognition, structure.
`duration_seconds`	number \| null	Длительность исходного аудио, как только она известна.
`language`	string \| null	Определённый или указанный ISO-639-1-код языка.
`points_spent`	number \| null	Списанные поинты при завершении. Null до терминального состояния.
`result`	object \| null	Текст, сегменты, структурированный вывод и субтитры. Null до completed.
`webhook_url`	string \| null	Адрес, куда мы POST'им обновления статуса, если указан при создании.
`error`	object \| null	Объект ошибки с code и message. Присутствует только при failed.
`metadata`	object \| null	Ваш произвольный объект ключ–значение, возвращается без изменений.
`created_at`	string	Временная метка создания в формате ISO 8601.
`completed_at`	string \| null	Временная метка терминального состояния ISO 8601. Иначе null.

Создание

Отправьте POST на /v1/transcriptions с полем url. API сразу отвечает 202 и возвращает Транскрипцию в статусе queued — обработка идёт в фоне. Полный пример — в Быстром старте.

create.shbash

curl -X POST https://api.quillhub.ai/v1/transcriptions \
  -H "Authorization: Bearer $QAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "speaker_recognition": true,
    "structure": true,
    "webhook_url": "https://example.com/hooks/quillai"
  }'

Список и пагинация

Список Транскрипций использует курсорную пагинацию. Передайте limit (до 100) и cursor, чтобы листать результаты. В ответе есть next_cursor, пока есть ещё страницы — передавайте его как cursor в следующем запросе. На последней странице next_cursor равен null.

list.shbash

curl "https://api.quillhub.ai/v1/transcriptions?limit=20&cursor=trs_01HZXK9P2Q7R8S4T5V6W7X8Y9Z" \
  -H "Authorization: Bearer $QAI_KEY"

# Response
{
  "data": [
    { "id": "trs_01J0A...", "status": "completed", "created_at": "..." },
    { "id": "trs_01J0B...", "status": "processing", "created_at": "..." }
  ],
  "next_cursor": "trs_01J0C..."
}

Получение

Получите одну Транскрипцию по ID. Именно этот эндпоинт стоит опрашивать, если вы не используете вебхуки.

retrieve.shbash

curl https://api.quillhub.ai/v1/transcriptions/trs_01HZXK9P2Q7R8S4T5V6W7X8Y9Z \
  -H "Authorization: Bearer $QAI_KEY"

Отмена

Отменить ещё не завершённую Транскрипцию. При успехе API возвращает 204 No Content, и задача переходит в cancelled.

cancel.shbash

curl -X DELETE https://api.quillhub.ai/v1/transcriptions/trs_01HZXK9P2Q7R8S4T5V6W7X8Y9Z \
  -H "Authorization: Bearer $QAI_KEY"

# 204 No Content

Отмена работает только до того, как Транскрипция достигнет completed. После завершения DELETE вернёт 409 Conflict.

Диаризация

Метки спикеров в result.segments.

Языки

Поддерживаемые языки и автоопределение.

Таймкоды

Границы сегментов, VTT и SRT.

Вебхуки

Уведомления о завершении Транскрипции.

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

Вперёд