Media

Nimble Media Download fetches media files (images, videos, audio, documents) directly from any URL using Nimble’s infrastructure. Bypass geo-restrictions and access controls while controlling the exact MIME types you expect — receiving the raw binary file in the response. Two modes are available: Realtime for instant binary downloads, and Async for cloud-based delivery where the file is saved directly to your own storage bucket.

Quick Start

Example Request

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

# The realtime endpoint streams the raw file — use the raw response
response = nimble.media.with_raw_response.run(
    url="https://example.com/product-image.jpg",
    expected_mime_types=["image/*"],
)

with open("image.jpg", "wb") as f:
    f.write(response.read())

import Nimble from "@nimble-way/nimble-js";
import { writeFile } from "node:fs/promises";

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

// The realtime endpoint streams the raw file — use the raw response
const response = await nimble.media
  .run({
    url: "https://example.com/product-image.jpg",
    expected_mime_types: ["image/*"],
  })
  .asResponse();

await writeFile("image.jpg", Buffer.from(await response.arrayBuffer()));

package main

import (
    "context"
    "os"

    nimble "github.com/Nimbleway/nimble-go"
    "github.com/Nimbleway/nimble-go/option"
)

func main() {
    client := nimble.NewClient(option.WithAPIKey("YOUR-API-KEY"))

    // The realtime endpoint streams the raw file — capture the raw body
    var body []byte
    _, err := client.Media.Run(context.Background(), nimble.MediaRunParams{
        URL:               "https://example.com/product-image.jpg",
        ExpectedMimeTypes: []string{"image/*"},
    }, option.WithResponseBodyInto(&body))
    if err != nil {
        panic(err)
    }
    os.WriteFile("image.jpg", body, 0o644)
}

curl -X POST 'https://sdk.nimbleway.com/v2/media' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://example.com/product-image.jpg",
    "expected_mime_types": ["image/*"]
}' \
--output image.jpg

The realtime endpoint returns the raw binary file, so SDK calls must read the raw response as shown above. The CLI prints structured output only — use cURL for one-off downloads from the terminal.

Example Response

The realtime endpoint returns the raw binary file — not JSON. The response Content-Type header will reflect the actual MIME type of the downloaded file (e.g. image/webp, image/jpeg, video/mp4).

< HTTP/2 200
< Content-Type: image/jpeg
< Content-Length: 48291

[binary image data]

How it works

You provide a media URL

Supply the URL of the media file you want to download, along with optional geo-targeting and MIME type filters

Nimble fetches the file

Routes the request through Nimble’s infrastructure - Applies geo-targeting if specified - Validates the response against your expected MIME types

You receive the media

Realtime: The binary file is streamed directly back in the HTTP response - Async: The file is uploaded to your cloud storage bucket and a task ID is returned

Parameters

Supported input parameters for both endpoints:

url - Required

string

required

The URL of the media file to download.Example: https://example.com/product-image.jpg

expected_mime_types

array

List of acceptable MIME types. Wildcards are supported. If the fetched file does not match one of these types, the request will fail.Examples:

["image/*"] — any image format
["image/webp", "image/jpeg"] — specific image formats
["video/mp4"] — MP4 video only
["image/*", "video/mp4"] — images or MP4

If omitted, any MIME type is accepted.

country

string

Fetch the media as if requesting from a specific country. Useful for geo-restricted content.Use ISO Alpha-2 country codes like US, GB, FR, DE, CA, JP, etc.Example: US

locale

string

LCID standard locale for the request. Use auto to automatically select the locale based on the country parameter.Examples:

en-US — English (United States)
en-GB — English (United Kingdom)
fr-FR — French (France)
auto — automatic based on country

Async-only parameters

The following additional parameter is only available on the /media/async endpoint:

storage - Required for async

object

required

Cloud storage destination where the downloaded media file will be saved. Only S3 is currently supported.Fields:

url (required) — Storage path in the format s3://bucket-name/path/
type — Storage provider: s3 (default), gcs, do
object_name — Custom filename without extension (e.g. product-123)

Each object_name must be unique. Submitting two requests with the same name will overwrite the first file. Use a unique prefix or suffix to avoid collisions — for example product_{id} or media_{date}_{timestamp}.

Example:

{
  "storage": {
    "url": "s3://my-bucket/media/",
    "type": "s3",
    "object_name": "product-123"
  }
}

Usage

Realtime download

Download a media file and save it locally:

curl -X POST 'https://sdk.nimbleway.com/v2/media' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://example.com/product-image.jpg"
}' \
--output output.jpg

With MIME type filtering

Validate the response type before accepting the file:

curl -X POST 'https://sdk.nimbleway.com/v2/media' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://example.com/hero-banner.webp",
    "expected_mime_types": ["image/webp", "image/jpeg", "image/png"]
}' \
--output banner.webp

Geo-targeted download

Fetch geo-restricted media from a specific region:

curl -X POST 'https://sdk.nimbleway.com/v2/media' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://example.com/regional-image.jpg",
    "country": "DE",
    "locale": "de-DE",
    "expected_mime_types": ["image/*"]
}' \
--output regional.jpg

Async API

For large files or async workflows, use the async endpoint to have Nimble upload the file directly to your cloud storage bucket.

Parameters

storage.url — Required

string

required

Bucket path where the media file will be saved.Format: s3://bucket-name/path/Example: s3://my-bucket/media/

storage.type

string

default:"s3"

Storage provider. Currently supported: s3 (Amazon S3), gcs (Google Cloud Storage), do (DigitalOcean Spaces).

storage.object_name

string

