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

# Get Video Transcript

> Extract transcript from non-YouTube online videos (Vimeo, Twitter/X, TikTok, Facebook, Instagram, Dailymotion, Loom, etc.) with optional language selection.

**For YouTube videos, use `/youtube/transcript` instead.**

Options:
- `transcript_text=true`: Returns the transcript as a single plain-text string instead of an array of segments.
- `metadata_only=true`: Returns only video metadata (no transcript).
- `fallback_to_metadata=true`: If transcript is unavailable, returns video metadata with an empty transcript instead of a 404 error (ignored when `metadata_only=true`).

Extract accurate metadata and transcripts from online videos including TikTok, Facebook, X, Vimeo, Dailymotion, Loom, and other platforms.

<Note>
  **For YouTube videos**, please use the dedicated [YouTube Transcript](/api-reference/endpoint/transcript-youtube) endpoint, which uses residential proxy infrastructure for reliable access.
</Note>

## Billing

Non-YouTube transcript retrieval consumes `standard_request` usage. 1 credit covers 10,000 Standard Requests.

## Overview

This endpoint automatically extracts rich video metadata and transcripts from non-YouTube online videos with high accuracy.

## Supported Platforms

VidNavigator can retrieve transcripts from a wide variety of sources. Below is the list of platforms currently supported by this endpoint:

* X / Twitter (just copy the tweet video link)
* Facebook (public videos only)
* TikTok
* Dailymotion
* Loom
* Vimeo

<Tip>
  For **YouTube videos**, use the [/youtube/transcript](/api-reference/endpoint/transcript-youtube) endpoint instead.
</Tip>

## Use Cases

<CardGroup cols={2}>
  <Card title="Content Analysis" icon="chart-bar">
    Extract transcripts for AI analysis, sentiment analysis, or content categorization
  </Card>

  <Card title="Search & Discovery" icon="magnifying-glass">
    Enable text-based search across video content libraries
  </Card>

  <Card title="Accessibility" icon="universal-access">
    Generate captions and transcripts for accessibility compliance
  </Card>

  <Card title="Content Creation" icon="pen-to-square">
    Create summaries, articles, or repurpose video content
  </Card>
</CardGroup>

## Request Parameters

| Parameter              | Type    | Required | Description                                                                                                                                                   |
| ---------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `video_url`            | string  | Yes      | URL of the video to transcribe                                                                                                                                |
| `language`             | string  | No       | ISO2 language code (e.g., "en", "es", "fr")                                                                                                                   |
| `metadata_only`        | boolean | No       | When `true`, returns only video metadata without fetching the transcript. Takes precedence over `fallback_to_metadata`.                                       |
| `fallback_to_metadata` | boolean | No       | When `true`, returns video metadata with an empty transcript if transcript is unavailable (returns 200 instead of 404). Ignored if `metadata_only` is `true`. |
| `transcript_text`      | boolean | No       | When `true`, returns the transcript as a single plain-text string instead of an array of segments.                                                            |

## Example Usage

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.vidnavigator.com/v1/transcript" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "video_url": "https://twitter.com/user/status/123456789",
      "language": "en"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.vidnavigator.com/v1/transcript"
  headers = {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "video_url": "https://twitter.com/user/status/123456789",
      "language": "en"
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.vidnavigator.com/v1/transcript', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      video_url: 'https://twitter.com/user/status/123456789',
      language: 'en'
    })
  });

  const result = await response.json();
  ```
</CodeGroup>

### Transcript as Plain Text (`transcript_text=true`)

Use `transcript_text=true` to return the transcript as a single plain-text string instead of an array of `{ text, start, end }` segments:

```bash theme={null}
curl -X POST "https://api.vidnavigator.com/v1/transcript" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://twitter.com/user/status/123456789",
    "transcript_text": "true"
  }'
```

### Getting Metadata Only

If you only need video metadata without the transcript (faster and still counts as usage):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.vidnavigator.com/v1/transcript" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "video_url": "https://www.tiktok.com/@user/video/123456789",
      "metadata_only": true
    }'
  ```

  ```python Python theme={null}
  data = {
      "video_url": "https://www.tiktok.com/@user/video/123456789",
      "metadata_only": True
  }
  response = requests.post(url, headers=headers, json=data)
  ```

  ```javascript JavaScript theme={null}
  const result = await fetch('https://api.vidnavigator.com/v1/transcript', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      video_url: 'https://www.tiktok.com/@user/video/123456789',
      metadata_only: true
    })
  });
  ```
</CodeGroup>

## Limitations

* `https://fb.watch/<video_id>` format is not supported, use the `https://www.facebook.com/watch/?v=<video_id>` format instead.

## Troubleshooting

