{
  "openapi": "3.0.1",
  "info": {
    "title": "Video Subtitle & Caption Extractor",
    "description": "Extract subtitles, captions, and AI transcripts from any video URL across 1000+ platforms (YouTube, Vimeo, TikTok, Instagram, X/Twitter, Facebook, Twitch, TED, Bilibili). Native captions first, Whisper AI fallback when none. JSON, SRT, VTT, text, or LLM-ready markdown.",
    "version": "0.2",
    "x-build-id": "i1XGF4kjiNtiqY1ZB"
  },
  "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 subtitles from. Works on 1000+ sites supported by yt-dlp (YouTube, Vimeo, TikTok, Instagram, X/Twitter, Facebook, Twitch, Dailymotion, TED, Bilibili, SoundCloud, Reddit, etc.). Each item is one video — for playlists or channels, expand to individual video URLs first. NOT a search query — must be a full URL with https://.",
            "items": {
              "type": "object"
            }
          },
          "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). Disable to skip videos that lack captions. Defaults to true.",
            "default": true
          },
          "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": "Skip videos longer than this many minutes. Prevents runaway costs on long podcasts/lectures when Whisper fallback is on. Defaults to 120 minutes (2 hours). Set to 0 for no cap.",
            "default": 120
          },
          "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": "Apify proxy used to reach geo-locked or rate-limited videos. Defaults to residential proxies — switch to datacenter for cheaper runs on uncontested sites.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}