Retrieve and export

Once a transcription is ready, the API lets you list what you have, check a transcription’s status, fetch its text, download an export, and delete it. Every request uses your API key as a Bearer token.

Before you start

Mint an API key (see Authentication) and export it:

export VOOK_API_KEY=vk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The Python examples use the requests package (pip install requests).

1. List your transcriptions

Fetch a paginated list of your transcriptions. The response includes each transcription’s id, name, and status. The list covers your whole account, including transcriptions you created in the Vook web app. To list only the work you submitted through the API, see List your transcription jobs.

curl "https://www.api.vook.ai/api/v1/transcriptions" \
  -H "Authorization: Bearer $VOOK_API_KEY"

import os, requests

BASE = "https://www.api.vook.ai/api/v1"
headers = {"Authorization": f"Bearer {os.environ['VOOK_API_KEY']}"}

resp = requests.get(f"{BASE}/transcriptions", headers=headers)
resp.raise_for_status()
for t in resp.json()["data"]:
    print(t["id"], t["status"], t["name"])

The response is paginated:

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Team weekly sync",
      "status": "completed",
      "language": "en",
      "diarize": true,
      "word_count": 1250,
      "submitted_at": "2024-01-15T10:30:00.000Z",
      "folder": {
        "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "name": "Client calls"
      }
    }
  ],
  "total_count": 100,
  "current_page": 1,
  "last_page": 10
}

Field	Type	Description
`data`	object[]	The transcriptions on this page.
`data[].id`	string	Transcription ID.
`data[].name`	string	Display name.
`data[].status`	string	Lifecycle status. See Check a transcription’s status.
`data[].language`	string or `null`	Spoken language code, when known. If you sent `auto`, reads `auto` until processing ends, then the detected code.
`data[].diarize`	boolean	Whether you requested speaker separation.
`data[].word_count`	number or `null`	Total word count, when available.
`data[].submitted_at`	string or `null`	When the transcription was submitted, as an ISO 8601 timestamp.
`data[].folder`	object or `null`	The folder the transcription belongs to, with its `id` and `name`, or `null`.
`total_count`	number	Total number of transcriptions across all pages.
`current_page`	number	The page returned.
`last_page`	number	The last page number.

Narrow the list with these optional query parameters:

Parameter	Description
`page`	Page number.
`page_size`	Items per page, a whole number from `1` to `100`. Defaults to `10`. Any other value returns `400 invalid_request`.
`search`	Free-text search over transcription names.
`in_progress`	Set to `true` to return only transcriptions still being processed.

List your transcription jobs

GET /api/v1/transcription-jobs lists only the jobs you submitted through the API. It takes the same query parameters as the transcription list and returns the same pagination fields, with one job per item. Read a job’s transcription_id with GET /api/v1/transcription-jobs/{id}.

curl "https://www.api.vook.ai/api/v1/transcription-jobs" \
  -H "Authorization: Bearer $VOOK_API_KEY"

resp = requests.get(f"{BASE}/transcription-jobs", headers=headers)
resp.raise_for_status()
for job in resp.json()["data"]:
    print(job["id"], job["status"], job["name"])

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "completed",
      "name": "Team weekly sync",
      "language": "en",
      "diarize": false,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:35:00.000Z"
    }
  ],
  "total_count": 100,
  "current_page": 1,
  "last_page": 10
}

Field	Type	Description
`data`	object[]	The jobs on this page.
`data[].id`	string	Transcription job ID.
`data[].status`	string	Job lifecycle status: `queued`, `processing`, `completed`, or `failed`. See Poll the job.
`data[].name`	string or `null`	Display name for the job.
`data[].language`	string	Language code as you sent it. Reads `auto` when you asked for detection.
`data[].diarize`	boolean	Whether you requested speaker separation.
`data[].created_at`	string	When the job was created, as an ISO 8601 timestamp.
`data[].updated_at`	string	When the job was last updated, as an ISO 8601 timestamp.
`total_count`	number	Total number of jobs across all pages.
`current_page`	number	The page returned.
`last_page`	number	The last page number.

2. Check a transcription’s status

Retrieve a single transcription by id to read its lifecycle status and whether its transcript is ready (has_transcription).

curl "https://www.api.vook.ai/api/v1/transcriptions/$ID" \
  -H "Authorization: Bearer $VOOK_API_KEY"

resp = requests.get(f"{BASE}/transcriptions/{transcription_id}", headers=headers)
resp.raise_for_status()
t = resp.json()
print(t["status"], "ready:", t["has_transcription"])

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Team weekly sync",
  "status": "completed",
  "language": "en",
  "has_transcription": true,
  "diarize": true,
  "speaker_count": 2,
  "word_count": 1250,
  "submitted_at": "2024-01-15T10:30:00.000Z",
  "created_at": "2024-01-15T10:30:00.000Z",
  "folder": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "name": "Client calls"
  }
}

