{
  "openapi": "3.1.0",
  "info": {
    "title": "Media Data API",
    "version": "1.0.0",
    "description": "Extract video, audio, captions, thumbnails and storyboards from YouTube, Vimeo, TikTok and Bilibili and deliver them to your configured storage destination."
  },
  "servers": [
    {
      "url": "https://api.brightdata.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/dca/trigger_hp": {
      "post": {
        "summary": "Trigger a media extraction job",
        "description": "Submits one or more media extraction jobs. Results are delivered to your configured storage destination when each job completes.\n\n> **Access required:** The Media Extraction API is not enabled by default. Contact [support@brightdata.com](mailto:support@brightdata.com) to enable it for your account.\n\n> **Delivery required:** A delivery destination must be configured before sending requests. See [Delivery options](https://docs.brightdata.com/datasets/scrapers/scrapers-library/delivery-options#delivery-options).",
        "operationId": "triggerMediaExtraction",
        "parameters": [
          {
            "name": "collector",
            "in": "query",
            "required": true,
            "description": "Your Media Extraction collector ID. This is a fixed value assigned when the feature is enabled on your account.",
            "schema": {
              "type": "string",
              "example": "YOUR_COLLECTOR_ID"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "A JSON array of extraction job objects. Each object represents one media extraction job. Multiple jobs can be submitted in a single request.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MediaExtractionJob"
                },
                "minItems": 1
              },
              "example": [
                {
                  "url": "https://www.video-page-example.com/v=89438398439",
                  "format": "all_audio_tracks+video",
                  "captions": true,
                  "captions_format": "vtt",
                  "min_height": 720,
                  "max_height": 1440,
                  "thumbnail": true,
                  "storyboards": true
                }
              ]
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job accepted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TriggerResponse"
                },
                "example": {
                  "success": true,
                  "inputs": 1,
                  "job_id": "hp_mn1l61rn1p94ynijur"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. Invalid or missing API key."
          },
          "403": {
            "description": "Forbidden. The Media Extraction API is not enabled for this account. Contact support@brightdata.com."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your Bright Data API key. Find it in the [Bright Data Control Panel](https://brightdata.com/cp/api_keys)."
      }
    },
    "schemas": {
      "MediaExtractionJob": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "The full URL of the video to download. Supported platforms: YouTube, Vimeo, TikTok, Bilibili.",
            "example": "https://www.video-page-example.com/v=89438398439"
          },
          "format": {
            "type": "string",
            "description": "Specifies what content type to download.",
            "default": "full",
            "enum": [
              "full",
              "video_only",
              "audio_only",
              "all_audio_tracks",
              "all_audio_tracks+video",
              "none"
            ],
            "x-enumDescriptions": {
              "full": "Downloads the video with the default audio track.",
              "video_only": "Downloads the video stream without audio.",
              "audio_only": "Downloads the default audio track only.",
              "all_audio_tracks": "Downloads all available audio tracks (for example, multiple languages) without video.",
              "all_audio_tracks+video": "Downloads the video together with all available audio tracks.",
              "none": "Skips media download. Use when you only need captions, thumbnails, or storyboards."
            }
          },
          "captions": {
            "type": "boolean",
            "description": "Whether to download available captions or subtitles for the video.",
            "default": false
          },
          "captions_format": {
            "type": "string",
            "description": "The file format for downloaded captions. Only applies when `captions` is `true`. Supported formats: `vtt`, `srt`, `json3`.",
            "default": "vtt",
            "enum": [
              "vtt",
              "srt",
              "json3"
            ]
          },
          "min_height": {
            "type": "integer",
            "description": "Minimum accepted video resolution, expressed as a vertical pixel count. The download proceeds only if a resolution at or above this height is available. Common values: 360, 480, 720, 1080, 1440, 2160.",
            "example": 720
          },
          "max_height": {
            "type": "integer",
            "description": "Maximum accepted video resolution, expressed as a vertical pixel count. The download proceeds only if a resolution at or below this height is available. Common values: 360, 480, 720, 1080, 1440, 2160.",
            "example": 1440
          },
          "thumbnail": {
            "type": "boolean",
            "description": "Whether to include the video's thumbnail image in the results.",
            "default": false
          },
          "storyboards": {
            "type": "boolean",
            "description": "Whether to include the video's storyboard images (sprite sheets used for timeline preview scrubbing) in the results.",
            "default": false
          }
        }
      },
      "TriggerResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "`true` when the job was accepted."
          },
          "inputs": {
            "type": "integer",
            "description": "Number of download jobs submitted."
          },
          "job_id": {
            "type": "string",
            "description": "Unique identifier for the submitted job."
          }
        }
      }
    }
  }
}