{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Download API: Video and Audio (MP4, MP3, M4A)",
    "description": "Download YouTube videos and audio by API. MP4 from 144p to 4K with sound, or M4A, MP3 and Opus audio. One row per link with a stable file link, size, checksum and duration. Pay per minute delivered; failed and skipped videos are free.",
    "version": "0.1",
    "x-build-id": "0Z0lsmBJLjPkhTSVe"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/johnvc~youtube-download-api/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-johnvc-youtube-download-api",
        "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/johnvc~youtube-download-api/runs": {
      "post": {
        "operationId": "runs-sync-johnvc-youtube-download-api",
        "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/johnvc~youtube-download-api/run-sync": {
      "post": {
        "operationId": "run-sync-johnvc-youtube-download-api",
        "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": "YouTube video links",
            "type": "array",
            "description": "YouTube video links or 11-character video IDs to download. Accepts watch links (youtube.com/watch?v=...), short links (youtu.be/...), Shorts links (youtube.com/shorts/...), embed and live-replay links. Up to 200 per run. Example: [\"https://www.youtube.com/watch?v=jNQXAC9IVRw\"].",
            "items": {
              "type": "string"
            }
          },
          "format": {
            "title": "What to download",
            "enum": [
              "audio",
              "video"
            ],
            "type": "string",
            "description": "Choose 'audio' for an audio-only file (smallest and cheapest, ideal for transcription and AI pipelines) or 'video' for a video file with sound included. Default: audio.",
            "default": "audio"
          },
          "quality": {
            "title": "Video quality",
            "enum": [
              "144p",
              "240p",
              "360p",
              "480p",
              "720p",
              "1080p",
              "1440p",
              "2160p"
            ],
            "type": "string",
            "description": "Maximum video resolution, used when format is 'video'. If the video is not offered at this quality, the highest available quality below it is delivered and billed at its own rate. Default: 720p.",
            "default": "720p"
          },
          "audioFormat": {
            "title": "Audio file type",
            "enum": [
              "m4a",
              "mp3",
              "opus"
            ],
            "type": "string",
            "description": "File type for audio downloads, used when format is 'audio'. M4A and Opus are delivered without re-encoding; MP3 is converted. Default: m4a.",
            "default": "m4a"
          },
          "audioQuality": {
            "title": "Audio quality",
            "enum": [
              "standard",
              "high"
            ],
            "type": "string",
            "description": "'standard' delivers a compact stream that is clear for speech, podcasts, lectures and transcription. 'high' delivers the best audio stream YouTube offers. Default: standard.",
            "default": "standard"
          },
          "videoCodec": {
            "title": "Video codec preference",
            "enum": [
              "smallest",
              "h264"
            ],
            "type": "string",
            "description": "'smallest' delivers the most efficient stream at the chosen quality (AV1 or VP9 when offered), which gives the smallest file. 'h264' delivers H.264 where YouTube offers it (up to 1080p), which plays on every device and editor. Default: smallest.",
            "default": "smallest"
          },
          "metadataOnly": {
            "title": "Metadata only (free)",
            "type": "boolean",
            "description": "Return title, channel, duration, available qualities and estimated file sizes without downloading anything. Free. Use it to check a list before spending. Default: false.",
            "default": false
          },
          "maxMinutes": {
            "title": "Skip videos longer than (minutes)",
            "minimum": 1,
            "maximum": 720,
            "type": "integer",
            "description": "Videos longer than this many minutes are skipped at no charge, before anything is downloaded. Leave empty for no limit. Example: 60."
          },
          "maxMegabytes": {
            "title": "Skip files larger than (MB)",
            "minimum": 1,
            "maximum": 20000,
            "type": "integer",
            "description": "Files estimated to be larger than this many megabytes are skipped at no charge, before anything is downloaded. Leave empty for no limit. Example: 500."
          },
          "maxAgeDays": {
            "title": "Reuse cached metadata up to (days)",
            "minimum": 0,
            "maximum": 90,
            "type": "integer",
            "description": "Metadata-only answers and length checks may be served from a cache when the same video was checked within this many days. Media files are always downloaded fresh. Set 0 to always check YouTube. Default: 7.",
            "default": 7
          },
          "storageProvider": {
            "title": "Where to store files",
            "enum": [
              "apify",
              "s3",
              "gcs",
              "azure"
            ],
            "type": "string",
            "description": "Where the downloaded files are delivered. 'apify' (default) keeps them in this run's key-value store. Choose 's3' for Amazon S3 or any S3-compatible storage (Cloudflare R2, Backblaze B2, Wasabi, DigitalOcean Spaces, MinIO), 'gcs' for Google Cloud Storage, or 'azure' for Azure Blob Storage. Files sent to your own storage are not kept in the key-value store.",
            "default": "apify"
          },
          "storageBucket": {
            "title": "Bucket name",
            "type": "string",
            "description": "For 's3' and 'gcs': the bucket name only, with no slashes. Example: my-video-archive."
          },
          "storagePrefix": {
            "title": "Folder prefix",
            "type": "string",
            "description": "Optional folder inside the bucket or container. Example: youtube/2026/ stores files as youtube/2026/<videoId>_<quality>.<ext>."
          },
          "storageRegion": {
            "title": "Region",
            "type": "string",
            "description": "For 's3': the bucket's region, for example us-east-1 or eu-west-1. Use 'auto' for Cloudflare R2. Not needed for 'gcs' or 'azure'. Default: us-east-1."
          },
          "storageEndpoint": {
            "title": "Custom endpoint",
            "type": "string",
            "description": "For S3-compatible storage other than Amazon: the https endpoint, for example https://<account>.r2.cloudflarestorage.com for Cloudflare R2 or https://s3.us-west-004.backblazeb2.com for Backblaze B2. Leave empty for Amazon S3 and for Google Cloud Storage."
          },
          "storageAccessKeyId": {
            "title": "Access key ID",
            "type": "string",
            "description": "For 's3': an access key ID with permission to write objects to the bucket. For 'gcs': an HMAC access ID from Cloud Storage settings, Interoperability tab. Stored as a secret."
          },
          "storageSecretAccessKey": {
            "title": "Secret access key",
            "type": "string",
            "description": "For 's3': the secret access key. For 'gcs': the HMAC secret that belongs to the access ID. Stored as a secret."
          },
          "storageSasUrl": {
            "title": "Azure container SAS URL",
            "type": "string",
            "description": "For 'azure': the container URL including a SAS token with write permission, in the form https://<account>.blob.core.windows.net/<container>?sv=...&sig=... Stored as a secret."
          },
          "cookies": {
            "title": "Cookies (optional, for restricted videos)",
            "type": "string",
            "description": "Optional. Cookies from your own signed-in YouTube session in Netscape cookies.txt format, needed only for age-restricted or members-only videos you have access to. Stored as a secret. Your session, your responsibility: leave empty for normal public videos."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}