Core conceptsTranscriptions

Transcriptions

A Transcription represents a single audio or video source processed by QuillAI — from the moment you submit it, through transcription and optional structuring, to the final text, segments, and subtitles you can read back.

Lifecycle

Every Transcription moves through a small set of states. New jobs start in queued, advance to processing once a worker picks them up, and end in one of three terminal states: completed, failed, or cancelled.

queued

Accepted and waiting for a worker.

processing

Downloading, transcribing, or structuring.

completed

Finished successfully. result is populated.

failed

Stopped by an error. See the error field.

cancelled

You stopped it via DELETE before completion.

Points are deducted only when a Transcription reaches completed. Failed and cancelled jobs are free.

The Transcription object

Here is a fully populated Transcription in the completed state, returned from 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"
}

Top-level fields: id, status, progress, source, options, duration_seconds, language, points_spent, result, webhook_url, error, metadata, created_at, and completed_at.

Fields reference

Field	Type	Description
`id`	string	Unique identifier, prefixed with trs_.
`status`	enum	One of queued, processing, completed, failed, cancelled.
`progress`	number	Float between 0 and 1 reflecting pipeline progress.
`source`	object	Input descriptor: type (youtube, instagram, direct, upload) and url.
`options`	object	Request-time options: language, speaker_recognition, structure.
`duration_seconds`	number \| null	Duration of the source audio once known.
`language`	string \| null	Detected or specified ISO-639-1 language code.
`points_spent`	number \| null	Points charged on completion. Null until terminal.
`result`	object \| null	Transcript text, segments, structured output, and subtitles. Null until completed.
`webhook_url`	string \| null	Where we POST status updates, if provided on create.
`error`	object \| null	Error object with code and message. Present only on failed.
`metadata`	object \| null	Your own key–value map, echoed back unchanged.
`created_at`	string	ISO 8601 timestamp of creation.
`completed_at`	string \| null	ISO 8601 timestamp of terminal state. Null otherwise.

Creating

Send a POST to /v1/transcriptions with a url. The API responds 202 immediately with a queued Transcription — processing happens in the background. See the Quickstart for an end-to-end walkthrough.

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"
  }'

Listing and filtering

List your Transcriptions with cursor-based pagination. Pass limit (max 100) and cursor to page through results. The response includes next_cursor when more results are available — pass it as cursor on the next request. next_cursor is null on the final page.

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..."
}

Retrieving

Fetch a single Transcription by ID. This is the endpoint you poll if you are not using webhooks.

retrieve.shbash

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

Cancelling

Cancel a Transcription that has not finished yet. The API returns 204 No Content on success and the job transitions to cancelled.

cancel.shbash

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

# 204 No Content

Cancellation only works before the Transcription reaches completed. Once completed, DELETE returns 409 Conflict.

Diarization

Speaker labels in result.segments.

Languages

Supported languages and auto-detection.

Timestamps

Segment boundaries, VTT, and SRT.

Webhooks

Get notified when a Transcription finishes.

Authentication