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 clipinclude_transcript=false: the scenes onlytranscript_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.
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:
| Mode | Endpoint | Media duration | How you get the result |
|---|---|---|---|
| Synchronous | POST /watch | Up to 10 minutes | In the HTTP response |
| Async | POST /watch/async | Up 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:
| Charge | When | Amount |
|---|---|---|
standard_request or residential_request | Always: the fetch of the video, as on /transcript | 1 request |
transcription_hour | Only when the transcript needs speech-to-text, because the video has no captions | The duration of the video: 1 credit = 3 hours |
frame_analysis | Always: the picture | 1 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
- X / Twitter
- Facebook (public videos only)
- Vimeo
- Dailymotion
- Loom
- Snapchat
Uploaded files are not supported by this endpoint.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
video_url | string | Yes | URL of the video to watch. For Instagram carousel posts and Snapchat highlights, append ?img_index=N to select a specific video. |
detail | string | No | How closely the picture is followed: low, auto (default) or high. See Level of detail. |
include_transcript | boolean | No | Default true. When false, only the scenes are returned and no transcript is fetched or produced. |
transcript_text | boolean | No | When true, returns the transcript as a single plain-text string instead of an array of segments. |
include_usage | boolean | No | When 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:
detail | Behavior |
|---|---|
low | Keeps the larger changes of picture. |
auto | 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. 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
}
}| Field | Description |
|---|---|
video_info | The video's metadata, as on /transcript. |
transcript | What 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). |
scenes | What is shown, in chronological order. |
scenes[].start, scenes[].end | Start 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[].description | What is visible: people, setting, action, objects. |
scenes[].on_screen_text | Text readable on screen, verbatim. Empty when there is none. |
frames_analyzed | Number of frames of the video that were analyzed to produce the scenes. |
transcript_error | Present 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
| Status | error | Description |
|---|---|---|
400 | missing_parameter, invalid_parameter, invalid_url, request_body_required | Invalid request. An unknown detail is an invalid_parameter. |
400 | no_videos_found | The post carries no video (e.g. an image-only carousel). |
400 | video_too_long | The media is longer than 10 minutes: use POST /watch/async. Videos longer than 2 hours are not accepted in either mode, except on YouTube. |
402 | limit_exceeded | Not enough credits. |
403 | content_restricted | The content requires login or age verification. |
404 | video_unavailable, video_not_yet_available | The video is gone, or not published yet. |
404 | frames_not_available | The picture cannot be read: a live stream, or a clip of a few seconds. |
404 | metadata_fetch_failed | The video could not be reached after our retries. May be temporary. |
451 | geo_restricted | The content is not available in this region. |
502, 503 | video_download_failed, watch_failed, watch_unavailable | The video could not be watched this time. Temporary: try again. |
See Errors for the full list.
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 watch. For Instagram carousel posts and Snapchat highlights, append ?img_index=N to select a specific video.
uridetail?stringHow 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.
"auto""low""auto""high"include_transcript?booleanWhen false, only the scenes are returned and no transcript is fetched or produced.
truetranscript_text?booleanWhen true, returns the transcript as a single plain-text string instead of an array of segments.
falseinclude_usage?booleanWhen true, the response includes the usage block of this request.
falseThe video was watched.
application/json- response
status?"success""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.
curl -X POST 'https://api.vidnavigator.com/v1/watch' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://www.tiktok.com/@nasa/video/7300000000000000000"}'{ "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 } }}