Batch downloads

Create a batch

POST /batches requires an API key or user session. It accepts from 1 to 10 items, or a lower operator-configured ceiling. Each item has the same shape as a download request.

{
    "items": [
        {
            "url": "https://example.com/one.mp4"
        },
        {
            "url": "https://example.com/two.jpg",
            "output": {
                "type": "image",
                "format": "original",
                "quality": "best"
            }
        }
    ]
}

A shortened 202 response:

{
    "batch": {
        "id": "bat_example",
        "status": "queued",
        "totalItems": 2,
        "jobs": [
            "job_one",
            "job_two"
        ]
    }
}

Each child has its own status and file list. An Instagram album may produce multiple files from one child job.

Follow a batch

GET /batches/:id requires the owning account and no body. Its batch.jobs field contains child objects with id, status, and progress. Creation returns ID strings; status lookup returns child objects. Do not assume both shapes are identical.

Poll individual jobs to read their complete results and errors. A batch's aggregate progress is not evidence that every child succeeded.

Admission and retries

Admission is atomic: an invalid or over-capacity batch should not leave partially accepted children. The shared 10-pending-download account ceiling also applies. Wait for capacity before sending another batch.

Batch creation is not idempotent. Blindly resending a timed-out /batches request can create duplicate work. For per-item retry control, submit individual downloads with idempotency keys instead.

Archives are a separate concern

The HTTP batch API does not return a ZIP, including when an archiveName is supplied. Your client/backend can assemble completed files, as the website does.

POST /media/playlist is an alias accepting the same item-list body. It is not the saved-playlist resource. The standalone worker batch job is a different interface that creates an archive.

Request examples

Choose a language. JavaScript and Node.js examples use a server environment, not a public browser key. Replace illustrative IDs with your own.

Submit a batch

curl --fail-with-body -X POST 'https://api.mediafilez.online/api/v1/batches' \
    -H "Authorization: ApiKey $MEDIAFILEZ_API_KEY" \
    -H 'Content-Type: application/json' \
    --data '{
    "items": [
        {
            "url": "https://example.com/one.mp4"
        },
        {
            "url": "https://example.com/two.jpg"
        }
    ]
}'