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

# Transcribe Online Video

> Transcribe online videos (e.g., Instagram, TikTok) using speech-to-text models when a transcript is not available.

**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

**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

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.

<Warning>
  **YouTube is not supported by this endpoint.** For YouTube videos, use the [/youtube/transcript](/api-reference/endpoint/transcript-youtube) endpoint instead, which retrieves existing transcripts/captions.
</Warning>

## Billing

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

## 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

| Parameter         | Type    | Required | Description                                                                                                                                                           |
| ----------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `video_url`       | string  | Yes      | URL of the video to transcribe. For Instagram carousel posts, append `?img_index=N` to select a specific video.                                                       |
| `transcript_text` | boolean | No       | When `true`, returns the transcript as a single plain-text string instead of an array of segments.                                                                    |
| `all_videos`      | boolean | No       | For 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 Behavior

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

<Note>
  If a carousel post contains **only images** (no videos), the API returns `400` with `error=no_videos_found`.
</Note>

## Example Usage

<CodeGroup>
  ```bash cURL theme={null}
  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/"
    }'
  ```

  ```python Python theme={null}
  from vidnavigator import VidNavigatorClient, VidNavigatorError

  client = VidNavigatorClient()

  try:
      result = client.transcribe_video(
          video_url="https://www.instagram.com/reel/C86ZvEaqRmo/"
      )
      print("Video Title:", result.data.video_info.title)
      for segment in result.data.transcript:
          print(f"[{segment.start:.2f}s - {segment.end:.2f}s] {segment.text}")
  except VidNavigatorError as e:
      print(f"An error occurred: {e.message}")
  ```

  ```javascript JavaScript theme={null}
  const { VidNavigatorClient, VidNavigatorError } = require('vidnavigator');

  const client = new VidNavigatorClient({
    apiKey: process.env.VIDNAVIGATOR_API_KEY,
  });

  async function transcribeVideo() {
    try {
      const { video_info, transcript } = await client.transcribeVideo({
        video_url: "https://www.instagram.com/reel/C86ZvEaqRmo/"
      });
      console.log("Video Title:", video_info.title);
      transcript.forEach(segment => {
        console.log(`[${segment.start.toFixed(2)}s - ${segment.end.toFixed(2)}s] ${segment.text}`);
      });
    } catch (error) {
      if (error instanceof VidNavigatorError) {
        console.error(`An error occurred: ${error.message}`);
      } else {
        console.error("An unexpected error occurred:", error);
      }
    }
  }

  transcribeVideo();
  ```
</CodeGroup>

### Instagram Carousel (select a specific video with `?img_index=2`)

```bash theme={null}
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"
  }'
```

### Instagram Carousel (transcribe all videos with `all_videos=true`)

```bash theme={null}
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[]`

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

### Single-video response (default)

```json theme={null}
{
  "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`)

```json theme={null}
{
  "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`.


## OpenAPI

````yaml POST /transcribe
openapi: 3.0.3
info:
  title: VidNavigator Developer API
  description: >-
    The VidNavigator Developer API provides programmatic access to video
    analysis, transcription, and search capabilities.


    ## Authentication

    All endpoints require API key authentication via the `X-API-Key` header:

    ```

    X-API-Key: YOUR_API_KEY

    ```


    ## Rate Limits

    Check the documentation for the rate limits for each endpoint.


    ## Error Handling

    The API uses standard HTTP status codes and returns error responses in JSON
    format:

    ```json

    {
      "status": "error",
      "error": "error_type",
      "message": "Human readable error message"
    }

    ```
  version: 1.0.0
  contact:
    name: VidNavigator Support
    url: https://vidnavigator.com/support
    email: support@vidnavigator.com
  license:
    name: Proprietary
    url: https://vidnavigator.com/terms
servers:
  - url: https://api.vidnavigator.com/v1
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Transcripts
    description: Extract transcripts from online videos
  - name: TikTok
    description: Scrape TikTok profile metadata and per-video stats
  - name: Files
    description: Manage uploaded audio/video files
  - name: Analysis
    description: AI-powered content analysis
  - name: Extraction
    description: >-
      Extract structured data from video and file transcripts using custom
      schemas
  - name: Namespaces
    description: Organize uploaded files into namespaces (folders)
  - name: Search
    description: Search videos and files using AI
  - name: System
    description: System health and information
  - name: Tweet Analysis
    description: Extract structured claims and metadata from X/Twitter tweets
