{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube All-in-One Downloader & Scraper",
    "description": "Download YouTube videos, Shorts, playlists, and channels as MP4. Up to 10 concurrent downloads with no browser needed. Extract comments, captions, and rich metadata. Metadata-only mode for fast, cheap research. Quality selection with automatic fallback. From $0.10/video.",
    "version": "0.3",
    "x-build-id": "qIR21oXdSuOW6LrvI"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/jy-labs~youtube-all-in-one-downloader-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-jy-labs-youtube-all-in-one-downloader-scraper",
        "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/jy-labs~youtube-all-in-one-downloader-scraper/runs": {
      "post": {
        "operationId": "runs-sync-jy-labs-youtube-all-in-one-downloader-scraper",
        "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/jy-labs~youtube-all-in-one-downloader-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-jy-labs-youtube-all-in-one-downloader-scraper",
        "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",
        "properties": {
          "startUrls": {
            "title": "YouTube URLs",
            "type": "array",
            "description": "Add one or more YouTube URLs to download. You can mix different types of URLs in a single run.",
            "items": {
              "type": "string"
            }
          },
          "searchQueries": {
            "title": "Search Queries",
            "type": "array",
            "description": "Search YouTube for videos matching these queries. Each query returns up to maxVideos results. Combined with startUrls if both are provided.",
            "items": {
              "type": "string"
            }
          },
          "quality": {
            "title": "Video Quality",
            "enum": [
              "highest",
              "1080p",
              "720p",
              "480p",
              "360p",
              "audio_only"
            ],
            "type": "string",
            "description": "Choose your preferred video quality. If the selected quality is not available for a video, the actor will automatically fall back to the closest lower quality.",
            "default": "highest"
          },
          "downloadVideo": {
            "title": "Download Video File",
            "type": "boolean",
            "description": "When enabled (default), the actor downloads the video file and stores it in Key-Value Store. Disable this to extract only metadata, captions, and comments without downloading the actual video -- significantly faster and cheaper.",
            "default": true
          },
          "downloadThumbnail": {
            "title": "Download Thumbnail Image",
            "type": "boolean",
            "description": "When enabled, the actor downloads the highest quality thumbnail image for each video and stores it in the Key-Value Store. The download URL is included in the output.",
            "default": false
          },
          "maxVideos": {
            "title": "Maximum Videos",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Limit the total number of videos to download. This is especially useful when downloading from playlists or channels to control costs and run time.",
            "default": 100
          },
          "filenameTemplate": {
            "title": "Filename Template",
            "type": "string",
            "description": "Custom filename template for downloaded files. Available placeholders: {videoId}, {title}, {quality}, {channelName}, {date}, {type}. Invalid filename characters are automatically removed.",
            "default": "{videoId}_{type}"
          },
          "extractMetadata": {
            "title": "Extract Video Metadata",
            "type": "boolean",
            "description": "When enabled (default), each result will include full video metadata: title, description, channel info, view/like counts, duration, tags, thumbnail URL, chapters, and category. When disabled, only the source URL and download link are returned.",
            "default": true
          },
          "outputFormat": {
            "title": "Output Format",
            "enum": [
              "default",
              "llm_ready"
            ],
            "type": "string",
            "description": "Choose the output format. 'default' returns full metadata with download URLs. 'llm_ready' returns a flat structure optimized for AI/LLM pipelines with clean transcript text, word count, and minimal metadata — ideal for RAG, embeddings, and fine-tuning.",
            "default": "default"
          },
          "extractCaptions": {
            "title": "Extract Captions / Subtitles",
            "type": "boolean",
            "description": "When enabled, the actor will extract available captions (subtitles) from each video. The full transcript text is included in the output. This also enables metadata extraction automatically.",
            "default": false
          },
          "downloadCaptions": {
            "title": "Download Caption File (SRT/VTT)",
            "type": "boolean",
            "description": "When enabled, the actor downloads caption files in the specified format (SRT or VTT) and stores them in the Key-Value Store. The download URL is included in the output.",
            "default": false
          },
          "captionFormat": {
            "title": "Caption File Format",
            "enum": [
              "srt",
              "vtt"
            ],
            "type": "string",
            "description": "Format for downloaded caption files. SRT is widely compatible, VTT is the web standard. Only applies when 'Download Caption File' is enabled.",
            "default": "srt"
          },
          "captionLanguage": {
            "title": "Preferred Caption Language",
            "pattern": "^[a-z]{2,3}(-[A-Za-z]{2,4})?$",
            "type": "string",
            "description": "The language code for captions you want to extract (e.g., 'en' for English, 'ko' for Korean, 'ja' for Japanese, 'es' for Spanish). If the preferred language is not available, the first available language will be used instead. Only applies when 'Extract Captions' or 'Download Caption File' is enabled.",
            "default": "en"
          },
          "autoTranslateLanguage": {
            "title": "Auto-Translate Captions Language",
            "pattern": "^[a-z]{2,3}(-[A-Za-z]{2,4})?$",
            "type": "string",
            "description": "Automatically translate captions to this language using YouTube's built-in translation. For example, set to 'en' to get English translations of Korean, Japanese, or any other language video. Uses YouTube's 'tlang' parameter. Language code format: 'en', 'ko', 'ja', 'es', 'fr', etc. Only applies when 'Extract Captions' or output format is 'LLM-Ready'."
          },
          "extractComments": {
            "title": "Extract Comments",
            "type": "boolean",
            "description": "When enabled, the actor will extract top comments from each video. Comment data includes author, text, like count, and timestamp. This also enables metadata extraction automatically.",
            "default": false
          },
          "extractReplies": {
            "title": "Extract Comment Replies",
            "type": "boolean",
            "description": "When enabled with 'Extract Comments', the actor will also extract reply threads for each comment. This increases processing time but provides full conversation context.",
            "default": false
          },
          "maxComments": {
            "title": "Max Comments Per Video",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Maximum number of comments to extract per video. Higher values increase run time and cost. Only applies when 'Extract Comments' is enabled.",
            "default": 100
          },
          "extractChannelInfo": {
            "title": "Extract Channel Info",
            "type": "boolean",
            "description": "When enabled with metadata extraction, adds detailed channel information including subscriber count, description, banner URL, and video count.",
            "default": false
          },
          "extractRelatedVideos": {
            "title": "Extract Related Videos",
            "type": "boolean",
            "description": "When enabled, extracts a list of related/suggested videos for each processed video. Up to 20 related videos are included with title, channel, view count, and duration.",
            "default": false
          },
          "monitorMode": {
            "title": "Monitor Mode (Incremental)",
            "type": "boolean",
            "description": "When enabled, the actor remembers previously processed video IDs using a named state store. On subsequent runs with the same state store name, only new videos are processed. This is ideal for scheduled runs monitoring channels or playlists for new content. Requires 'State Store Name' to be set.",
            "default": false
          },
          "stateStoreName": {
            "title": "State Store Name",
            "type": "string",
            "description": "Name of the Key-Value Store used to persist processed video IDs between runs. Use a descriptive name like 'my-channel-monitor'. Different monitoring jobs should use different store names. Only applies when 'Monitor Mode' is enabled."
          },
          "webhookUrl": {
            "title": "Webhook URL",
            "type": "string",
            "description": "Optional URL to receive a POST notification when all processing completes. The webhook payload includes processing statistics (processed count, failed count, success rate, total time)."
          },
          "maxConcurrency": {
            "title": "Parallel Downloads",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Number of videos to download at the same time. Higher values finish faster but use more memory. Reduce this if you experience out-of-memory errors.",
            "default": 4
          },
          "maxRequestRetries": {
            "title": "Retry Attempts",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "How many times to retry downloading a video if it fails (e.g., due to network issues or rate limiting). Each retry uses exponential backoff with smart error classification (longer delays for rate-limiting, no retries for permanent failures).",
            "default": 3
          },
          "includeFailedVideos": {
            "title": "Include Failed Videos in Output",
            "type": "boolean",
            "description": "When enabled, videos that failed to download (after all retries) will still appear in the output dataset with an error message. Useful for debugging or tracking which videos could not be processed.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy Configuration",
            "type": "object",
            "description": "Configure a proxy to avoid YouTube rate limiting and geo-restrictions. Enabled by default with Apify Proxy. RESIDENTIAL group is recommended for best reliability. Note: Proxy usage incurs additional costs (billed per GB of data transferred). You can disable this to reduce costs, but YouTube may block or rate-limit requests.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}