Skip to Content

Watch Online Video

Read what a video shows, along with what it says. The response holds the video's transcript and a list of scenes: for each one, when it starts and ends, a description of the picture, and the text readable on screen.

Works with every platform POST /transcript and POST /transcribe support. The transcript comes from the platform's captions when it has them, and from speech-to-text otherwise.

Options:

  • detail: how closely the picture is followed (low, auto, high). The number of frames depends on the video at every level: few on a fixed shot, many on a fast-cut clip
  • include_transcript=false: the scenes only
  • transcript_text=true: the transcript as a single text string instead of segments

A video without speech is not an error: transcript is empty, transcript_error says why, and the scenes are returned.

Set include_usage=true to receive the usage block.

Long videos: this endpoint is synchronous. For media longer than ~10 minutes use POST /watch/async instead, which returns a task_id and can call your webhook when it finishes. See https://docs.vidnavigator.com/guides/async-jobs

Videos longer than 2 hours are not accepted (video_too_long), except on YouTube.

POST
/watch

Read what a video shows, next to what it says: its transcript and a list of scenes, each with a description of the picture and the text readable on screen, in one response.

Overview

A transcript holds what is said. This endpoint adds the picture. For each scene of the video you get when it starts and ends, a description of what is visible (people, setting, action, objects) and the text on screen (captions, titles, signs), verbatim.

Use it when the picture matters:

  • a video with little or no speech,
  • a product demo or a tutorial,
  • prices, names or claims written on screen,
  • checking that what is said matches what is shown.

The transcript comes with the scenes by default. It is taken from the platform's captions when it has them, and from speech-to-text otherwise. For the words alone, /transcript and /transcribe remain the cheaper calls.

Synchronous or async?

This endpoint comes in two modes, with the same request body and the same result:

ModeEndpointMedia durationHow you get the result
SynchronousPOST /watchUp to 10 minutesIn the HTTP response
AsyncPOST /watch/asyncUp to 2 hours (any length on YouTube)Poll GET /watch/{task_id} or receive a webhook

Media longer than 10 minutes is rejected by the synchronous endpoint with 400 video_too_long. Use the async mode for anything that may run past 10 minutes. It also works for short videos, so it is the safe default when you don't know the duration.

Billing

A watch request is charged for the fetch of the video, for the transcription when it is needed, and for the frames analyzed:

ChargeWhenAmount
standard_request or residential_requestAlways: the fetch of the video, as on /transcript1 request
transcription_hourOnly when the transcript needs speech-to-text, because the video has no captionsThe duration of the video: 1 credit = 3 hours
frame_analysisAlways: the picture1 unit per frame: 1 credit = 1,000 frames

The number of frames follows the picture: few on a fixed shot, more when it changes often, and more at a higher detail. A video is analyzed, and charged, for at least 334 frames per hour of video, in proportion to its length, so an hour of video watched never costs less than an hour of transcription.

As a guide, at the default level: a fixed shot stays at that minimum, about 0.33 credit per hour of video, and an hour of television programme is typically between 0.5 and 1 credit.

include_transcript: false leaves the transcription out, and its charge with it. When a request fails, the frames and the transcription are not charged.

Set include_usage: true to receive a usage block with the breakdown: the quantity of its frame_analysis entry is the number of frames charged.

Supported Platforms

Every platform supported by /transcript and /transcribe:

  • YouTube
  • TikTok
  • Instagram
  • X / Twitter
  • Facebook (public videos only)
  • Vimeo
  • Dailymotion
  • Loom
  • Snapchat

Uploaded files are not supported by this endpoint.

Request Parameters

ParameterTypeRequiredDescription
video_urlstringYesURL of the video to watch. For Instagram carousel posts and Snapchat highlights, append ?img_index=N to select a specific video.
detailstringNoHow closely the picture is followed: low, auto (default) or high. See Level of detail.
include_transcriptbooleanNoDefault true. When false, only the scenes are returned and no transcript is fetched or produced.
transcript_textbooleanNoWhen true, returns the transcript as a single plain-text string instead of an array of segments.
include_usagebooleanNoWhen true, the response includes the usage block of this request.

Level of detail

The number of frames analyzed depends on the video at every level: few on a fixed shot, many on a fast-cut clip. A frame is taken where the picture changes, and at least one every 10 seconds. detail sets how small a change counts:

detailBehavior
lowKeeps the larger changes of picture.
autoThe balanced default.
highFollows faster cuts, and looks at a still picture twice as often.

A higher level analyzes more frames on a video whose picture changes often. The response tells how many were analyzed in frames_analyzed.

Example Usage

curl -X POST "https://api.vidnavigator.com/v1/watch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.tiktok.com/@nasa/video/7300000000000000000"
  }'

Both SDKs run this call as a background job (POST /watch/async, then polling), so it is not limited to 10 minutes of video.

Scenes only

curl -X POST "https://api.vidnavigator.com/v1/watch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.tiktok.com/@nasa/video/7300000000000000000",
    "include_transcript": false,
    "detail": "high"
  }'

Success Response (200 OK)

