Transcribe from a URL

If your file is already reachable over https, for example behind a presigned object URL, you can send its link directly. Vook fetches the file for you, so you create the job in one call and skip the upload steps. To send a file from your machine instead, see Transcribe from a file.

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. Create the transcription job

Pass the file’s direct https link as url. 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 '{
    "url": "https://example.com/recordings/meeting.mp3",
    "language": "en",
    "diarize": false,
    "name": "Team weekly sync"
  }'

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}/transcription-jobs",
    headers=headers,
    json={
        "url": "https://example.com/recordings/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 follow the job.
`status`	string	Job lifecycle status. See Poll the job.

The request body fields are:

Field	Required	Description
`url`	yes	Direct https link to an audio or video file, up to 2048 characters.
`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.
`file_name`	no	Original file name.
`name`	no	Display name for the resulting transcription. Defaults to `file_name`, then to the last segment of the `url` path (for example `meeting.mp3`).
`callback_url`	no	Endpoint to notify when the job finishes. See Webhooks.

The link is checked before the job is created. If it does not point to reachable media, the request answers with an error code starting with url_. A 400 means you need to fix the URL; a 502 or 504 means you can retry later. See Errors and limits for each code. If your account has no credit left for this request, it returns 402 with the error code insufficient_api_credits.

2. Follow the job and read the result

From here the job behaves exactly like one created from an uploaded file:

Poll GET /api/v1/transcription-jobs/{id} until status is completed or failed. See Poll the job.
Or get notified by passing a callback_url. See Webhooks.
Read the transcript from GET /api/v1/transcription-jobs/{id}/transcript or download an export. See Read the result.

Vook API

API Reference

Transcribe from a URL

Before you start

1. Create the transcription job

2. Follow the job and read the result

Next steps

Webhooks

Retrieve and export

​Before you start

​1. Create the transcription job

​2. Follow the job and read the result

​Next steps

Webhooks

Retrieve and export

Before you start

1. Create the transcription job

2. Follow the job and read the result

Next steps