Your first API download

This guide uses the hosted API from your backend. Ask [email protected] for access. You do not need to run Redis, a worker, or a Discord bot to use it.

Set your key

Store your key in the calling service's private environment. Do not put it in browser JavaScript or a public repository.

export MEDIAFILEZ_API_KEY='YOUR_API_KEY'

On PowerShell:

$env:MEDIAFILEZ_API_KEY = 'YOUR_API_KEY'

The base URL is https://api.mediafilez.online/api/v1. Test the key:

curl --fail-with-body 'https://api.mediafilez.online/api/v1/users/me' \
  -H "Authorization: ApiKey $MEDIAFILEZ_API_KEY"

1. Start a download

Replace the URL with a public media link you are allowed to download.

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

The response is 202. A shortened example:

{
    "job": {
        "id": "job_example",
        "status": "queued",
        "result": null
    }
}

Keep job.id. Keep the same idempotency key if you retry this same request after a connection failure. Use a new key for a new download.

2. Wait for the job

curl --fail-with-body 'https://api.mediafilez.online/api/v1/jobs/job_example' \
  -H "Authorization: ApiKey $MEDIAFILEZ_API_KEY"

Poll about every two seconds. Continue for queued or processing. Stop for completed, failed, cancelled, or expired.

When successful, a shortened response looks like:

{
    "job": {
        "id": "job_example",
        "status": "completed",
        "result": {
            "fileId": "fil_example",
            "files": [
                {
                    "fileId": "fil_example"
                }
            ]
        }
    }
}

If result.files exists, use every entry. Otherwise use result.fileId. This matters for albums, which can produce several files. See job results.

3. Get a download URL

curl --fail-with-body 'https://api.mediafilez.online/api/v1/files/fil_example' \
  -H "Authorization: ApiKey $MEDIAFILEZ_API_KEY"

Read file.url from the JSON response. Fetch that URL to obtain the bytes. Do not send your API key to the storage URL.

Private download URLs expire, normally after 15 minutes. Ask /files/:id again for a fresh URL. Refreshing a URL does not restore a deleted or expired artifact.

Next steps

Use the complete Node.js and Python example, learn about authentication, or open the API reference.

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.

Try a download request

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"
}'

Read the job status

curl --fail-with-body -X GET 'https://api.mediafilez.online/api/v1/jobs/job_example' \
    -H "Authorization: ApiKey $MEDIAFILEZ_API_KEY"

Get the file address

curl --fail-with-body -X GET 'https://api.mediafilez.online/api/v1/files/fil_example' \
    -H "Authorization: ApiKey $MEDIAFILEZ_API_KEY"