Medien-Uploads

Videoerzeugung und Bildbearbeitung nutzen beide Medien-Assets — Referenzbilder, Referenzvideos und -audio, Quellbilder und Masken. Für das Senden gibt es genau eine Regel:

• Das Asset liegt bereits im öffentlichen Internet (Ihr CDN / Objektspeicher) — übergeben Sie direkt seine http(s)-URL, ganz ohne Upload-Overhead. Nur für Video-Referenzmaterialien.
• Das Asset ist lokal — laden Sie es zuerst per vorab signiertem Direct-to-R2-Upload hoch und referenzieren Sie dann die zurückgegebene upload_id. Das ist der einzige Weg für lokale Dateien und der einzige Weg für die Bildbearbeitung (Quelle und Maske).

Der Endpunkt ist POST https://api.alltoken.ai/v1/uploads/presign (Plural uploads). Verwechseln Sie ihn nicht mit /upload/presign des Account-Dienstes, das für In-Site-Avatare gedacht ist und nur Bild-MIME-Typen akzeptiert.

Ihre Datei durchläuft niemals unser Gateway. Sie tauschen eine einmalige Direct-Upload-URL ein, übertragen die Rohbytes per PUT direkt in den Objektspeicher und referenzieren dann beim Erstellen der Aufgabe die zurückgegebene upload_id. Das Gateway transportiert nur eine wenige Dutzend Byte große ID. Derselbe Mechanismus bedient Video-Referenzmaterialien und Bildbearbeitung — es unterscheiden sich nur der purpose und das Feld, über das Sie darauf verweisen.

Schritt 1 — eine Direct-Upload-URL anfordern:

Body: purpose (bestimmt die erlaubten MIME-Typen und die Größe — siehe unten), content_type (die Datei-MIME, kleingeschrieben), content_length (exakte Byte-Anzahl), content_md5 und checksum_sha256.

Die Antwort liefert upload_id (beginnt mit upl_), upload_url (das vorab signierte PUT-Ziel), required_headers (in Schritt 2 wortwörtlich wiederholen), expires_in (URL-Gültigkeit, 300 s), claim_expires_at (upload_id-Gültigkeit, 2 h) und max_content_length.

Schritt 2 — übertragen Sie die Rohbytes per PUT an upload_url und wiederholen Sie dabei jeden Header in required_headers exakt. Der Body sind die rohen Datei-Bytes — nicht base64, nicht multipart:

Schritt 3 — erstellen Sie die Aufgabe mit Verweis auf upload_id. Video legt sie in content[].upload_id ab; die Bildbearbeitung verwendet die Top-Level-Felder image_upload_id / mask_upload_id. Das Gateway validiert die Byte-Anzahl und den ETag, verschiebt das Objekt in den permanenten Bereich der Aufgabe und übermittelt eine vom Upstream erreichbare Adresse — alles transparent für Sie; Sie erhalten einfach 202 + task_id.

Drei Regeln, die Sie sich merken sollten:

• upload_id und das URL-Feld schließen sich innerhalb eines Elements gegenseitig aus — beides auszufüllen gibt 400 upload_url_conflict zurück.
• Presign und Aufgabenerstellung müssen denselben API Key verwenden — die Zugehörigkeit wird als (Benutzer + API Key + purpose) geprüft; ein Schlüsselwechsel gibt 404 upload_not_found zurück.
• Der purpose muss zur tatsächlichen Verwendung passen, sonst erhalten Sie ebenfalls 404 upload_not_found.

Vollständige Tabellen der Request- und Response-Felder finden Sie in der Image API- und Video API-Referenz.

Jeder purpose legt die erlaubten MIME-Typen und eine Größenobergrenze pro Datei fest.

Masken lehnen image/jpeg ab, weil der Alphakanal ausdrückt „wo geändert werden soll", und jpeg hat keine Transparenz.

Also: laden Sie hoch, sobald Sie die URL haben, danach haben Sie jedoch zwei Stunden Zeit, um die Generierungsanfrage zusammenzustellen und abzuschicken.

Eine upload_id bindet an genau eine Aufgabe; erneute Verwendung gibt 409 upload_already_used zurück. Das ist beabsichtigt — ein Asset, eine Aufgabe, eine Abrechnung. Schlägt die Aufgabenerstellung fehl, wird das temporäre Objekt automatisch zurückgewonnen.

Normales „hochladen, dann verwenden"-Timing trifft diese nie. Achten Sie bei großen Bildbearbeitungs-Stapeln auf die Tagesgrenze: 25 MiB × ~80 Dateien erreichen 2 GiB.

Presign-Phase:

Bindungsphase (wenn Sie die Aufgabe erstellen):