Media requests

Resolve an intent

POST /media/resolve

Body:

{
    "url": "https://example.com/video.mp4"
}

Returns 200 with status: "unverified", a detected source.platform, and generic variant choices. title, thumbnail, duration, and media URLs can be null. This endpoint does not download or probe the source. Availability is checked when the worker executes a download.

Submit a download

POST /media/download

Authentication: partner API key or user session. Anonymous downloads depend on the deployment. Partner integrations should always send their key.

{
    "url": "https://example.com/video.mp4",
    "delivery": "private",
    "output": {
        "type": "auto",
        "format": "original",
        "quality": "best"
    },
    "processing": {
        "fitToLimit": false
    }
}

Byte values are bytes, not megabytes. Account and operator ceilings still apply. Quality heights are preferences when source variants exist, not guaranteed dimensions. audio-only requires original or mp3 format.

For source-preserving output, use format: "original" with fitToLimit: false. Explicit conversion or fitting can change the selected source. This does not recover quality missing from the source.

Accepted response

Returns 202, a Location header pointing to /api/v1/jobs/:id, and Retry-After: 2. The JSON contains job.id, status, phase, timestamps, error, and result.

Follow job status, then retrieve files. A worker failure is reported on the job, even though submission returned 202.

Duplicate submission protection

Optionally send Idempotency-Key. It must contain 8 to 200 printable non-space ASCII characters. Keys are scoped to the account.

An identical logical download with the same key returns the existing job. Reusing the key with different intent returns 409 IDEMPOTENCY_CONFLICT. Keep the key after a submission timeout. A deliberate retry of a terminal failed job needs a new key.

Audio and thumbnails

Audio example:

{
    "url": "https://example.com/video.mp4",
    "output": {
        "type": "audio",
        "format": "mp3",
        "quality": "audio-only"
    }
}

Thumbnail example:

{
    "url": "https://example.com/video.mp4",
    "output": {
        "type": "thumbnail",
        "format": "jpg",
        "quality": "best"
    }
}

Source support and extraction still apply. The API does not accept source-platform cookies from callers.

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.

Download a file

curl --fail-with-body -X POST 'https://api.mediafilez.online/api/v1/media/download' \
    -H "Authorization: ApiKey $MEDIAFILEZ_API_KEY" \
    -H 'Content-Type: application/json' \
    --data '{
    "url": "https://example.com/video.mp4",
    "output": {
        "type": "auto",
        "format": "original",
        "quality": "best"
    }
}'