{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube to MP3 Downloader",
    "description": "Convert authorized YouTube videos and playlists to MP3 (or m4a, opus, wav, flac) with chosen bitrate, ID3 tags and thumbnail cover art. Saves each track to Apify key-value storage and returns MCP-ready JSON. Built for AI agents and SEO.",
    "version": "1.0",
    "x-build-id": "hbhUZ7GWKdhEu6XeV"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~youtube-to-mp3-downloader/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-youtube-to-mp3-downloader",
        "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~youtube-to-mp3-downloader/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-youtube-to-mp3-downloader",
        "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~youtube-to-mp3-downloader/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-youtube-to-mp3-downloader",
        "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 or playlist URLs",
            "type": "array",
            "description": "Full YouTube URLs to convert to audio, for example https://www.youtube.com/watch?v=dQw4w9WgXcQ. Accepts youtube.com/watch, youtu.be, Shorts, embed and (with the playlist toggle) playlist URLs. Defaults to one sample URL. NOT a search query or channel scraper.",
            "items": {
              "type": "object"
            }
          },
          "authorizationConfirmed": {
            "title": "I have permission to download this audio",
            "type": "boolean",
            "description": "Confirms you own the audio, have the rights holder's permission, or are otherwise legally allowed to download it. The run stops with a warning and downloads nothing when this is false. Defaults to false so accidental runs never download media. NOT a way to bypass YouTube rights or access controls.",
            "default": false
          },
          "audioFormat": {
            "title": "Audio format",
            "enum": [
              "mp3",
              "m4a",
              "opus",
              "wav",
              "flac"
            ],
            "type": "string",
            "description": "Output audio format for every track. mp3 is the most compatible, m4a/opus are efficient lossy formats, and wav/flac are lossless. Defaults to mp3. NOT a video format — this actor only produces audio.",
            "default": "mp3"
          },
          "audioBitrate": {
            "title": "Audio bitrate (kbps)",
            "enum": [
              "best",
              "320",
              "256",
              "192",
              "128"
            ],
            "type": "string",
            "description": "Target bitrate for lossy formats (mp3, m4a, opus). 320 is highest quality, 128 is smallest file, and best keeps the source quality using VBR. Defaults to 192. Ignored for lossless wav and flac.",
            "default": "192"
          },
          "embedMetadata": {
            "title": "Embed ID3 tags and cover art",
            "type": "boolean",
            "description": "Write ID3 metadata (title, artist, upload date) and embed the video thumbnail as cover art into each file. Defaults to true so files show up correctly in music players. Turn off for slightly faster, smaller, tag-free files. NOT related to the separate raw metadata JSON option.",
            "default": true
          },
          "includePlaylist": {
            "title": "Expand playlist URLs",
            "type": "boolean",
            "description": "When on, a playlist URL is expanded and every track (up to the max results cap) is downloaded. When off, only the single video in the URL is used. Defaults to false. NOT a channel crawler — it only follows the specific playlist you provide.",
            "default": false
          },
          "maxResults": {
            "title": "Max tracks per run",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Hard cap on the total number of audio tracks saved across all input URLs and expanded playlists. Defaults to 20 and accepts 1 to 200. Use this to bound cost, because each saved track is billed. NOT a per-playlist limit — it applies to the whole run.",
            "default": 20
          },
          "maxDurationMinutes": {
            "title": "Max duration in minutes",
            "minimum": 1,
            "maximum": 720,
            "type": "integer",
            "description": "Skip videos longer than this many minutes before downloading. Defaults to 120 minutes and accepts 1 to 720. Use it to avoid long livestreams or podcasts. NOT a clip length — the actor downloads the full track when it passes this cap.",
            "default": 120
          },
          "maxFileSizeMb": {
            "title": "Max file size in MB",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Delete and mark a track as skipped if the final audio file is larger than this limit. Defaults to 100 MB and accepts 1 to 500. Lower it for agent workflows where small files matter. NOT a compression target.",
            "default": 100
          },
          "includeMetadataJson": {
            "title": "Save raw metadata JSON",
            "type": "boolean",
            "description": "Also save the full yt-dlp metadata JSON for each successful track to the key-value store. Useful for audits and downstream processing. Defaults to false to keep storage lean. NOT required for the dataset row, which always includes concise metadata.",
            "default": false
          },
          "cookiesTxt": {
            "title": "YouTube cookies.txt (optional)",
            "type": "string",
            "description": "Optional Netscape cookies.txt content for age-restricted or members-only videos that need your logged-in YouTube session. Paste only cookies you are allowed to use. Leave empty for public videos. NOT a username or password field."
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apify proxy used for YouTube requests. Residential proxies are enabled by default because datacenter IPs are frequently blocked by YouTube. Change only if you know your target videos work from another network.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}