{
  "openapi": "3.0.1",
  "info": {
    "title": "Video Transcript & Subtitle Extractor",
    "description": "Extract transcripts, subtitles and captions from video URLs on 1,000+ platforms, including YouTube, Vimeo, TikTok, Instagram, X, Facebook, Twitch and TED. Native captions first, Whisper AI when none exist; output JSON, SRT, VTT, text or Markdown.",
    "version": "0.5",
    "x-build-id": "iBXdZcEm34u4iWyeU"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~video-subtitle-extractor/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-video-subtitle-extractor",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/khadinakbar~video-subtitle-extractor/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-video-subtitle-extractor",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/khadinakbar~video-subtitle-extractor/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-video-subtitle-extractor",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "videoUrls"
        ],
        "properties": {
          "videoUrls": {
            "title": "Video URLs",
            "type": "array",
            "description": "Public video URLs to extract transcripts and subtitles from, on 1,000+ supported sites (YouTube, Vimeo, TikTok, Instagram, X/Twitter, Facebook, Twitch, Dailymotion, TED, Bilibili, SoundCloud, Reddit and more). YouTube playlist and channel URLs are expanded into individual videos (see maxVideosPerPlaylist). NOT a search query — use full https:// URLs.",
            "items": {
              "type": "object"
            }
          },
          "maxVideosPerPlaylist": {
            "title": "Max videos per playlist or channel",
            "minimum": 0,
            "maximum": 500,
            "type": "integer",
            "description": "For YouTube playlist (youtube.com/playlist?list=…) or channel URLs (youtube.com/@handle, /channel/…, /videos, /shorts tabs), process up to this many newest listed videos. Each video with a transcript is billed as one transcript. Defaults to 20. Set 0 to disable expansion. Single video URLs are not affected.",
            "default": 20
          },
          "preferredLanguages": {
            "title": "Preferred caption languages (priority order)",
            "type": "array",
            "description": "ISO 639-1 language codes in priority order. The first available match is returned (e.g., ['en', 'es'] picks English if present, else Spanish). Use 'auto' to accept any language. Defaults to ['en']. NOT a translation target — for translation set 'translateTo'.",
            "default": [
              "en"
            ],
            "items": {
              "type": "string"
            }
          },
          "outputFormat": {
            "title": "Output format",
            "enum": [
              "json",
              "srt",
              "vtt",
              "text",
              "markdown"
            ],
            "type": "string",
            "description": "Format of the transcript field in each result. 'json' returns timestamped segments (best for AI/programmatic use). 'srt' or 'vtt' returns standard subtitle file format strings. 'text' is plain unformatted text. 'markdown' is LLM-ready with timestamps as headings. Defaults to 'json'. Raw .srt/.vtt files are also saved to the key-value store regardless of this setting.",
            "default": "json"
          },
          "useWhisperFallback": {
            "title": "Use Whisper AI when no captions available",
            "type": "boolean",
            "description": "If a video has no native captions, transcribe its audio with OpenAI Whisper. Adds $0.02 per minute of audio to the run cost (vs $0.005 flat for caption extraction). Native captions are the default reliable path; enable this only when an OpenAI API key is supplied or Whisper coverage is explicitly desired.",
            "default": false
          },
          "whisperModel": {
            "title": "Whisper model",
            "enum": [
              "whisper-1"
            ],
            "type": "string",
            "description": "Whisper model used for AI fallback transcription. 'whisper-1' is OpenAI's hosted model (fastest, best accuracy). Only used when 'useWhisperFallback' is true. Ignored otherwise.",
            "default": "whisper-1"
          },
          "openaiApiKey": {
            "title": "OpenAI API key (optional, BYOK)",
            "type": "string",
            "description": "Bring your own OpenAI API key to bypass the Whisper per-minute charge — you pay OpenAI directly (~$0.006/min) and the actor only charges $0.005 per video processed. Leave empty to use the platform's Whisper service ($0.02/min). Stored only for the duration of one run."
          },
          "translateTo": {
            "title": "Translate captions to (optional)",
            "type": "string",
            "description": "ISO 639-1 code to translate captions into using YouTube's auto-translation (e.g., 'es', 'fr', 'de'). Only works for YouTube videos with captions. Leave empty to keep the original language. NOT supported on Whisper fallback (Whisper detects language but does not translate).",
            "default": ""
          },
          "includeAutoCaptions": {
            "title": "Include auto-generated captions",
            "type": "boolean",
            "description": "Accept YouTube's automatic speech-recognition captions (lower quality but cover more videos). Set false to require human-uploaded captions only. Defaults to true.",
            "default": true
          },
          "maxDurationMinutes": {
            "title": "Max video duration (minutes)",
            "minimum": 0,
            "maximum": 600,
            "type": "integer",
            "description": "Maximum duration for Whisper AI fallback. Prevents runaway transcription costs on long podcasts or lectures. Native/manual/auto captions are still extracted from longer videos because they do not incur per-minute Whisper charges. Defaults to 120 minutes (2 hours). Set to 0 for no Whisper duration cap.",
            "default": 120
          },
          "perVideoTimeoutSecs": {
            "title": "Per-video time limit (seconds)",
            "minimum": 60,
            "maximum": 3600,
            "type": "integer",
            "description": "Maximum time spent on one video before it is skipped with a video_timeout note in the FAILURES record, so one slow or stuck video cannot use up the whole run. Defaults to 900 seconds. Raise it for very long Whisper transcriptions. Range 60–3600.",
            "default": 900
          },
          "includeMetadata": {
            "title": "Include video metadata",
            "type": "boolean",
            "description": "Add title, channel, duration, viewCount, uploadDate, thumbnail to each result. Disable for minimal output (transcript only). Defaults to true.",
            "default": true
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Optional custom or Apify proxy settings. When left blank, the actor uses its managed mobile proxy. Supply your own proxy only when you need to control egress or billing.",
            "default": {
              "useApifyProxy": false
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}