Transcribe from a file

This guide walks through creating a transcription from a file on your machine. You get an upload URL and a short-lived token, send the file, then start a transcription job and follow it until the transcript is ready. If your file is already reachable over https, transcribe from a URL instead.

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).

The flow at a glance

Step	Call	What you get
1	`POST /api/v1/uploads/init`	An `upload_url` and an `upload_token`.
2	`POST {upload_url}`	The file is stored, and you get its `size_bytes`.
3	`POST /api/v1/transcription-jobs`	A job `id` to follow.

Then poll the job, or receive a webhook, and read its transcript.

1. Get an upload URL and token

Request where to send the file and a short-lived upload_token. You send this token with the file in the next step and again when you create the job.

curl -X POST "https://www.api.vook.ai/api/v1/uploads/init" \
  -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.post(f"{BASE}/uploads/init", headers=headers)
resp.raise_for_status()
init = resp.json()
upload_url = init["upload_url"]
upload_token = init["upload_token"]

{
  "upload_url": "https://ingress.vook.ai/upload",
  "upload_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-01-15T10:30:00.000Z"
}

Field	Type	Description
`upload_url`	string	Absolute URL to send the file to in step 2. Use it as returned.
`upload_token`	string	Token scoped to this upload. Used in steps 2 and 3.
`expires_at`	string	When the token expires, as an ISO 8601 timestamp. Start the upload before this time; an upload already in flight completes normally.

2. Upload the file

Send the file to upload_url as multipart/form-data in a single request. Authenticate this request with the upload_token from step 1, not your API key.

curl -X POST "$UPLOAD_URL" \
  -H "Authorization: Bearer $UPLOAD_TOKEN" \
  -F "chunk=@meeting.mp3" \
  --progress-bar -o upload-response.json

upload_headers = {"Authorization": f"Bearer {upload_token}"}

with open("meeting.mp3", "rb") as f:
    resp = requests.post(
        upload_url,
        headers=upload_headers,
        files={"chunk": f},
    )
resp.raise_for_status()

Large files take a while to send, and the request returns only once the whole file is stored. Give it a generous timeout, so a large upload is not cut off before it completes. To show progress while it runs, track the bytes sent on your side, as the curl example does with --progress-bar. The fields are:

Field	Where	Description
`chunk`	form file	The raw file bytes.
`Authorization`	header	`Bearer {upload_token}`.

A successful upload returns 201:

{
  "size_bytes": 52428800
}

Field	Type	Description
`size_bytes`	number	Size of the stored file, in bytes.

A 2xx status means the file is stored. Wait for this response before you create the job in step 3. If the upload does not succeed, the response uses the same error body as the rest of the API:

Status	Code	Next step
`401`	`unauthorized`	The `upload_token` was not accepted. Get a new one from step 1 and upload again.
`413`	`upload_too_large`	The file is above the 6 GB limit. Send a file of 6 GB or less.
`502`	`upload_failed`	The file was not stored. Upload it again with the same `upload_token`.

3. Create the transcription job

Start the transcription. Pass the upload_token and the file details. The response gives you a job id and its status.

curl -X POST "https://www.api.vook.ai/api/v1/transcription-jobs" \
  -H "Authorization: Bearer $VOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_token": "'"$UPLOAD_TOKEN"'",
    "file_name": "meeting.mp3",
    "language": "en",
    "diarize": false,
    "name": "Team weekly sync"
  }'

resp = requests.post(
    f"{BASE}/transcription-jobs",
    headers=headers,
    json={
        "upload_token": upload_token,
        "file_name": "meeting.mp3",
        "language": "en",
        "diarize": False,
        "name": "Team weekly sync",
    },
)
resp.raise_for_status()
job_id = resp.json()["id"]

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "queued"
}

Field	Type	Description
`id`	string	Transcription job ID. Use it to poll the job.
`status`	string	Job lifecycle status. See Poll the job.

If the response does not reach you, send the same request again. The same upload_token returns the same job id, so a retry never creates a second job. The request body fields are:

Field	Required	Description
`upload_token`	yes	The token from step 1.
`file_name`	yes	The original file name.
`language`	yes	Spoken language code, for example `en` or `fr`. Send `auto` to detect it; the transcription then reports the detected code.
`diarize`	yes	Set `true` to separate speakers.
`name`	no	Display name for the resulting transcription. Defaults to `file_name`.
`callback_url`	no	Endpoint to notify when the job finishes. See Webhooks.

If your account has no credit left for this request, it returns 402 with the error code insufficient_api_credits. Top up, then send the request again. If no file is stored for the upload_token, for example because step 2 did not complete, the request returns 409 with the error code upload_not_found. No job is created and the token stays valid. Finish the upload, wait for its 201, then send this request again with the same token.

4. Poll the job

Poll the job by id until its status is completed or failed. To be notified instead, pass a callback_url and see Webhooks.

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

import time

while True:
    resp = requests.get(f"{BASE}/transcription-jobs/{job_id}", headers=headers)
    resp.raise_for_status()
    job = resp.json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(5)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "completed",
  "name": "Team weekly sync",
  "language": "en",
  "diarize": false,
  "transcription_id": "123e4567-e89b-12d3-a456-426614174000",
  "callback_url": null,
  "error_code": null,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

Field	Type	Description
`id`	string	Transcription job ID.
`status`	string	Job lifecycle status. See the table below.
`name`	string or `null`	Display name for the job.
`language`	string	Language code as you sent it. Reads `auto` when you asked for detection; the transcription carries the detected code.
`diarize`	boolean	Whether you requested speaker separation.
`transcription_id`	string or `null`	The transcription this job produced. `null` until the job reaches `processing`.
`callback_url`	string or `null`	The webhook endpoint you submitted, or `null` when the job was created without one.
`error_code`	string or `null`	Why the job failed, when `status` is `failed`. See Job error codes.
`created_at`	string	When the job was created, as an ISO 8601 timestamp.
`updated_at`	string	When the job was last updated, as an ISO 8601 timestamp.

The status field reflects where the job is in its lifecycle:

Status	Meaning
`queued`	Accepted, waiting to be processed.
`processing`	The job is running. `transcription_id` is set from this point.
`completed`	Finished; the transcript is ready.
`failed`	The job did not produce a transcript. `error_code` carries a short code describing the cause.

5. Read the result

Once the job is completed, read its transcript straight from the job:

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

resp = requests.get(
    f"{BASE}/transcription-jobs/{job_id}/transcript", headers=headers
)
resp.raise_for_status()
print(resp.json()["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.

The job also has an export endpoint, GET /api/v1/transcription-jobs/{id}/export, which takes the same query parameters as the transcription export. Both job endpoints return 409 with job_not_completed while the job is still running, or job_failed if it ended without a transcript. The job’s transcription_id is also a regular transcription. Use it with the endpoints from Retrieve and export to read its metadata or list it alongside your other transcriptions.

Delete the result

To delete the transcription a job produced, call DELETE /api/v1/transcription-jobs/{id}. It returns 204 when the transcription is deleted, or when the job has none to delete. A job that is still running returns 409; wait for it to finish, then retry.

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

Vook API

API Reference

Transcribe from a file

Before you start

The flow at a glance

1. Get an upload URL and token

2. Upload the file

3. Create the transcription job

4. Poll the job

5. Read the result

Delete the result

Next steps

Webhooks

Retrieve and export

​Before you start

​The flow at a glance

​1. Get an upload URL and token

​2. Upload the file

​3. Create the transcription job

​4. Poll the job

​5. Read the result

​Delete the result

​Next steps

Webhooks

Retrieve and export

Before you start

The flow at a glance

1. Get an upload URL and token

2. Upload the file

3. Create the transcription job

4. Poll the job

5. Read the result

Delete the result

Next steps