Importly
DocumentationDashboard

Metadata Endpoint

Purpose

Quickly retrieve metadata (e.g., title, duration, available formats) from a publicly accessible media URL—before deciding whether to download.

Overview

Use the /metadata endpoint to preview essential details about the media at a given URL. This can help you:

  • Decide which quality option you want (low, medium, or high).
  • Confirm that the media is accessible and valid.
  • Estimate how many credits you'll spend if you decide to import.

Parameters

You can pass parameters via query string or JSON body (if you prefer a POST request). The most common usage pattern is GET + query params.

ParameterTypeDescription
url*string

Publicly accessible URL pointing to video or audio content.

Note: You can pass authentication via the Authorization: Bearer <API_KEY> header for every request.

Example Request (GET)

curl -X GET "https://api.importly.io/metadata?url=https://example.com/video.mp4" \
     -H "Authorization: Bearer YOUR_API_KEY"

Example Response (Initial Queue)

{
  "success": true,
  "data": {
    "jobId": "abc123",
    "status": "queued",
    "message": "Metadata request queued. You will receive a webhook when it's complete."
  }
}

Example Response (Completed)

{
  "success": true,
  "data": {
    "title": "Sample Video",
    "duration": 314,
    "availableFormats": [
      {
        "formatId": "preset_1080p",
        "selector": "bestvideo[height<=1080][vcodec^=avc1]/.../best[height<=1080]",
        "ext": "mp4",
        "quality": "1080p",
        "costInCredits": 30,
        "description": "1080p (best quality up to 1080p with audio)",
        "height": 1080,
        "isAudioOnly": false,
        "codec": {
          "video": "h264",
          "audio": "aac"
        }
      },
      {
        "formatId": "preset_720p",
        "selector": "bestvideo[height<=720][vcodec^=avc1]/.../best[height<=720]",
        "ext": "mp4",
        "quality": "720p",
        "costInCredits": 30,
        "description": "720p (best quality up to 720p with audio)",
        "height": 720,
        "isAudioOnly": false,
        "codec": {
          "video": "h264",
          "audio": "aac"
        }
      },
      {
        "formatId": "preset_480p",
        "selector": "bestvideo[height<=480][vcodec^=avc1]/.../best[height<=480]",
        "ext": "mp4",
        "quality": "480p",
        "costInCredits": 30,
        "description": "480p (best quality up to 480p with audio)",
        "height": 480,
        "isAudioOnly": false,
        "codec": {
          "video": "h264",
          "audio": "aac"
        }
      },
      {
        "formatId": "preset_audio",
        "selector": "bestaudio[ext=m4a]/bestaudio",
        "ext": "m4a",
        "quality": "audio-only",
        "costInCredits": 30,
        "description": "Best available audio quality",
        "isAudioOnly": true,
        "codec": {
          "audio": "aac"
        }
      },
      {
        "formatId": "18",
        "selector": "18",
        "ext": "mp4",
        "quality": "360p",
        "costInCredits": 30,
        "description": "360p, MP4",
        "fileSize": 30665003,
        "height": 360,
        "isAudioOnly": false,
        "codec": {
          "video": "h264",
          "audio": "aac"
        }
      }
    ],
    "thumbnailUrl": "https://example.com/thumbnail.jpg"
  }
}
  • title: Media title or a fallback if no title is available.
  • duration: Duration in seconds, if detectable.
  • availableFormats: Array of available download formats with cost estimates and selectors.
  • thumbnailUrl: Direct URL to a representative thumbnail image, when available.

Available Formats Structure

Each format in the availableFormats array contains:

  • formatId: Unique identifier for this format
  • selector: ytdlp format selector string to use with the import endpoint. For preset formats, this is the full yt-dlp command that will be executed (truncated with ... in examples for readability).
  • ext: File extension (mp4, webm, m4a, etc.)
  • quality: Human-readable quality description (e.g., "720p", "audio-only")
  • costInCredits: Estimated cost in credits for downloading this format
  • description: Detailed human-readable description
  • fileSize: Exact file size in bytes (when available)
  • height: Video height in pixels (for video formats)
  • fps: Frame rate (when available)
  • isAudioOnly: Whether this is an audio-only format
  • language: Audio language code (for multi-language content)
  • codec: Object containing video and/or audio codec information

Format Types

The response includes two types of formats:

Preset Formats (recommended): Standard quality options like 360p, 480p, 720p, 1080p, and audio-only. These use smart format selection to pick the best available streams and combine them when necessary.

Individual Formats: Specific formats available from the source, giving you fine-grained control over exactly what gets downloaded.

Error Handling

  • 400 Bad Request: Missing or invalid url, or the URL points to a playlist (not supported).
  • 404 Not Found: Couldn't locate any media info at the provided url.
  • 401 Unauthorized: Invalid or missing API key.
  • 429 Too Many Requests: Rate-limited—try again later or reduce request frequency.
  • 500 Internal Server Error: Unexpected failure while processing the request.

Best Practices

  • Cache Responses: If your application queries the same URL repeatedly, store the metadata to avoid unnecessary calls.
  • Check Before Import: Use /metadata to avoid incurring unnecessary download costs if the URL is invalid or the content is larger than expected.
  • Use Preset Formats: For most use cases, the preset formats (360p, 720p, etc.) provide the best balance of quality and compatibility.
  • Use the Selector Field: When making import requests, use the selector field from the metadata response to ensure you get exactly the format you want.
  • Consider Cost vs Quality: Compare costInCredits across formats to find the best value for your needs.

Usage with Import Endpoint

Once you have metadata, you can use the selector value directly with the import endpoint:

curl -X GET "https://api.importly.io/import" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://example.com/video.mp4",
       "format": "bestvideo[height<=720][vcodec^=avc1]/.../best[height<=720]"
     }'
EndpointsImport