> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidnavigator.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.vidnavigator.com/webhooks.md).

> [!NOTE]
>
> Use this endpoint instead of [`POST /analyze/video`](https://docs.vidnavigator.com/api-reference/endpoint/analyze-video.md) 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

**1. Submit the job**

`POST /analyze/video/async` with the **same body** as [`POST /analyze/video`](https://docs.vidnavigator.com/api-reference/endpoint/analyze-video.md), 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 /analyze/video/{task_id}` every few seconds while `task_status` is `processing` — polling is free — or receive a [webhook](https://docs.vidnavigator.com/webhooks.md) 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 /analyze/video`](https://docs.vidnavigator.com/api-reference/endpoint/analyze-video.md#billing): 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](https://docs.vidnavigator.com/api-reference/endpoint/analyze-video.md#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](https://vidnavigator.com/studio/api); pass `""` to opt this job out of the default.                                                                                         |

> [!NOTE]
>
> `include_usage` is not accepted on the submit request. Pass it on the poll request instead.

```bash 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)

```json
{
  "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`](https://docs.vidnavigator.com/api-reference/usage-costs.md#per-call-usage-disclosure) block. |

```bash 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

```json
{
  "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](https://docs.vidnavigator.com/guides/async-jobs.md) for the states, the retention of results and the webhook events (`analyze_video.completed` / `analyze_video.failed`).

## OpenAPI

````yaml POST /analyze/video/async
openapi: 3.0.3
info:
  title: VidNavigator Developer API
  version: 1.0.0
servers:
  - url: https://api.vidnavigator.com/v1
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /analyze/video/async:
    post:
      summary: Analyze a video asynchronously (long videos)
      description: |-
        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.
      operationId: analyzeVideoAsync
      tags:
        - Analysis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - video_url
              properties:
                video_url:
                  type: string
                  format: uri
                  description: URL of the video to analyze
                  example: https://youtube.com/watch?v=dQw4w9WgXcQ
                query:
                  type: string
                  description: Optional question about the video content
                  example: What is the main topic discussed?
                include_scenes:
                  type: boolean
                  default: false
                  description: 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.
                transcript_text:
                  type: boolean
                  default: false
                  description: When true, returns the transcript as a single plain-text string instead of an array of segments.
                webhook_url:
                  type: string
                  format: uri
                  description: 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
      responses:
        "202":
          description: Job accepted and started.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AsyncJobAccepted"
        "400":
          $ref: "#/components/responses/BadRequest"
        "402":
          description: Insufficient credits to queue the job; no task is created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  error:
                    type: string
                    enum:
                      - limit_exceeded
                  error_code:
                    type: string
                    enum:
                      - limit_exceeded
                  message:
                    type: string
        "429":
          description: Too many jobs already running for this account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  error:
                    type: string
                    enum:
                      - too_many_active_jobs
                  message:
                    type: string
        "500":
          $ref: "#/components/responses/InternalServerError"
components:
  schemas:
    AsyncJobAccepted:
      type: object
      description: 202 response from an async submit endpoint.
      properties:
        status:
          type: string
          enum:
            - success
        data:
          type: object
          properties:
            task_id:
              type: string
              description: Identifier to poll with.
              example: 550e8400-e29b-41d4-a716-446655440000
            task_status:
              type: string
              enum:
                - processing
            job_type:
              type: string
              enum:
                - transcribe
                - extract_video
                - tweet_statement
                - watch
                - analyze_video
            expires_at:
              type: string
              format: date-time
              description: Results are deleted after this time. Until the job finishes this is a provisional submit-time bound; on completion it is pushed out to finish time + 1 hour.
            check_status_url:
              type: string
              description: Relative URL to poll for status and the result.
              example: /v1/transcribe/550e8400-e29b-41d4-a716-446655440000
            webhook_url:
              type: string
              nullable: true
              description: The URL this job's result will be POSTed to, or null if no webhook applies.
            message:
              type: string
            docs_url:
              type: string
  responses:
    BadRequest:
      description: Bad request - invalid parameters. On /transcribe the `error` field may be `missing_parameter`, `unsupported_platform`, `unsupported_url`, `invalid_url`, `request_body_required`, `video_too_long`, or `no_videos_found` (the post carries no video).
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
              message:
                type: string
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - metadata_fetch_failed
                  - audio_extraction_failed
                  - transcription_failed
                  - internal_server_error
              message:
                type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication. Include your VidNavigator API key in the X-API-Key header.
````
