Media Uploads

Video generation and image editing both take media assets — reference images, reference video and audio, source images, and masks. There is exactly one rule for how to send them:

• The asset is already on the public internet (your CDN / object storage) — pass its http(s) URL directly, with zero upload overhead. Video reference materials only.
• The asset is local — upload it first with a presigned direct-to-R2 upload, then reference the returned upload_id. This is the only path for local files, and the only path for image editing (source and mask).

The endpoint is POST https://api.alltoken.ai/v1/uploads/presign (plural uploads). Don't confuse it with the account service's /upload/presign, which is for in-site avatars and only accepts image MIME types.

Your file never passes through our gateway. You exchange a one-time direct-upload URL, PUT the raw bytes straight to object storage, then reference the returned upload_id when you create the task. The gateway only carries a few-dozen-byte ID. The same mechanism serves video reference materials and image editing — only the purpose and the field you reference it by differ.

Step 1 — request a direct-upload URL:

Body: purpose (decides the allowed MIME and size — see below), content_type (the file MIME, lowercase), content_length (exact byte count), content_md5, and checksum_sha256.

The response returns upload_id (starts with upl_), upload_url (the presigned PUT target), required_headers (replay verbatim in step 2), expires_in (URL validity, 300 s), claim_expires_at (upload_id validity, 2 h), and max_content_length.

Step 2 — PUT the raw bytes to upload_url, replaying every header in required_headers exactly. The body is the raw file bytes — not base64, not multipart:

Step 3 — create the task referencing upload_id. Video puts it in content[].upload_id; image editing uses the image_upload_id / mask_upload_id top-level fields. The gateway validates the byte count and ETag, moves the object into the task's permanent area, and submits an upstream-reachable address — all transparent to you; you just get 202 + task_id.

Three rules to remember:

• upload_id and the URL field are mutually exclusive within one item — filling both returns 400 upload_url_conflict.
• Presign and task creation must use the same API key — ownership is checked as (user + API key + purpose); switching keys returns 404 upload_not_found.
• The purpose must match the actual use, or you also get 404 upload_not_found.

Full request and response field tables live in the Image API and Video API reference.

Each purpose fixes the allowed MIME types and a per-file size cap.

Masks reject image/jpeg because the alpha channel expresses "where to change", and jpeg has no transparency.

So: upload as soon as you have the URL, but you then have two hours to assemble and submit the generation request.

An upload_id binds to exactly one task; reuse returns 409 upload_already_used. This is by design — one asset, one task, one bill. If task creation fails, the temporary object is reclaimed automatically.

Normal "upload then use" pacing never hits these. For large image-editing batches, mind the daily cap: 25 MiB × ~80 files reaches 2 GiB.

Presign stage:

Binding stage (when you create the task):