7. Upload links (BigLoader) — let your users upload

Telegram bots and many integrations can't relay big files. An upload link is a short-lived, one-time URL you send to an end user: they open it in any browser, the file goes straight to storage, and — if you pinned an operation — it is processed automatically and billed exactly like a normal /jobs/api submit.

Prefer clicking? The panel's Upload links page (/upload-links) does the same thing and lets you download both the source and the result.

Create a link

curl -s https://mp.dvocorp.com/api/v1/upload-sessions/api \
  -H 'X-Api-Key: ca_live_...' -H 'Content-Type: application/json' \
  -d '{
    "service_slug": "clipconvert",
    "operation_key": "compress",
    "params": { "level": "medium" },
    "expires_in_seconds": 3600,
    "max_file_size_bytes": 2147483648,
    "allowed_mime_types": ["video/mp4", "video/quicktime"],
    "callback_url": "https://my-bot.example.com/hooks/bigloader",
    "delete_after_processing": true,
    "metadata": { "telegram_user_id": "123456" }
  }'

{
  "id": "<session_id>",
  "upload_url": "https://mp.dvocorp.com/u/<TOKEN>",
  "expires_at": "2026-07-22T13:00:00Z",
  "status": "created",
  "estimated_cost": 3,
  "callback_secret": "<shown once — use it to verify callbacks>"
}

Send upload_url to your user. That's it.

Options:

• service_slug / operation_key / params are exactly the fields POST /jobs/api takes — the uploaded file is injected as params.file_url. Omit them to just receive a file with no processing.

• max_files (1–20, default 1) — accept several files through one link; every file is fanned out to the configured operations. With bundle_zip: true the owner can pull everything as one archive from GET https://mp.dvocorp.com/api/v1/upload-sessions/{id}/archive (works regardless of the flag).

• operations (max 10) — several processings of the same file, one job per entry, each billed separately. Mutually exclusive with the single triple:

  { "operations": [
      { "service_slug": "clipconvert", "operation_key": "compress",  "params": { "level": "medium" } },
      { "service_slug": "clipconvert", "operation_key": "thumbnail", "params": { "at": 3 } }
  ] }
  

• An operation whose media kind doesn't match a file (a photo hitting a video-only op) is skipped with a recorded reason in files[].skipped — never an error, never charged.

• Unknown operation → 404; not enough credits → 402. You find out at create time, before anyone uploads.

• The token is stored hashed server-side and appears only inside upload_url.

Get the result

Poll:

curl -s https://mp.dvocorp.com/api/v1/upload-sessions/<session_id> -H 'X-Api-Key: ca_live_...'

{
  "id": "...",
  "status": "processing",
  "file": { "filename": "movie.mp4", "size_bytes": 2147483648, "url": "https://.../movie.mp4" },
  "uploaded_ip": "203.0.113.7",
  "jobs": [ { "id": "...", "operation_key": "compress", "status": "processing" } ],
  "estimated_cost": 3,
  "error": null
}

Statuses: created → uploading → uploaded → processing → done, plus failed and expired. done means every job finished and at least one succeeded — the per-job statuses tell the rest. Results are at jobs[].result.output_url.

GET https://mp.dvocorp.com/api/v1/upload-sessions lists your recent sessions; DELETE https://mp.dvocorp.com/api/v1/upload-sessions/{id} removes the files and cancels and refunds any in-flight jobs.

Or set callback_url and receive webhooks:

• upload.completed — right after the file lands and is verified
• processing.completed / processing.failed — when all linked jobs finish

Each callback carries:

X-BigLoader-Event:     processing.completed
X-BigLoader-Signature: HMAC_SHA256(callback_secret, raw_request_body)   # hex

Verify by recomputing the HMAC over the raw body. Delivery is best-effort — polling always works as a fallback.

Limits

• Lifetime: expires_in_seconds, default 1 h, capped at 24 h.
• One upload per link unless max_files says otherwise — a second attempt gets 409.
• Size: the lower of MAX_UPLOAD_GB (default 3 GB) and your max_file_size_bytes. The stored size is verified after upload; oversized objects are deleted and rejected with 413.
• Storage: sources live under the temp prefix and are cleaned by bucket lifecycle rules (~24 h), or immediately after successful processing when delete_after_processing: true.

Env knobs: UPLOAD_BRIDGE_TTL_SEC, UPLOAD_BRIDGE_MAX_TTL_SEC, UPLOAD_BRIDGE_IP_RPM, UPLOAD_BRIDGE_PAGE_BASE_URL.