* **Invalid URL**: Ensure the video URL is complete and valid. This endpoint supports direct links from X (a tweet), Vimeo, TikTok, etc.
* **Transcript Not Found**: Please ensure that the video has subtitles available (either manually added or auto-generated). If no subtitles are present, the transcript cannot be extracted. Consider using `fallback_to_metadata: true` to get metadata even when transcript is unavailable.
* **Language Not Supported**: Sometimes the selected subtitles language is not available. In which case, you will get a clear message stating that. Verify that the chosen language is available for the video. We recommend not using the language input if you are unsure.
* **For YouTube videos**: This endpoint does not support YouTube. Please use the [/youtube/transcript](/api-reference/endpoint/transcript-youtube) endpoint instead.

If issues persist or need more help, please reach out to us at [support@vidnavigator.com](mailto:support@vidnavigator.com).

## Success Response (200 OK)

Returns a `video_info` object and a `transcript` object.

```json theme={null}
{
  "status": "success",
  "data": {
    "video_info": {
      "title": "A Really Cool Video",
      "description": "An example description for the video.",
      "thumbnail": "https://example.com/thumbnail.jpg",
      "url": "https://twitter.com/user/status/123456789",
      "channel": "Example Creator",
      "duration": 45.5,
      "views": 123456,
      "likes": 9876,
      "published_date": "2024-01-15",
      "keywords": ["example", "twitter", "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 sentence.",
        "start": 3.5,
        "end": 5.1
      }
    ]
  }
}
```

### Response with `transcript_text: true`

When you set `transcript_text: true`, the transcript is returned as a single string:

```json theme={null}
{
  "status": "success",
  "data": {
    "video_info": { ... },
    "transcript": "This is the first sentence of the video. And this is the second sentence."
  }
}
```

### Response with `metadata_only: true`

When you set `metadata_only: true`, only the video metadata is returned:

```json theme={null}
{
  "status": "success",
  "data": {
    "video_info": {
      "title": "A Really Cool Video",
      "description": "An example description for the video.",
      "thumbnail": "https://example.com/thumbnail.jpg",
      "url": "https://twitter.com/user/status/123456789",
      "channel": "Example Creator",
      "duration": 45.5,
      "views": 123456,
      "likes": 9876,
      "published_date": "2024-01-15"
    }
  }
}
```


## OpenAPI

````yaml POST /transcript
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:
  /transcript:
    post:
      tags:
        - Transcripts
      summary: Get transcript for non-YouTube videos
      description: >-
        Extract transcript from non-YouTube online videos (Vimeo, Twitter/X,
        TikTok, Facebook, Instagram, Dailymotion, Loom, etc.) with optional
        language selection.


        **For YouTube videos, use `/youtube/transcript` instead.**


        Options:

        - `transcript_text=true`: Returns the transcript as a single plain-text
        string instead of an array of segments.

        - `metadata_only=true`: Returns only video metadata (no transcript).

        - `fallback_to_metadata=true`: If transcript is unavailable, returns
        video metadata with an empty transcript instead of a 404 error (ignored
        when `metadata_only=true`).
      operationId: getTranscript
      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 retrieve transcript for
                  example: https://twitter.com/user/status/123456789
                language:
                  type: string
                  minLength: 2
                  maxLength: 2
                  description: ISO2 language code (optional)
                  example: en
                metadata_only:
                  type: boolean
                  default: false
                  description: >-
                    When true, returns only video metadata without transcript.
                    Usage is still recorded.
                fallback_to_metadata:
                  type: boolean
                  default: false
                  description: >-
                    When true, returns video metadata with an empty transcript
                    if transcript is unavailable (200). Ignored if metadata_only
                    is true.
                transcript_text:
                  type: boolean
                  default: false
                  description: >-
                    When true, returns the transcript as a single plain-text
                    string instead of an array of segments.
      responses:
        '200':
          description: Transcript retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  data:
                    type: object
                    properties:
                      video_info:
                        $ref: '#/components/schemas/VideoInfo'
                      transcript:
                        $ref: '#/components/schemas/TranscriptOutput'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/ContentRestricted'
        '404':
          $ref: '#/components/responses/VideoNotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '451':
          $ref: '#/components/responses/GeoRestricted'
        '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
    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:
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
              message:
                type: string
    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
    ContentRestricted:
      description: Content restricted - requires login or age verification
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - content_restricted
              message:
                type: string
    VideoNotFound:
      description: Video not found or transcript unavailable
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - video_not_found
                  - transcript_not_available
              message:
                type: string
    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - limit_exceeded
              message:
                type: string
              usage:
                type: integer
              limit:
                type: integer
    GeoRestricted:
      description: Content not available in your region
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - geo_restricted
              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.

````