Video transcription and notes API

Quickstart

These steps take a file from your disk to a transcript and notes. You need an active Basic or Plus plan, a terminal and, for the example client, Python 3.12 or later.

1. Create an API key

Sign in on the website (for example on the pricing page), open API keys in the account bar, name the key and, if you like, set an expiry date. Copy the secret when it appears: it is shown only once. Up to three keys can be active at a time.

2. Store the key in an environment variable

Keep the key out of source code, command-line arguments and logs. The examples read the key from VTN_API_KEY and the base URL from VTN_API_BASE.

export VTN_API_BASE="https://api.video-to-notes.com"
read -rs VTN_API_KEY && export VTN_API_KEY   # paste the key, press Enter

$env:VTN_API_BASE = "https://api.video-to-notes.com"
$env:VTN_API_KEY = Read-Host "API key" -MaskInput

3. Check your account

This call confirms that the key works and returns your plan, your remaining plan seconds, the supported formats and the current limits.

# Sends the key through stdin, so it never appears in the process list.
vtn() {
  printf 'header = "Authorization: Bearer %s"\n' "$VTN_API_KEY" |
    curl -s --config - "$@"
}

vtn "$VTN_API_BASE/api/v1/account"

$headers = @{ Authorization = "Bearer $env:VTN_API_KEY" }
Invoke-RestMethod "$env:VTN_API_BASE/api/v1/account" -Headers $headers |
  ConvertTo-Json -Depth 5

4. Transcribe a file

Download the Python example client. It needs only the standard library. It uploads the file in parts, starts the job, waits for it and saves every result page.

python client.py run meeting.mp4 --state meeting.state.json \
  --output meeting.jsonl --download meeting-files

To process only part of a recording, add --start and --end in seconds from the start of the file. --audio-language gives a language hint and --notes-language chooses the language of the notes. Without these options the whole file is processed and the languages are detected automatically.

python client.py run lecture.webm --state lecture.state.json \
  --start 30 --end 3630 --audio-language ru --notes-language en

The state file stores the upload ID and the request identity, never the key. If the command stops, run it again with the same state file: it recovers the same job and you are not charged twice. Use a new state file for each new job.

5. Read the results

meeting.jsonl holds one JSON result page per line: transcript text with timings, notes in Markdown, gaps and warnings. meeting-files holds the downloads, such as the transcript as TXT and the notes as Markdown, HTML and PDF. The client has these other commands:

python client.py account
python client.py status JOB_ID
python client.py result JOB_ID --output results.jsonl --download files
python client.py cancel JOB_ID
python client.py resume JOB_ID

Prefer curl? The Bash quickstart runs the same upload, job and result steps with curl and jq.

bash quickstart.sh meeting.mp4

How a job works

Every integration follows the same six steps. The API reference shows each call with a request and a response example.

1. Check the account. GET /api/v1/account returns your plan, remaining seconds, supported formats and limits.
2. Create an upload. POST /api/v1/uploads with the file size in bytes and the file extension. The response gives the part size and the number of parts.
3. Upload the parts. Get signed URLs from POST /api/v1/uploads/{upload_id}/parts, send each part with an HTTP PUT straight to storage, keep each ETag, then call POST /api/v1/uploads/{upload_id}/complete.
4. Start the job. POST /api/v1/jobs with the upload ID and an Idempotency-Key header. The server checks the real file, plans the work and reserves the time from your plan.
5. Poll the status. GET /api/v1/jobs/{job_id} until the state is final, waiting at least poll_after_seconds between calls.
6. Read the result. GET /api/v1/jobs/{job_id}/result and follow next_cursor until it is null. Download the files listed in artifacts before their links expire.

A job ends as completed, completed_with_gaps, interrupted, cancelled, failed or expired. charged_seconds shows how much of your plan the job used.

Best practices

These habits keep your keys safe, prevent double charges and make long jobs reliable.

Keep keys secret

• Call the API only from a server or a script you control. Never put a key in browser code, a mobile app, a URL or source control.
• Load the key from an environment variable or a secret manager, and keep it out of logs, error reports and command-line arguments.
• Use one key per integration and give it an expiry date, so you can rotate or revoke one key without touching the others.
• To rotate a key, create the new key, deploy it, then revoke the old one. Jobs that already started keep running.
• If a key may have leaked, for example in a chat, a ticket or a commit, revoke it right away in the API keys panel.

Make job creation safe to retry

• Generate a random Idempotency-Key, such as a UUID, for each new job and save it with the upload ID before you send the request.
• If the response is lost, send the same request with the same key again. You get the original job back and you are not charged twice.
• Never reuse a key for another file or other options: the API answers with 409 IDEMPOTENCY_CONFLICT.

Poll politely and handle limits

• Wait at least five seconds between status calls, and longer when poll_after_seconds asks for it.
• On 429 or 503, wait for the Retry-After header or error.retry_after_seconds, then retry with a little random jitter.
• Retry a request unchanged only when error.retryable is true. Otherwise fix the request first.
• An account runs one upload and one job at a time. Queue your files and send the next one when the current job is finished.

Control how many hours you use

• Check remaining_seconds before you upload. A job that needs more time than you have fails with INSUFFICIENT_BALANCE; the API never shortens your selection to make it fit.
• Send a range when you need only part of a recording. Only the selected audio is charged.
• Cancel jobs you no longer need. Finished parts stay available and reserved time that was not used is returned.
• Abort uploads you will not use, so that the next upload can start.

Collect complete results

• Follow next_cursor until it is null. A page holds at most 32 items.
• Treat gap items as audio that could not be processed, not as silence, and check the warnings.
• Download the files in artifacts while their links are valid (up to ten minutes); request the page again for fresh links.
• Save what you need: result files are kept for about 24 hours and transcript recovery for about 48 hours.
• Read the fields you need and ignore the rest.

Frequently asked questions

Files and examples

The examples and contract files are published with the site and match the live API.

• client.py: Python 3.12+ example client, standard library only
• quickstart.sh: Bash example with curl and jq
• openapi.json: OpenAPI 3.1 description of every endpoint, with examples
• paid-api.schema.json: JSON Schema of every request and response

Help

Something unclear or not working? Contact us and include the request_id from the error response, the time and the endpoint. Never send us your API key.