Skip to Content

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.

POST
/analyze/video/async

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

ParameterTypeRequiredDescription
video_urlstringYesURL of the video to analyze.
querystringNoA question to answer about the video. Without it you get the summary, people, places and key subjects.
include_scenesbooleanNoDefault 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_textbooleanNoWhen true, returns the transcript as a single plain-text string.
webhook_urlstringNoWhere 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
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}

ParameterInDescription
task_idpathThe task_id returned by the submit request.
include_usagequerytrue to receive the charges of the job in a usage block.
cURL
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

Authorization

ApiKeyAuth
headerX-API-Key<token>

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

Request Body

application/json
  1. body
video_url*string

URL of the video to analyze

Formaturi
query?string

Optional question about the video content

include_scenes?boolean

When 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.

Defaultfalse
transcript_text?boolean

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

Defaultfalse
webhook_url?string

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

Formaturi

Response Body

Job accepted and started.

application/json
  1. response

202 response from an async submit endpoint.

status?"success"
Value in"success"
data?
Example Request
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"}'
Example Response
{  "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"  }}

On this page