Skip to Content

Transcribe Online Video

Transcribe online videos (YouTube, Instagram, TikTok, Snapchat and the other supported platforms) with speech-to-text, whether or not they have captions. For a YouTube video that has captions, POST /transcript returns them without speech-to-text.

Instagram Carousel Posts:

  • For posts with multiple videos, the URL can include ?img_index=N to select a specific video
  • Example: https://www.instagram.com/p/ABC123/?img_index=2 transcribes the second video
  • Without img_index, the first video is transcribed
  • Set all_videos=true to transcribe ALL videos in a carousel post
  • Snapchat highlights with several videos work the same way: img_index=N is the Nth video

Options:

  • transcript_text=true: Returns transcript as a single text string instead of segments
  • all_videos=true: For carousel posts, returns all videos with their transcripts

Set include_usage=true to receive the usage block.

Long videos: this endpoint is synchronous and holds the connection open for the whole transcription. For media longer than ~10 minutes use POST /transcribe/async instead, which returns a task_id and can call your webhook when it finishes. Media longer than 10 minutes is rejected here with video_too_long (HTTP 400). Send long media to the async endpoint, which has no cap. See https://docs.vidnavigator.com/guides/async-jobs

POST
/transcribe

Transcribe online videos from YouTube, Instagram, TikTok and the other supported platforms with speech-to-text, whether or not they have captions.

Overview

This endpoint is designed for videos where a pre-existing transcript or caption file cannot be retrieved. It downloads the video content and processes it through an AI speech-to-text model to generate a new transcript.

This is particularly useful for social media platforms where direct transcript extraction is not possible, such as Instagram Reels that don't have captions.

YouTube: a YouTube video that has captions gets them faster from /transcript. Use this endpoint for a YouTube video without captions, or when you want a speech-to-text transcript instead of YouTube's captions. The original audio track is transcribed, even when YouTube offers dubbed tracks in other languages.

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 /transcribeUp to 10 minutesIn the HTTP response
AsyncPOST /transcribe/asyncAny lengthPoll GET /transcribe/{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

Speech-to-text processing consumes transcription_hour usage. 1 credit covers 3 hours of video/audio transcription.

On a cache miss, one standard_request or residential_request is also charged for the metadata fetch (residential for YouTube, Instagram, Facebook-watch, Rumble; standard otherwise), plus transcription_hour proportional to the audio duration. On a cache hit (same URL transcribed before, by any user), only transcription_hour is charged — the metadata fetch is skipped. Users with the free_on_cache_hit sponsorship flag get the cache-hit transcription_hour waived (waived: true in the per-charge entry).

Set include_usage: true to receive a usage block with the breakdown.

The async mode is billed exactly the same way. A video_too_long rejection on the synchronous endpoint still bills the metadata fetch that read the duration (standard_request or residential_request, not refunded) but no transcription_hour.

Supported Platforms

VidNavigator can generate transcripts from these platforms using speech-to-text:

  • Instagram
  • X / Twitter (just copy the tweet video link)
  • Facebook (public videos only)
  • TikTok
  • Dailymotion
  • Loom
  • Vimeo
  • Snapchat (Spotlights, story snaps, highlights, Show episodes and snapchat.com/t/... share links)

Request Parameters

ParameterTypeRequiredDescription
video_urlstringYesURL of the video to transcribe. For Instagram carousel posts and Snapchat highlights, append ?img_index=N to select a specific video.
transcript_textbooleanNoWhen true, returns the transcript as a single plain-text string instead of an array of segments.
all_videosbooleanNoFor Instagram carousel posts and Snapchat highlights only. When true, transcribes ALL videos in the post and returns them in an array. Ignored for non-carousel URLs (reels, TikTok, etc.).

Instagram carousel posts (e.g. https://www.instagram.com/p/.../) may contain multiple videos and/or images.

  • Select a specific item: Append ?img_index=N to the URL to select a specific item (1-based).
    Example: https://www.instagram.com/p/ABC123/?img_index=2 selects the second item.
  • Transcribe all videos: Set all_videos=true to transcribe all videos in the carousel. The response format changes (see “Success Response”).

If a carousel post contains only images (no videos), the API returns 400 with error=no_videos_found.

Example Usage

curl -X POST "https://api.vidnavigator.com/v1/transcribe" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.instagram.com/reel/C86ZvEaqRmo/"
  }'
curl -X POST "https://api.vidnavigator.com/v1/transcribe" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.instagram.com/p/ABC123/?img_index=2"
  }'
