Skip to main content
POST
/
transcribe
Transcribe online videos
curl --request POST \
  --url https://api.vidnavigator.com/v1/transcribe \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "video_url": "https://www.instagram.com/reel/C86ZvEaqRmo/",
  "transcript_text": false,
  "all_videos": false
}
'
{
  "status": "success",
  "data": {
    "video_info": {
      "title": "<string>",
      "description": "<string>",
      "thumbnail": "<string>",
      "url": "<string>",
      "channel": "<string>",
      "channel_url": "<string>",
      "duration": 123,
      "views": 123,
      "likes": 123,
      "published_date": "<string>",
      "keywords": [
        "<string>"
      ],
      "category": "<string>",
      "available_languages": [
        "<string>"
      ],
      "selected_language": "<string>",
      "carousel_info": {
        "total_items": 123,
        "video_count": 123,
        "image_count": 123,
        "selected_index": 123
      }
    },
    "transcript": [
      {
        "text": "<string>",
        "start": 123,
        "end": 123
      }
    ]
  }
}
Transcribe online videos from platforms like Instagram, TikTok, and more using speech-to-text models when a direct transcript is not available.

​
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 is not supported by this endpoint. For YouTube videos, use the /transcript/youtube endpoint instead, which retrieves existing transcripts/captions.

​
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

​
Request Parameters

ParameterTypeRequiredDescription
video_urlstringYesURL of the video to transcribe. For Instagram carousel posts, 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 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

400 can include (per OpenAPI): missing_parameter, invalid_parameter, no_videos_found, unsupported_platform.

Authorizations

​
X-API-Key
string
header
required

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

Body

application/json
​
video_url
string<uri>
required

URL of the video to transcribe. For Instagram carousel posts, append ?img_index=N to select a specific video.

Example:

"https://www.instagram.com/reel/C86ZvEaqRmo/"

​
transcript_text
boolean
default:false

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

​
all_videos
boolean
default:false

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

Response

Video transcribed successfully. Response format depends on all_videos parameter.

Single video response (default)

​
status
enum<string>
Available options:
success
​
data
object