Analyze Video (Async)
Queue a video analysis and return a task_id immediately.
Use this instead of POST /analyze/video when include_scenes is set on anything longer than ~10 minutes.
Accepts the same body as POST /analyze/video, plus webhook_url.
include_usage is not accepted here: pass it on GET /analyze/video/{task_id} once task_status=completed.
See https://docs.vidnavigator.com/guides/async-jobs
Submit-time check: the submit endpoint returns 402 instead of a task_id when the account has almost no credits left. A job can still fail later with 402 when the video needs more than the remaining balance. An invalid or deactivated API key is rejected with 401, and a key without the endpoint's permission with 403; no task is created in either case.
Analyze an online video of any length in the background. You get a task_id immediately, then collect the analysis by polling or through a webhook.
Use this endpoint instead of POST /analyze/video when you ask for the scenes (include_scenes: true) of a video longer than 10 minutes: the synchronous endpoint does not read the picture of such a video. It also works for short videos and without the scenes.
How It Works
Submit the job
POST /analyze/video/async with the same body as POST /analyze/video, plus an optional webhook_url. You get 202 Accepted with a task_id and a check_status_url.
Wait for the result
Poll GET /analyze/video/{task_id} every few seconds while task_status is processing — polling is free — or receive a webhook when the job finishes.
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 /analyze/video: the fetch of the video, the analysis and, with include_scenes, 1 credit per 1,000 frames analyzed (at least 334 frames per hour of video). The async mode costs nothing extra. Charges are reverted when the job fails.
Submit the job
POST https://api.vidnavigator.com/v1/analyze/video/async
| Parameter | Type | Required | Description |
|---|---|---|---|
video_url | string | Yes | URL of the video to analyze. |
query | string | No | A question to answer about the video. Without it you get the summary, people, places and key subjects. |
include_scenes | boolean | No | Default false. When true, what the video shows (its scenes, with the text on screen) is read as well and used together with the transcript. See Use what the video shows. |
transcript_text | boolean | No | When true, returns the transcript as a single plain-text string. |
webhook_url | string | No | Where to POST the result when the job finishes. Overrides the account default set in Studio → API; pass "" to opt this job out of the default. |
include_usage is not accepted on the submit request. Pass it on the poll request instead.
curl -X POST "https://api.vidnavigator.com/v1/analyze/video/async" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://www.dailymotion.com/video/x84243e",
"query": "What are the ingredients and their quantities?",
"include_scenes": true
}'Accepted response (202)
{
"status": "success",
"data": {
"task_id": "49075fa1-f5e0-4e45-a907-961a72d0e106",
"task_status": "processing",
"job_type": "analyze_video",
"expires_at": "2026-11-16T13:35:54.473122+00:00",
"check_status_url": "/v1/analyze/video/49075fa1-f5e0-4e45-a907-961a72d0e106",
"webhook_url": null,
"message": "Job started. Poll check_status_url for the result."
}
}Get the result
GET https://api.vidnavigator.com/v1/analyze/video/{task_id}
| Parameter | In | Description |
|---|---|---|
task_id | path | The task_id returned by the submit request. |
include_usage | query | true to receive the charges of the job in a usage block. |
curl "https://api.vidnavigator.com/v1/analyze/video/49075fa1-f5e0-4e45-a907-961a72d0e106?include_usage=true" \
-H "X-API-Key: YOUR_API_KEY"Completed response
{
"status": "success",
"data": {
"task_id": "49075fa1-f5e0-4e45-a907-961a72d0e106",
"task_status": "completed",
"job_type": "analyze_video",
"result": {
"video_info": { "title": "PATÊ DE FRANGO CREMOSO", "duration": 79 },
"transcript": [
{ "text": "Música", "start": 0.0, "end": 4.0 }
],
"transcript_analysis": {
"summary": "The video shows how to make a creamy chicken pâté...",
"query_answer": {
"answer": "Shredded cooked chicken 500 g; mayonnaise 300 g; requeijão 250 g; 2 grated carrots; corn 250 g; green olives 250 g; herbs to taste.",
"best_segment_index": 5,
"relevant_segments": ["5:6", "9", "13:14", "16", "18"]
}
},
"scenes": [
{
"start": 0.0,
"end": 2.0,
"description": "A wooden table holds a bowl of crackers, a bowl of creamy pâté and a bowl of olives.",
"on_screen_text": "PATÊ DE FRANGO CREMOSO"
}
],
"frames_analyzed": 30
}
},
"usage": {
"charges": [
{ "service_type": "standard_request", "quantity": 1.0, "credits": 0.0001 },
{ "service_type": "frame_analysis", "quantity": 30.0, "credits": 0.03 },
{ "service_type": "analysis_request", "quantity": 1.0, "credits": 0.01 }
],
"total_credits": 0.0401
}
}A failed job answers 200 too, with task_status: "failed" and the error in data.error (error, message, http_status). See Async jobs for the states, the retention of results and the webhook events (analyze_video.completed / analyze_video.failed).
API reference
ApiKeyAuthX-API-Key<token>API key authentication. Include your VidNavigator API key in the X-API-Key header.
application/json- body
video_url*stringURL of the video to analyze
uriquery?stringOptional question about the video content
include_scenes?booleanWhen true, the scenes of the video (what it shows, with the text readable on screen) are read as well, as POST /watch does, and used together with the transcript.
falsetranscript_text?booleanWhen true, returns the transcript as a single plain-text string instead of an array of segments.
falsewebhook_url?stringWhere 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
uriJob accepted and started.
application/json- response
202 response from an async submit endpoint.
status?"success""success"data?curl -X POST 'https://api.vidnavigator.com/v1/analyze/video/async' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}'{ "status": "success", "data": { "task_id": "550e8400-e29b-41d4-a716-446655440000", "task_status": "processing", "job_type": "transcribe", "expires_at": "2019-08-24T14:15:22Z", "check_status_url": "/v1/transcribe/550e8400-e29b-41d4-a716-446655440000", "webhook_url": "string", "message": "string", "docs_url": "string" }}