Custom filename without extension (e.g. product-123). The original file extension is appended automatically.

Cloud storage delivery requires bucket permissions to be configured before use. See Bucket Permissions for setup instructions.

Example Request

Submit a request and receive a task_id immediately — the file is uploaded to your bucket in the background.

cURL

curl -X POST 'https://sdk.nimbleway.com/v2/media/async' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://example.com/product-image.jpg",
    "country": "US",
    "locale": "en-US",
    "expected_mime_types": ["image/*"],
    "storage": {
        "url": "s3://my-bucket/media/",
        "type": "s3",
        "object_name": "product-123"
    }
}'

Response

{
  "status": "success",
  "task": {
    "id": "52907745-7672-470e-1231-a2f8feb52944",
    "state": "pending"
  }
}

Use the task.id to poll for status. The file is ready when task.state returns success.

Polling and cloud storage delivery are both supported. See Callbacks & Delivery for the full guide.

Response

Realtime response

The response body is the raw binary file. Use the Content-Type response header to determine the actual file format.

Header	Description
`Content-Type`	MIME type of the downloaded file (e.g. `image/jpeg`, `image/webp`, `video/mp4`)
`Content-Length`	File size in bytes

Async response

Returns a task object immediately. The file is uploaded to your storage destination in the background.

Example Response

{
  "status": "success",
  "task": {
    "id": "52907745-7672-470e-1231-a2f8feb52944",
    "state": "pending",
    "created_at": "2026-03-02T12:00:00.000Z",
    "modified_at": "2026-03-02T12:00:00.000Z",
    "account_name": "my-account",
    "api_type": "media",
    "input": {
      "url": "https://example.com/product-image.jpg",
      "country": "US",
      "locale": "en-US",
      "expected_mime_types": ["image/*"],
      "storage": {
        "url": "s3://my-bucket/media/",
        "type": "s3",
        "object_name": "product-123"
      }
    }
  }
}

Field	Type	Description
`status`	string	Request status: `success` or `error`
`task.id`	string	Task ID for tracking the async job
`task.state`	string	`pending`, `processing`, `success`, `failed`
`task.input`	object	The original request parameters echoed back

Once the task completes, the media file will be available at the path specified in storage.url + storage.object_name (with the original file extension).

The async endpoint uses cloud-based delivery only — the file is saved directly to your storage bucket. There are no callback URLs for this endpoint.

Use cases

Product Image Collection

Download product images from e-commerce sites at scale for catalog building or price monitoring

Media Archiving

Archive images, videos, and documents from websites before they disappear

Geo-restricted Content

Access region-locked media by routing requests through the appropriate country

AI Training Data

Build large-scale image, video, and audio datasets for training and fine-tuning machine learning models

Real-world examples

AI training data collection

Scenario: You’re building an image or video dataset to train or fine-tune a machine learning model.How Media Download helps:

Collect images, videos, and audio files from any public URL at scale
Use expected_mime_types to enforce consistent file formats across your dataset
Async mode saves files directly to S3, ready for your training pipeline
Geo-targeting lets you collect region-specific visual data for diverse datasets

Result: Clean, validated media dataset delivered straight to your storage bucket.

E-commerce product image pipeline

Scenario: You’re building a product catalog and need to collect images from multiple retailer websites.How Media Download helps:

Downloads images directly without needing to manage proxies
Validates MIME types to ensure you only store actual images
Geo-targeting lets you access region-specific product images
Async mode saves images directly to S3 without intermediate storage

Result: Automated image pipeline ready for your product database.

News media archiving

Scenario: You want to archive images from news articles before they are removed.How Media Download helps:

Downloads images reliably through Nimble’s infrastructure
Accepts wildcard MIME types (image/*) to handle any image format
Async delivery stores files directly to your archive bucket

Result: Durable media archive from any news source.

Video content collection

Scenario: You need to collect video clips from various websites for analysis.How Media Download helps:

Specify expected_mime_types: ["video/mp4"] to only accept video files
Use geo-targeting for region-locked video content
Async mode handles large file sizes without timeout issues

Result: Reliable video collection with format validation.

Pricing

Media Download is billed per GB of data downloaded using the Media-VX6 driver. Only successful downloads count toward usage.

Driver	PAYG Price
`Media-VX6`	$2.00 / GB

View full pricing

Next steps

Extract

Extract structured data and HTML from web pages

Map

Discover media URLs across an entire website before downloading

Getting Started

Web Search

Search Agent

Extraction Tools

Extraction Templates

Jobs

Guides

SDKs

Admin

Proxy

Quick Start

Example Request

Example Response

How it works

Parameters

Async-only parameters

Usage

Realtime download

With MIME type filtering

Geo-targeted download

Async API

Parameters

Example Request

Response

Realtime response

Async response

Use cases

Product Image Collection

Media Archiving

Geo-restricted Content

AI Training Data

Real-world examples

Pricing

Next steps

Extract

Map

​Quick Start

​Example Request

​Example Response

​How it works

​Parameters

​Async-only parameters

​Usage

​Realtime download

​With MIME type filtering

​Geo-targeted download

​Async API

​Parameters

​Example Request

​Response

​Realtime response

​Async response

​Use cases

Product Image Collection

Media Archiving

Geo-restricted Content

AI Training Data

​Real-world examples

​Pricing

​Next steps

Extract

Map

Quick Start

Example Request

Example Response

How it works

Parameters

Async-only parameters

Usage

Realtime download

With MIME type filtering

Geo-targeted download

Async API

Parameters

Example Request

Response

Realtime response

Async response

Use cases

Real-world examples

Pricing

Next steps