API and worker architecture

Hosted request lifecycle

sequenceDiagram
    accTitle: Hosted download lifecycle
    accDescr: A backend submits a job, the worker processes it, and file lookup returns a storage URL.
    participant Client as Your backend
    participant API as MediaFilez API
    participant Queue as Queue and worker
    participant Store as Storage
    Client->>API: POST /media/download + API key
    API-->>Client: 202 + job.id
    API->>Queue: Dispatch persistent job
    Queue->>Queue: Download, validate, process
    Queue->>Store: Commit every result file
    Queue-->>API: Completion and file identities
    Client->>API: GET /jobs/:id
    API-->>Client: completed + result.files
    Client->>API: GET /files/:fileId + API key
    API-->>Client: file.url
    Client->>Store: Fetch URL without the API key
    Store-->>Client: File bytes

1. Your backend submits a URL with its API key.
2. The API checks the request and account limits, saves the job, and queues it for execution.
3. A worker resolves a media source, downloads it within limits, validates the artifact, and applies requested conversion.
4. The worker stores the result. The API records file identities and job completion.
5. Your backend retrieves file metadata and passes the returned download URL to its caller, or streams the file itself.

The API does not perform source extraction. The worker does not manage partner accounts or browser sessions.

Three interfaces, different results

Do not send a raw worker job to the HTTP endpoint. The API adds the execution identity and translates the public request into a worker job.

Delivery and ownership

flowchart TD
    accTitle: Private and public file delivery
    accDescr: Private file lookup checks the owning account and issues an expiring URL; public delivery returns a shareable CDN URL.
    C[Caller] --> A[GET /files/:id]
    A --> D{Delivery type}
    D -->|Private| P[Check owning account]
    P --> U[Return signed URL]
    U --> T[Fetch before expiry]
    D -->|Public| B[Return shareable CDN URL]
    B --> F[Fetch public file]
    T --> K[Do not send API key to storage]
    F --> K

API keys on the same account share jobs, files, playlists, and limits. A key is not an end-user identity for every member of your bot. Your application must decide which of its own users may see a result.

Private file metadata requires the owning account. Once issued, a signed URL grants temporary access to anyone who has that URL. Public delivery intentionally creates a shareable CDN URL. See files and delivery.

Continue after a connection failure

Keep the accepted job.id. If your connection drops while waiting, request that job again rather than starting a duplicate download.

If you didn't receive an ID because submission timed out, retry the individual download with the same Idempotency-Key. This lets the API recognize the earlier submission. HTTP batch creation does not provide the same retry guarantee.

Independent applications

The Discord bot has its own download execution path. The Desktop app uses local tools first. MediaAnalyzer inspects a direct media URL. These projects do not all send their work through the hosted worker.