openapi: 3.0.0
info:
  title: TikTok Transcripts API
  description: |
    TikTok Transcripts API allows you to retrieve the transcript (captions) of a single TikTok video from its URL. You get timestamped caption segments and the list of available caption languages for the video.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: TikTok Transcript Retrieval
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["tiktok_transcripts"]
        - name: url
          in: query
          required: false
          description: TikTok video URL. Accepts /video/ URLs as well as vm./vt.tiktok.com and tiktok.com/t/ share links. Required if video_id and username are not provided; cannot be combined with them
          schema:
            type: string
        - name: video_id
          in: query
          required: false
          description: Numeric TikTok video ID. Alternative to url; must be paired with username.
          schema:
            type: string
            pattern: '^\d+$'
        - name: username
          in: query
          required: false
          description: TikTok creator username (with or without the @ symbol). Alternative to url; must be paired with video_id.
          schema:
            type: string
            pattern: '^@?[a-zA-Z0-9_.]{1,24}$'
        - name: language
          in: query
          required: false
          description: >-
            ISO caption language code (e.g. en, eng, pt-BR). An exact match against available_languages is
            preferred (en, eng, and eng-US all select English); otherwise the base language is used, so
            regioned codes like fr-CA stay distinct. Defaults to the original caption
          schema:
            type: string
            pattern: '^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8}){0,2}$'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        transcripts:
          type: array
          items:
            $ref: '#/components/schemas/Transcript'
          description: Array of transcript segments with timing information
        available_languages:
          type: array
          items:
            $ref: '#/components/schemas/AvailableLanguage'
          description: List of available caption languages for this video
        error:
          type: string
          description: Error message if the transcript could not be retrieved
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: TikTok URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used
        url:
          type: string
          description: TikTok video URL
        video_id:
          type: string
          description: TikTok video ID requested
        username:
          type: string
          description: TikTok username requested
        language:
          type: string
          description: Caption language code
    Transcript:
      type: object
      properties:
        text:
          type: string
          description: The transcript text content
        start:
          type: number
          description: Start time of this transcript segment in seconds
        duration:
          type: number
          description: Duration of this transcript segment in seconds
    AvailableLanguage:
      type: object
      properties:
        name:
          type: string
          description: Display name of the language
        lang:
          type: string
          description: The track's full language code, including the region when TikTok defines one (e.g. en, pt-BR, fr-CA)
        is_selected:
          type: boolean
          description: Present and true on the language the returned transcript is in
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong