Skip to main content
POST
Transcribe a video asynchronously (long videos)
Transcribe an online video of any length. The job runs in the background: you get a task_id immediately, then collect the transcript by polling or through a webhook.
Use this endpoint instead of POST /transcribe for media longer than 10 minutes, which the synchronous endpoint rejects with video_too_long. It also works for short videos, so it is the safe default when you don’t know the duration.

How It Works

1

Submit the job

POST /transcribe/async with the same body as POST /transcribe, plus an optional webhook_url. You get 202 Accepted with a task_id and a check_status_url.
2

Wait for the result

Poll GET /transcribe/{task_id} every few seconds while task_status is processing — polling is free — or receive a webhook when the job finishes.
3

Read the result

On completed, data.result is identical to the synchronous response’s data block, so the same parsing code works for both. On failed, data.error carries the same error code the synchronous endpoint would have returned.

Billing

Billed exactly like POST /transcribe — the async mode costs nothing extra. Charges are made in the background worker, so pass include_usage=true on the result request (not on the submit) to see them. A failed job has all of its charges reverted.

Submit the job

POST https://api.vidnavigator.com/v1/transcribe/async
include_usage is not accepted on the submit request — pass it on the poll request instead.

Response (202 Accepted)

Get the result

The playground above only covers the submit request. Call the result endpoint with cURL or your HTTP client.
GET https://api.vidnavigator.com/v1/transcribe/{task_id} Polling is free. Poll every few seconds while task_status is processing. Results are kept for 1 hour after the job finishes, and reading a task doesn’t delete it.
cURL
On completed, data.result is identical to the data block of the synchronous response (video_info + transcript, or carousel_info + videos when all_videos=true).
On failed, data.result is null and data.error carries the same code the synchronous endpoint would have returned, e.g. { "error": "transcript_not_available", "message": "...", "http_status": 404 }. All charges are reverted.

Webhook

Pass webhook_url on the submit request, or configure a default endpoint in Studio → API, to be called back when the job finishes. See Webhooks for the payload and signature verification, and Async Jobs for the full workflow.

Authorizations

X-API-Key
string
header
required

API key authentication. Include your VidNavigator API key in the X-API-Key header.

Body

application/json
video_url
string<uri>
required

URL of the video to transcribe. For Instagram carousel posts, append ?img_index=N to select a specific video.

Example:

"https://www.youtube.com/watch?v=long-podcast"

transcript_text
boolean
default:false

When true, returns the transcript as a single plain-text string instead of an array of segments.

all_videos
boolean
default:false

For Instagram carousel posts only. When true, transcribes ALL videos in the post.

webhook_url
string<uri>

Where to POST the result when the job finishes. Overrides the account-level default configured in Studio → API. Pass an empty string to opt this job out of that default. Must be a publicly reachable https URL — private, loopback and link-local hosts are rejected. See https://docs.vidnavigator.com/guides/webhooks

Example:

"https://example.com/hooks/vidnavigator"

Response

Job accepted and started.

202 response from an async submit endpoint.

status
enum<string>
Available options:
success
data
object