Download with code

Use this backend example to submit a URL, wait for the job, and retrieve every file's download address. Choose Node.js or Python below. Neither version needs third-party packages.

Run the example

Set MEDIAFILEZ_API_KEY privately. Save the chosen version as download.mjs or download.py.

node download.mjs 'PUBLIC_MEDIA_URL'

python download.py 'PUBLIC_MEDIA_URL'

Node.js requires version 22.13 or newer. Python uses its standard library.

Complete example

const base = "https://api.mediafilez.online/api/v1";
const apiKey = process.env.MEDIAFILEZ_API_KEY;
const url = process.argv[2];

if (!apiKey || !url) {
    throw new Error("Set MEDIAFILEZ_API_KEY and pass a media URL.");
}

async function request(path, body) {
    const response = await fetch(base + path, {
        method: body ? "POST" : "GET",
        headers: {
            Authorization: `ApiKey ${apiKey}`,
            "Content-Type": "application/json"
        },
        body: body ? JSON.stringify(body) : undefined,
        signal: AbortSignal.timeout(30000)
    });
    const data = await response.json();

    if (!response.ok) {
        throw new Error(data.error?.message ?? `HTTP ${response.status}`);
    }

    return data;
}

let { job } = await request("/media/download", { url });
console.log(`Accepted ${job.id}`);

for (let attempt = 0; attempt < 90; attempt++) {
    ({ job } = await request(`/jobs/${job.id}`));

    if (job.status === "completed") {
        break;
    }

    if (["failed", "cancelled", "expired"].includes(job.status)) {
        throw new Error(job.error?.message ?? `Job ${job.status}`);
    }

    await new Promise((resolve) => setTimeout(resolve, 2000));
}

if (job.status !== "completed") {
    throw new Error(`Still running: ${job.id}. Resume polling or cancel it.`);
}

const result = job.result ?? {};
const files = result.files ?? [{ fileId: result.fileId }];

if (!files.length || files.some((file) => !file.fileId)) {
    throw new Error("The job returned no files.");
}

for (const { fileId } of files) {
    const { file } = await request(`/files/${fileId}`);

    console.log(file.fileName);
    // Pass file.url to the authorized caller. Do not put it in public logs.
}

The last loop requests each file's metadata. file.url (Python: file["url"]) is the download address. Pass it to the authorized caller or fetch it separately without an API-key header. The example prints filenames, not signed URLs.

How the example works

request() sends the API key and parses one API response. Submitting /media/download gives you a job ID, which the loop checks about every two seconds. The loop stops when the job finishes, fails, or exceeds the example's waiting window.

After completion, result.files contains the returned files. The fallback to result.fileId also accepts older single-file responses. A missing or empty result stops with an error instead of requesting an undefined file ID. The last loop looks up every file, so an album isn't reduced to its first image.

Keep the boundary clear

The API key is for your backend, never browser JavaScript. The returned storage URL does not need the key. Do not forward API credentials to storage or put signed URLs in public logs.

The polling loop is bounded to about three minutes plus request time. A timeout in this script does not cancel the server job. Resume using the printed job ID, or cancel it.

Retry a request

This introductory example stops on HTTP or job failures. In a service, back off for temporary errors. If you retry a timed-out submission, send the same Idempotency-Key for that logical download. See duplicate submission protection.

Use the result in a bot

Send the completed files when they fit the platform's upload limits, or give the authorized user the returned URL. For an album, handle every result.files entry. A partner key represents your application account, not a separate account for each Discord member.