{
  "status": "success",
  "data": {
    "video_info": {
      "title": "Evening news",
      "description": "An example description for the video.",
      "thumbnail": "https://example.com/thumbnail.jpg",
      "url": "https://www.tiktok.com/@nasa/video/7300000000000000000",
      "channel": "Example Creator",
      "duration": 24.0,
      "views": 123456,
      "likes": 7890,
      "published_date": "2026-07-01"
    },
    "transcript": [
      {
        "text": "Good evening. Tonight, the storm reaches the coast.",
        "start": 0.4,
        "end": 3.9
      }
    ],
    "scenes": [
      {
        "start": 0.0,
        "end": 4.0,
        "description": "A studio with a news desk. A presenter in a dark suit faces the camera.",
        "on_screen_text": ""
      },
      {
        "start": 4.0,
        "end": 12.0,
        "description": "A presenter stands in front of a world map and points at Europe.",
        "on_screen_text": "BREAKING NEWS"
      },
      {
        "start": 12.0,
        "end": 24.0,
        "description": "Waves break over a sea wall; a few people walk away from the shore.",
        "on_screen_text": "LIVE - 18:42"
      }
    ],
    "frames_analyzed": 23
  }
}
FieldDescription
video_infoThe video's metadata, as on /transcript.
transcriptWhat is said: an array of segments, or one string with transcript_text=true. Left out when include_transcript=false; empty when the video has no transcript (see transcript_error).
scenesWhat is shown, in chronological order.
scenes[].start, scenes[].endStart and end of the scene, in seconds from the beginning of the video. A scene ends where the next one starts, or at the end of the video.
scenes[].descriptionWhat is visible: people, setting, action, objects.
scenes[].on_screen_textText readable on screen, verbatim. Empty when there is none.
frames_analyzedNumber of frames of the video that were analyzed to produce the scenes.
transcript_errorPresent only when the transcript could not be had.

A video without speech

A video without speech is not an error. The scenes are returned, transcript is empty and transcript_error says why. The same applies to a YouTube video that has no captions.

{
  "status": "success",
  "data": {
    "video_info": { "title": "Timelapse of a harbour", "duration": 30.0 },
    "transcript": [],
    "transcript_error": {
      "error": "transcript_not_available",
      "message": "No transcript found for this video."
    },
    "scenes": [
      {
        "start": 0.0,
        "end": 30.0,
        "description": "A harbour at dusk, seen from above. Cranes unload a container ship while the sky darkens.",
        "on_screen_text": ""
      }
    ],
    "frames_analyzed": 6
  }
}

Error Responses

StatuserrorDescription
400missing_parameter, invalid_parameter, invalid_url, request_body_requiredInvalid request. An unknown detail is an invalid_parameter.
400no_videos_foundThe post carries no video (e.g. an image-only carousel).
400video_too_longThe media is longer than 10 minutes: use POST /watch/async. Videos longer than 2 hours are not accepted in either mode, except on YouTube.
402limit_exceededNot enough credits.
403content_restrictedThe content requires login or age verification.
404video_unavailable, video_not_yet_availableThe video is gone, or not published yet.
404frames_not_availableThe picture cannot be read: a live stream, or a clip of a few seconds.
404metadata_fetch_failedThe video could not be reached after our retries. May be temporary.
451geo_restrictedThe content is not available in this region.
502, 503video_download_failed, watch_failed, watch_unavailableThe video could not be watched this time. Temporary: try again.

See Errors for the full list.

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 watch. For Instagram carousel posts and Snapchat highlights, append ?img_index=N to select a specific video.

Formaturi
detail?string

How closely the picture is followed. At every level a frame is taken where the picture changes, and at least one every 10 seconds; the level sets how small a change counts. low keeps the larger changes, auto is the balanced default, high follows faster cuts and looks at a still picture twice as often. A higher level analyzes more frames on a video whose picture changes often.

Default"auto"
Value in"low""auto""high"
include_transcript?boolean

When false, only the scenes are returned and no transcript is fetched or produced.

Defaulttrue
transcript_text?boolean

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

Defaultfalse
include_usage?boolean

When true, the response includes the usage block of this request.

Defaultfalse

Response Body

The video was watched.

application/json
  1. response
status?"success"
Value in"success"
data?

A watched video: its metadata, its transcript and its scenes.

usage?

Per-call usage, returned only when the request sets include_usage=true: the charges of this request, one entry per service_type, and the total credits deducted. A waived charge carries waived: true and credits_saved, with a top-level waived.credits_saved summary.

For endpoints that run an AI analysis (/extract/video, /extract/file, /analyze/video, /analyze/file, /youtube/search), the analysis_request entry carries a nested tokens object with the request's token counts.

Example Request
curl -X POST 'https://api.vidnavigator.com/v1/watch' \  -H 'Content-Type: application/json' \  -d '{  "video_url": "https://www.tiktok.com/@nasa/video/7300000000000000000"}'
Example Response
{  "status": "success",  "data": {    "video_info": {      "title": "string",      "description": "string",      "thumbnail": "http://example.com",      "url": "http://example.com",      "channel": "string",      "channel_url": "http://example.com",      "duration": 0,      "views": 0,      "likes": 0,      "published_date": "string",      "keywords": [        "string"      ],      "category": "string",      "available_languages": [        "string"      ],      "selected_language": "string",      "carousel_info": {        "total_items": 0,        "video_count": 0,        "image_count": 0,        "selected_index": 0      }    },    "transcript": [      {        "text": "string",        "start": 0,        "end": 0      }    ],    "transcript_error": {      "error": "transcript_not_available",      "message": "string"    },    "scenes": [      {        "start": 4,        "end": 12,        "description": "A presenter stands in front of a world map and points at Europe.",        "on_screen_text": "BREAKING NEWS"      }    ],    "frames_analyzed": 23  },  "usage": {    "charges": [      {        "service_type": "standard_request",        "quantity": 0,        "credits": 0,        "waived": true,        "credits_saved": 0,        "tokens": {          "prompt_tokens": 0,          "completion_tokens": 0,          "total_tokens": 0        }      }    ],    "total_credits": 0,    "waived": {      "credits_saved": 0    }  }}

On this page