curl -X POST "https://api.vidnavigator.com/v1/transcribe" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.instagram.com/p/ABC123/",
    "all_videos": true
  }'

Success Response (200 OK)

This endpoint has two success response shapes (a oneOf), depending on whether you set all_videos=true:

  • Single-video response (default): returns data.video_info + data.transcript
  • All-videos response (all_videos=true): returns data.carousel_info + data.videos[]

transcript_text=true affects the shape of each returned transcript (string vs segments) in both response types.

Single-video response (default)

{
  "status": "success",
  "data": {
    "video_info": {
      "title": "A Reel Interesting Video",
      "description": "An example description for the video.",
      "thumbnail": "https://example.com/thumbnail.jpg",
      "url": "https://www.instagram.com/reel/C86ZvEaqRmo/",
      "channel": "Example Creator",
      "duration": 58.5,
      "views": 123456,
      "likes": 7890,
      "published_date": "2024-07-01",
      "keywords": ["example", "social media", "video"],
      "category": "Entertainment"
    },
    "transcript": [
      {
        "text": "This is the first sentence of the video.",
        "start": 0.5,
        "end": 3.2
      },
      {
        "text": "And this is the second.",
        "start": 3.5,
        "end": 5.1
      }
    ]
  }
}

All-videos response (all_videos=true)

{
  "status": "success",
  "data": {
    "carousel_info": {
      "total_items": 5,
      "video_count": 2,
      "image_count": 3,
      "transcribed_count": 2,
      "total_duration": 123.4
    },
    "videos": [
      {
        "index": 1,
        "status": "success",
        "video_info": {
          "title": "Video 1",
          "description": "Example description",
          "thumbnail": "https://example.com/thumb1.jpg",
          "url": "https://www.instagram.com/p/ABC123/?img_index=1",
          "channel": "Example Creator",
          "duration": 60.0,
          "views": 123,
          "likes": 45,
          "published_date": "2024-07-01",
          "keywords": ["example"],
          "category": "Entertainment"
        },
        "transcript": [
          { "text": "First line", "start": 0.0, "end": 2.0 }
        ]
      },
      {
        "index": 2,
        "status": "error",
        "error": "transcript_not_available",
        "message": "Transcript could not be generated for this video."
      }
    ]
  }
}

Error Responses

StatuserrorDescription
400missing_parameter, invalid_parameter, invalid_url, unsupported_url, unsupported_platform, request_body_requiredInvalid request.
400no_videos_foundThe post carries no video (e.g. an image-only carousel).
400video_too_longThe media is longer than 10 minutes. Use POST /transcribe/async.
402limit_exceededNot enough credits.
403content_restrictedThe content requires login or age verification.
404video_not_found, video_unavailable, transcript_not_availableThe video can't be found or accessed, or no transcript could be generated.
451geo_restrictedThe content is not available in this region.
500metadata_fetch_failed, audio_extraction_failed, transcription_failed, internal_server_errorProcessing failed. Charges are reverted.

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

Formaturi
transcript_text?boolean

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

Defaultfalse
all_videos?boolean

For carousel posts only. When true, transcribes ALL videos in the post and returns them in an array. Ignored for non-carousel URLs (reels, TikTok, etc.).

Defaultfalse
include_usage?boolean

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

Defaultfalse

Response Body

Video transcribed successfully. Response format depends on all_videos parameter.

application/json
  1. response

Single video response (default)

status?"success"
Value in"success"
data?
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/transcribe' \  -H 'Content-Type: application/json' \  -d '{  "video_url": "https://www.instagram.com/reel/C86ZvEaqRmo/"}'
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      }    ]  },  "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