Field	Type	Description
`id`	string	Transcription ID.
`name`	string	Display name.
`status`	string	Lifecycle status. See the table below.
`language`	string or `null`	Spoken language code, when known. If you sent `auto`, reads `auto` until processing ends, then the detected code.
`has_transcription`	boolean	`true` once the transcript is available to fetch and export.
`diarize`	boolean	Whether you requested speaker separation.
`speaker_count`	number or `null`	Number of detected speakers, when diarized.
`word_count`	number or `null`	Total word count, when available.
`submitted_at`	string or `null`	When the transcription was submitted, as an ISO 8601 timestamp.
`created_at`	string	When the transcription was created, as an ISO 8601 timestamp.
`folder`	object or `null`	The folder the transcription belongs to, with its `id` and `name`, or `null`.

The status field reflects where your transcription is in its lifecycle:

Status	Meaning
`processing`	Transcription is running.
`completed`	Finished; the transcript is available.
`empty`	Finished with no detected speech.
`failed`	Processing failed.

3. Fetch the transcript

Once has_transcription is true, fetch the transcript text.

curl "https://www.api.vook.ai/api/v1/transcriptions/$ID/transcript" \
  -H "Authorization: Bearer $VOOK_API_KEY"

resp = requests.get(
    f"{BASE}/transcriptions/{transcription_id}/transcript", headers=headers
)
resp.raise_for_status()
data = resp.json()
if data["plain_text"] is not None:
    print(data["plain_text"])

{
  "plain_text": "Hello world. This is a transcript.",
  "word_count": 1250,
  "transcription": [
    {
      "speaker_key": "SPEAKER_00",
      "start_time_seconds": 0,
      "children": [
        {
          "text": "Hello world.",
          "start_time_seconds": 0.8,
          "end_time_seconds": 1.9
        },
        {
          "text": "This is a transcript.",
          "start_time_seconds": 2.1,
          "end_time_seconds": 3.4
        }
      ]
    }
  ]
}

Field	Type	Description
`plain_text`	string or `null`	The full transcript as a single string. `null` on a transcription with no speech.
`word_count`	number or `null`	Total word count of the transcript. `null` when the count is not available, and always on a transcription with no speech.
`transcription`	object[] or `null`	The same content split into paragraphs. `null` on a transcription with no speech.
`transcription[].speaker_key`	string	Speaker of the paragraph. Present when you requested `diarize: true`.
`transcription[].start_time_seconds`	number	When the paragraph starts, in seconds.
`transcription[].children`	object[]	The paragraph’s timed text segments.
`transcription[].children[].text`	string	Text of the segment.
`transcription[].children[].start_time_seconds`	number	When the segment starts, in seconds.
`transcription[].children[].end_time_seconds`	number	When the segment ends, in seconds.

If the transcript is not ready yet, the request returns 409 with the error code job_not_completed. Wait for has_transcription to be true, then retry. On a transcription with no speech (status empty), the request returns 200 with plain_text set to null.

4. Download an export

Download the transcription as a ready-to-share file in the format you need. The endpoint returns the binary file, so write the response body to disk. Save the file with the extension of the format you requested. srt exports come back as text/plain. Three query parameters are required:

Parameter	Type	Description
`format`	string	Output format: `pdf`, `docx`, `srt`, `md`, or `html`.
`show_timestamps`	boolean	Include start timestamps in the export.
`show_speakers`	boolean	Include speaker labels in the export.

curl "https://www.api.vook.ai/api/v1/transcriptions/$ID/export?format=pdf&show_timestamps=true&show_speakers=true" \
  -H "Authorization: Bearer $VOOK_API_KEY" \
  -o transcript.pdf

resp = requests.get(
    f"{BASE}/transcriptions/{transcription_id}/export",
    headers=headers,
    params={
        "format": "pdf",
        "show_timestamps": "true",
        "show_speakers": "true",
    },
)
resp.raise_for_status()
if resp.status_code == 204:
    print("No speech detected, nothing to export.")
else:
    with open("transcript.pdf", "wb") as f:
        f.write(resp.content)

The export responds with:

Status	Meaning
`200`	The file, in the requested format.
`204`	The audio contained no speech, so there is nothing to export.
`409`	The transcript is not ready yet (`job_not_completed`).

show_timestamps and show_speakers are still required for an srt export, but they do not change the output: srt is a standard format that always carries timestamps and omits speaker labels.

5. Delete a transcription

Delete a transcription you no longer need by its id. A successful delete returns 204 with an empty body.

curl -X DELETE "https://www.api.vook.ai/api/v1/transcriptions/$ID" \
  -H "Authorization: Bearer $VOOK_API_KEY"

resp = requests.delete(f"{BASE}/transcriptions/{transcription_id}", headers=headers)
resp.raise_for_status()

If the job that produces the transcription is still running, the request returns 409. Wait for the job to finish, then retry.

Vook API

API Reference

Retrieve and export

Before you start

1. List your transcriptions

List your transcription jobs

2. Check a transcription’s status

3. Fetch the transcript

4. Download an export

5. Delete a transcription

Next steps

Transcribe from a file

API Reference

​Before you start

​1. List your transcriptions

​List your transcription jobs

​2. Check a transcription’s status

​3. Fetch the transcript

​4. Download an export

​5. Delete a transcription

​Next steps

Transcribe from a file

API Reference

Before you start

1. List your transcriptions

List your transcription jobs

2. Check a transcription’s status

3. Fetch the transcript

4. Download an export

5. Delete a transcription

Next steps