{
  "openapi": "3.1.0",
  "info": {
    "title": "VidTwo Media API",
    "version": "1.0.0",
    "description": "High-performance social video, reels, stories, audio, and photo extraction and download API supporting YouTube, Instagram, Facebook, TikTok, Pinterest, Reddit, and Twitter/X.",
    "contact": {
      "name": "VidTwo Support",
      "url": "https://www.vidtwo.com/contact"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.vidtwo.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://www.vidtwo.com",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/extract": {
      "post": {
        "summary": "Extract social media details and direct stream links",
        "operationId": "extractMedia",
        "description": "Parses a valid public video, post, reel, or photo URL from supported platforms and returns media streams, resolutions, thumbnails, and download links.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Public social media URL (e.g. YouTube, Instagram, TikTok, Facebook, Pinterest, Reddit, X)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully extracted media details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExtractResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid URL or extraction failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Extract social media details via query parameter",
        "operationId": "extractMediaGet",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Public social media URL"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully extracted media details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExtractResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/download": {
      "get": {
        "summary": "Stream or download media file",
        "operationId": "downloadMedia",
        "description": "Directly streams or pipes audio/video file with Content-Disposition headers for seamless client downloading.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Target video or media stream URL"
          },
          {
            "name": "filename",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Custom downloaded file name"
          }
        ],
        "responses": {
          "200": {
            "description": "Media binary stream (MP4, MP3, JPG, etc.)",
            "content": {
              "video/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/mpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    },
    "/api/download-zip": {
      "post": {
        "summary": "Download batch items or playlist as ZIP archive",
        "operationId": "downloadZip",
        "description": "Bundles multiple video or photo items into a single compressed ZIP file.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["items"],
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": ["url"],
                      "properties": {
                        "url": { "type": "string", "format": "uri" },
                        "filename": { "type": "string" }
                      }
                    }
                  },
                  "zipName": {
                    "type": "string",
                    "default": "vidtwo_download.zip"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Binary ZIP archive stream",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ExtractResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "title": { "type": "string" },
              "thumbnail": { "type": "string" },
              "platform": { "type": "string" },
              "duration": { "type": "number" },
              "medias": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "url": { "type": "string" },
                    "quality": { "type": "string" },
                    "extension": { "type": "string" },
                    "type": { "type": "string" },
                    "formattedSize": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "error": { "type": "string" }
        }
      }
    }
  }
}