paths:
  /transcribe:
    post:
      tags:
        - Transcripts
      summary: Transcribe online videos
      description: >-
        Transcribe online videos (e.g., Instagram, TikTok) using speech-to-text
        models when a transcript is not available.


        **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


        **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
      operationId: transcribeVideo
      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 transcribe. For Instagram carousel
                    posts, append ?img_index=N to select a specific video.
                  example: https://www.instagram.com/reel/C86ZvEaqRmo/
                transcript_text:
                  type: boolean
                  default: false
                  description: >-
                    When true, returns the transcript as a single plain-text
                    string instead of an array of segments.
                all_videos:
                  type: boolean
                  default: false
                  description: >-
                    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.).
      responses:
        '200':
          description: >-
            Video transcribed successfully. Response format depends on
            `all_videos` parameter.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    description: Single video response (default)
                    properties:
                      status:
                        type: string
                        enum:
                          - success
                      data:
                        type: object
                        properties:
                          video_info:
                            $ref: '#/components/schemas/VideoInfo'
                          transcript:
                            $ref: '#/components/schemas/TranscriptOutput'
                  - type: object
                    description: All videos response (when all_videos=true)
                    properties:
                      status:
                        type: string
                        enum:
                          - success
                      data:
                        type: object
                        properties:
                          carousel_info:
                            $ref: '#/components/schemas/CarouselInfo'
                          videos:
                            type: array
                            items:
                              $ref: '#/components/schemas/CarouselVideoResult'
        '400':
          description: Bad request - invalid parameters or no videos found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  error:
                    type: string
                    enum:
                      - missing_parameter
                      - invalid_parameter
                      - no_videos_found
                      - unsupported_platform
                  message:
                    type: string
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    VideoInfo:
      type: object
      properties:
        title:
          type: string
          description: Video title
        description:
          type: string
          description: Video description
        thumbnail:
          type: string
          format: uri
          description: Video thumbnail URL
        url:
          type: string
          format: uri
          description: Video URL
        channel:
          type: string
          description: Channel name
        channel_url:
          type: string
          format: uri
          description: Channel URL
        duration:
          type: number
          description: Duration in seconds
        views:
          type: integer
          description: View count
        likes:
          type: integer
          description: Like count
        published_date:
          type: string
          description: Publication date
        keywords:
          type: array
          items:
            type: string
          description: Video keywords/tags
        category:
          type: string
          description: Video category
        available_languages:
          type: array
          items:
            type: string
          description: Available transcript languages
        selected_language:
          type: string
          description: Selected transcript language
        carousel_info:
          $ref: '#/components/schemas/VideoCarouselInfo'
          description: >-
            Present only for carousel posts (e.g., Instagram posts with multiple
            videos)
    TranscriptOutput:
      description: >-
        Transcript output. By default it is an array of segments. When
        `transcript_text=true`, it is returned as a single plain-text string.
      oneOf:
        - type: array
          items:
            $ref: '#/components/schemas/TranscriptSegment'
        - type: string
    CarouselInfo:
      type: object
      description: Summary information for all_videos=true response
      properties:
        total_items:
          type: integer
          description: Total number of items in the carousel
        video_count:
          type: integer
          description: Number of videos in the carousel
        image_count:
          type: integer
          description: Number of images in the carousel
        transcribed_count:
          type: integer
          description: Number of videos successfully transcribed
        total_duration:
          type: number
          description: Total duration of all transcribed videos in seconds
    CarouselVideoResult:
      type: object
      description: Result for a single video in an all_videos response
      properties:
        index:
          type: integer
          description: 1-based index of this video in the carousel
        status:
          type: string
          enum:
            - success
            - error
          description: Whether this video was transcribed successfully
        video_info:
          $ref: '#/components/schemas/VideoInfo'
          description: Video metadata (present when status is success)
        transcript:
          $ref: '#/components/schemas/TranscriptOutput'
          description: Video transcript (present when status is success)
        error:
          type: string
          description: Error code (present when status is error)
        message:
          type: string
          description: Error message (present when status is error)
    VideoCarouselInfo:
      type: object
      description: Carousel information for a single video within a carousel post
      properties:
        total_items:
          type: integer
          description: Total number of items in the carousel (videos + images)
        video_count:
          type: integer
          description: Number of videos in the carousel
        image_count:
          type: integer
          description: Number of images in the carousel
        selected_index:
          type: integer
          description: 1-based index of the selected video
    TranscriptSegment:
      type: object
      properties:
        text:
          type: string
          description: Transcript text for this segment
        start:
          type: number
          description: Start time in seconds
        end:
          type: number
          description: End time in seconds
  responses:
    PaymentRequired:
      description: Usage limit exceeded - upgrade required
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - limit_exceeded
              message:
                type: string
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - 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.

````