# Ask a question about a transcript and get the answer
Source: https://docs.vook.ai/api-reference/chats-api-v1/ask-a-question-about-a-transcript-and-get-the-answer
/api-reference/openapi.json post /api/v1/transcriptions/{id}/chats
You send a free-text prompt that runs against the transcription and get the answer back in the same response. The exchange is saved as a chat so you can list and retrieve it later. Next: GET the chat by its id to read the answer again.
# Get a single chat, including its answer
Source: https://docs.vook.ai/api-reference/chats-api-v1/get-a-single-chat-including-its-answer
/api-reference/openapi.json get /api/v1/transcriptions/{id}/chats/{chat_id}
# List the chats for a transcription
Source: https://docs.vook.ai/api-reference/chats-api-v1/list-the-chats-for-a-transcription
/api-reference/openapi.json get /api/v1/transcriptions/{id}/chats
# Create a transcription job from an uploaded file
Source: https://docs.vook.ai/api-reference/transcription-jobs-api-v1/create-a-transcription-job-from-an-uploaded-file
/api-reference/openapi.json post /api/v1/transcription-jobs
# Get a transcription job by ID
Source: https://docs.vook.ai/api-reference/transcription-jobs-api-v1/get-a-transcription-job-by-id
/api-reference/openapi.json get /api/v1/transcription-jobs/{id}
# List the API key owner's transcription jobs
Source: https://docs.vook.ai/api-reference/transcription-jobs-api-v1/list-the-api-key-owners-transcription-jobs
/api-reference/openapi.json get /api/v1/transcription-jobs
# Export a transcription in the requested format
Source: https://docs.vook.ai/api-reference/transcriptions-api-v1/export-a-transcription-in-the-requested-format
/api-reference/openapi.json get /api/v1/transcriptions/{id}/export
# Get a transcription by ID
Source: https://docs.vook.ai/api-reference/transcriptions-api-v1/get-a-transcription-by-id
/api-reference/openapi.json get /api/v1/transcriptions/{id}
# Get the transcript text for a transcription
Source: https://docs.vook.ai/api-reference/transcriptions-api-v1/get-the-transcript-text-for-a-transcription
/api-reference/openapi.json get /api/v1/transcriptions/{id}/transcript
# List the API key owner's transcriptions
Source: https://docs.vook.ai/api-reference/transcriptions-api-v1/list-the-api-key-owners-transcriptions
/api-reference/openapi.json get /api/v1/transcriptions
# Mint a single-use upload token for a file
Source: https://docs.vook.ai/api-reference/uploads-api-v1/mint-a-single-use-upload-token-for-a-file
/api-reference/openapi.json post /api/v1/uploads/init
# Authentication
Source: https://docs.vook.ai/authentication
Mint a Vook API key and send it as a Bearer token on every request.
The Vook API authenticates with an API key. You mint keys from the Vook web app,
then send the key as a Bearer token on every request.
## Mint a key
You create keys from the **API Keys** page in the Vook web app, so there is nothing to
deploy or configure first. Your account must have API access enabled. Give the
key a name, and the app shows you a `vk_live_…` value **once**. Copy it
immediately and store it somewhere safe, since you cannot retrieve it again.
Open the API Keys page in the Vook web app to create and manage your keys.
## Store the key
Export the key as an environment variable so the examples in these guides can
read it:
```bash theme={null}
export VOOK_API_KEY=vk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
## Send the key
Send the key as a Bearer token in the `Authorization` header on every request:
```bash theme={null}
curl https://www.api.vook.ai/api/v1/transcriptions \
-H "Authorization: Bearer $VOOK_API_KEY"
```
## Key lifecycle
* Keys expire **one year** after they are created.
* Revoke a key at any time from the **API Keys** page in the web app.
* A revoked or expired key is rejected on the next request, so mint a new one to
continue.
Treat `vk_live_…` keys like passwords. Do not commit them to source control or
expose them in client-side code. If a key leaks, revoke it and mint a new one.
# Chat with a transcript
Source: https://docs.vook.ai/chat
Ask questions about a transcription and get answers grounded in its content.
Chat lets you ask a question about a transcription and get an answer drawn from
what was said. You send a prompt, and Vook's AI answers using the transcript as
its source: summaries, action items, decisions, or anything else the recording
covers. Each exchange is saved against the transcription so you can list and
revisit it later.
The base URL is `https://www.api.vook.ai/api/v1`. Chat runs against an existing
transcription, so you need a transcription `id` whose transcript is ready
(`has_transcription` is `true`). See [Retrieve and export](/retrieve-export)
to find one, or [Transcribe a file](/upload) to create one.
## Before you start
Mint an API key (see [Authentication](/authentication)) and export it:
```bash theme={null}
export VOOK_API_KEY=vk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
The Python examples use the `requests` package (`pip install requests`).
## 1. Ask a question
Send a `title` and a `prompt` to the transcription's `chats` collection. The
`title` is a short label you will see when listing chats; the `prompt` is the
question or instruction to run against the transcript.
```bash curl theme={null}
curl -X POST "https://www.api.vook.ai/api/v1/transcriptions/$ID/chats" \
-H "Authorization: Bearer $VOOK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Summary",
"prompt": "Summarize this transcript in two sentences."
}'
```
```python Python theme={null}
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}/transcriptions/{transcription_id}/chats",
headers=headers,
json={
"title": "Summary",
"prompt": "Summarize this transcript in two sentences.",
},
)
resp.raise_for_status()
chat = resp.json()
print(chat["answer"])
```
The response is the chat, with its `answer`:
```json theme={null}
{
"id": "a35f053f-0ef3-4022-9530-00d35e193605",
"transcription_id": "4d039fef-0be2-4283-9834-7dd43c70652e",
"title": "Summary",
"prompt": "Summarize this transcript in two sentences.",
"answer": "The speaker spent three months at Princess Boot Camp. They learned to ride a horse, waltz, and sing.",
"created_at": "2024-01-15T10:30:00.000Z"
}
```
The request body fields are:
| Field | Required | Description |
| -------- | -------- | -------------------------------------------------------- |
| `title` | yes | Short label for the exchange, shown when you list chats. |
| `prompt` | yes | Question or instruction to run against the transcript. |
The `answer` is usually ready in the response. If it comes back `null`, the
answer is still being prepared, so re-request the chat by its `id` (see
[step 3](#3-read-a-single-chat)) until `answer` is set.
## 2. List the chats
Retrieve every chat saved against a transcription, newest first. Each item
carries its `id`, `title`, and `created_at`. Fetch a chat by `id` to read its
full `prompt` and `answer`.
```bash curl theme={null}
curl "https://www.api.vook.ai/api/v1/transcriptions/$ID/chats" \
-H "Authorization: Bearer $VOOK_API_KEY"
```
```python Python theme={null}
resp = requests.get(
f"{BASE}/transcriptions/{transcription_id}/chats", headers=headers
)
resp.raise_for_status()
for c in resp.json()["data"]:
print(c["id"], c["title"])
```
```json theme={null}
{
"data": [
{
"id": "a35f053f-0ef3-4022-9530-00d35e193605",
"transcription_id": "4d039fef-0be2-4283-9834-7dd43c70652e",
"title": "Summary",
"created_at": "2024-01-15T10:30:00.000Z"
}
]
}
```
## 3. Read a single chat
Fetch one chat by its `id` to read its `prompt` and `answer`. Use this to pick
up an earlier exchange, or to check for an `answer` that was not yet set when you
created the chat.
```bash curl theme={null}
curl "https://www.api.vook.ai/api/v1/transcriptions/$ID/chats/$CHAT_ID" \
-H "Authorization: Bearer $VOOK_API_KEY"
```
```python Python theme={null}
resp = requests.get(
f"{BASE}/transcriptions/{transcription_id}/chats/{chat_id}", headers=headers
)
resp.raise_for_status()
chat = resp.json()
if chat["answer"] is not None:
print(chat["answer"])
```
## Next steps
List, read, and export your transcriptions.
Try every endpoint interactively in the playground.
# Overview
Source: https://docs.vook.ai/introduction
Transcribe audio and video, then retrieve and export the results with a single API key.
The Vook API lets you work with your transcriptions programmatically: upload a
file to transcribe, list your transcriptions, check their status, read the
transcript text, and download exports, using only an API key.
## Base URL
All requests target the versioned public surface under `/api/v1`:
```
https://www.api.vook.ai/api/v1
```
## Authentication
Every request authenticates with an API key sent as a Bearer token:
```bash theme={null}
Authorization: Bearer $VOOK_API_KEY
```
Keys look like `vk_live_…`. See [Authentication](/authentication) for how to
mint and revoke them.
## Requirements
The examples in these guides use `curl` and Python. The Python snippets require
**Python 3.8+** and the [`requests`](https://pypi.org/project/requests/) package:
```bash theme={null}
pip install requests
```
## Next steps
Upload a file and turn it into a transcription.
List a transcription, read its text, and download an export.
Mint a `vk_live_…` key and send it on every request.
# Quickstart
Source: https://docs.vook.ai/quickstart
Go from an audio or video file to a finished transcript with the Vook API.
The Vook API turns your audio and video into transcripts and gives you the
results back as structured text or ready-to-share files. You can run the whole
flow with an API key alone.
The base URL is `https://www.api.vook.ai/api/v1`. The file upload step uses a
separate host, documented in [Transcribe a file](/upload).
## The path
There are two stages: send a file for transcription, then read the result.
Mint an API key (see [Authentication](/authentication)) and send it as a
Bearer token on every request:
```bash theme={null}
export VOOK_API_KEY=vk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
Mint an upload token, send the file, then start a transcription job and poll
it until the transcript is ready. Full walkthrough in
[Transcribe a file](/upload).
List your transcriptions, check status, read the transcript text, and
download an export. Full walkthrough in
[Retrieve and export](/retrieve-export).
## Next steps
Create a transcription from your own audio or video.
List, read, and export your transcriptions.
Try every endpoint interactively in the playground.
Manage your `vk_live_…` keys.
# Retrieve and export
Source: https://docs.vook.ai/retrieve-export
List your transcriptions, check status, read the transcript, and download an export.
Once a transcription is ready, the API lets you list what you have, check a
transcription's status, fetch its text, and download an export. Every request
uses your API key as a Bearer token.
The base URL is `https://www.api.vook.ai/api/v1`. To create a transcription
from your own file, see [Transcribe a file](/upload).
## Before you start
Mint an API key (see [Authentication](/authentication)) and export it:
```bash theme={null}
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`.
```bash curl theme={null}
curl "https://www.api.vook.ai/api/v1/transcriptions" \
-H "Authorization: Bearer $VOOK_API_KEY"
```
```python Python theme={null}
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:
```json theme={null}
{
"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": null
}
],
"totalCount": 100,
"currentPage": 1,
"lastPage": 10
}
```
Page through results with the `page` and `page_size` query parameters, or narrow
the list with `search`.
## 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`).
```bash curl theme={null}
curl "https://www.api.vook.ai/api/v1/transcriptions/$ID" \
-H "Authorization: Bearer $VOOK_API_KEY"
```
```python Python theme={null}
resp = requests.get(f"{BASE}/transcriptions/{transcription_id}", headers=headers)
resp.raise_for_status()
t = resp.json()
print(t["status"], "ready:", t["has_transcription"])
```
The `status` field reflects where your transcription is in its lifecycle:
| Status | Meaning |
| ------------ | -------------------------------------- |
| `queued` | Accepted, waiting to be processed. |
| `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. If the transcript
is not ready yet, `plain_text` and `transcription` come back `null`, so check for
a non-null value before using the response.
```bash curl theme={null}
curl "https://www.api.vook.ai/api/v1/transcriptions/$ID/transcript" \
-H "Authorization: Bearer $VOOK_API_KEY"
```
```python Python theme={null}
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"])
```
```json theme={null}
{
"plain_text": "Hello world. This is a transcript.",
"word_count": 1250,
"transcription": [
{
"speakerKey": "SPEAKER_00",
"startTimeSeconds": 0,
"children": [
{
"text": "Hello world. This is a transcript.",
"startTimeSeconds": 0.8,
"endTimeSeconds": 3.4
}
]
}
]
}
```
`plain_text` is the full transcript as a single string. `transcription` is the
same content split into paragraphs, each with a `speakerKey` and a list of timed
`children` text segments.
## 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.
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. |
```bash curl theme={null}
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
```
```python Python theme={null}
resp = requests.get(
f"{BASE}/transcriptions/{transcription_id}/export",
headers=headers,
params={
"format": "pdf",
"show_timestamps": "true",
"show_speakers": "true",
},
)
resp.raise_for_status()
with open("transcript.pdf", "wb") as f:
f.write(resp.content)
```
`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.
## Next steps
Create a transcription from your own audio or video.
Ask questions and get answers grounded in the transcript.
Try every endpoint interactively in the playground.
# Transcribe a file
Source: https://docs.vook.ai/upload
Upload an audio or video file and turn it into a transcription with three API calls.
This guide walks through creating a transcription from your own file. You mint a
short-lived upload token, send the file to the upload host, then start a
transcription job and poll it until the transcript is ready.
Two hosts are involved. The main API is `https://www.api.vook.ai/api/v1`. The
file upload in step 2 goes to a separate upload host,
`https://ingress.vook.ai`. Every request still authenticates with a Bearer
token.
## Before you start
Mint an API key (see [Authentication](/authentication)) and export it:
```bash theme={null}
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_token` for this upload. |
| 2 | `POST https://ingress.vook.ai/upload` | The file bytes are stored. |
| 3 | `POST /api/v1/transcription-jobs` | A job `id` to poll. |
Then poll the job until it completes and read each transcription it produced.
## 1. Get an upload token
Request a short-lived `upload_token`. You send this token with the file in the
next step and again when you create the job.
```bash curl theme={null}
curl -X POST "https://www.api.vook.ai/api/v1/uploads/init" \
-H "Authorization: Bearer $VOOK_API_KEY"
```
```python Python theme={null}
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()
upload_token = resp.json()["upload_token"]
```
```json theme={null}
{
"upload_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
## 2. Upload the file
Send the file to the upload host as `multipart/form-data` in a single request.
Authenticate this request with the **`upload_token`** from step 1, not your API
key.
```bash curl theme={null}
curl -X POST "https://ingress.vook.ai/upload" \
-H "Authorization: Bearer $UPLOAD_TOKEN" \
-F "chunk=@meeting.mp3"
```
```python Python theme={null}
INGRESS = "https://ingress.vook.ai"
upload_headers = {"Authorization": f"Bearer {upload_token}"}
with open("meeting.mp3", "rb") as f:
resp = requests.post(
f"{INGRESS}/upload",
headers=upload_headers,
files={"chunk": f},
)
resp.raise_for_status()
```
The fields are:
| Field | Where | Description |
| --------------- | --------- | ------------------------ |
| `chunk` | form file | The raw file bytes. |
| `Authorization` | header | `Bearer {upload_token}`. |
A success returns `201` with an empty JSON body (`{}`). You can ignore it.
```json theme={null}
{}
```
## 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`.
```bash curl theme={null}
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"
}'
```
```python Python theme={null}
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"]
```
```json theme={null}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "queued"
}
```
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`. |
| `diarize` | yes | Set `true` to separate speakers. |
| `name` | no | Display name for the resulting transcription. |
## 4. Poll the job
Poll the job by `id` until its `status` is `completed`. When it finishes, the
`transcription_ids` array holds the transcriptions it produced.
```bash curl theme={null}
curl "https://www.api.vook.ai/api/v1/transcription-jobs/$JOB_ID" \
-H "Authorization: Bearer $VOOK_API_KEY"
```
```python Python theme={null}
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", "partial", "failed"):
break
time.sleep(5)
transcription_ids = job["transcription_ids"]
```
```json theme={null}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "completed",
"name": "Team weekly sync",
"language": "en",
"diarize": false,
"transcription_ids": ["123e4567-e89b-12d3-a456-426614174000"],
"error_code": null,
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:30:00.000Z"
}
```
The `status` field reflects where the job is in its lifecycle:
| Status | Meaning |
| ------------ | ---------------------------------------------------------- |
| `queued` | Accepted, waiting to be processed. |
| `processing` | The job is running. |
| `completed` | Finished; `transcription_ids` is ready. |
| `partial` | Finished with some transcriptions produced and others not. |
| `failed` | The job did not produce a transcription. |
When the job ends as `partial` or `failed`, `error_code` carries a short code
describing the cause.
## 5. Read the result
Each id in `transcription_ids` is a regular transcription. Read it with the
endpoints from [Retrieve and export](/retrieve-export): fetch its status and
metadata, get the transcript text, or download an export.
```python Python theme={null}
for transcription_id in transcription_ids:
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"])
```
## Next steps
Read a transcript and download an export.
Try every endpoint interactively in the playground.