Téléversement de médias

La génération vidéo et l'édition d'images utilisent toutes deux des ressources média — images de référence, vidéo et audio de référence, images source et masques. Il n'existe qu'une seule règle pour les envoyer :

• La ressource est déjà sur l'internet public (votre CDN / stockage objet) — transmettez directement son URL http(s), sans aucun surcoût de téléversement. Matériaux de référence vidéo uniquement.
• La ressource est locale — téléversez-la d'abord via un téléversement pré-signé direct vers R2, puis référencez l'upload_id retourné. C'est la seule voie pour les fichiers locaux, et la seule voie pour l'édition d'images (source et masque).

Le point de terminaison est POST https://api.alltoken.ai/v1/uploads/presign (uploads au pluriel). Ne le confondez pas avec le /upload/presign du service de compte, réservé aux avatars du site et qui n'accepte que les types MIME image.

Votre fichier ne transite jamais par notre passerelle. Vous obtenez une URL de téléversement direct à usage unique, vous envoyez les octets bruts par PUT directement vers le stockage objet, puis vous référencez l'upload_id retourné lors de la création de la tâche. La passerelle ne transporte qu'un identifiant de quelques dizaines d'octets. Le même mécanisme sert aux matériaux de référence vidéo et à l'édition d'images — seuls le purpose et le champ par lequel vous le référencez diffèrent.

Étape 1 — demander une URL de téléversement direct :

Corps : purpose (détermine le MIME et la taille autorisés — voir ci-dessous), content_type (le MIME du fichier, en minuscules), content_length (nombre exact d'octets), content_md5 et checksum_sha256.

La réponse retourne upload_id (commence par upl_), upload_url (la cible PUT pré-signée), required_headers (à rejouer tels quels à l'étape 2), expires_in (validité de l'URL, 300 s), claim_expires_at (validité de l'upload_id, 2 h) et max_content_length.

Étape 2 — envoyez les octets bruts par PUT vers upload_url, en rejouant exactement chaque en-tête de required_headers. Le corps correspond aux octets bruts du fichier — ni base64, ni multipart :

Étape 3 — créez la tâche en référençant upload_id. La vidéo le place dans content[].upload_id ; l'édition d'images utilise les champs de premier niveau image_upload_id / mask_upload_id. La passerelle valide le nombre d'octets et l'ETag, déplace l'objet vers la zone permanente de la tâche et soumet une adresse accessible en amont — le tout de manière transparente pour vous ; vous obtenez simplement 202 + task_id.

Trois règles à retenir :

• upload_id et le champ URL sont mutuellement exclusifs au sein d'un même élément — remplir les deux retourne 400 upload_url_conflict.
• La pré-signature et la création de la tâche doivent utiliser la même API Key — la propriété est vérifiée comme (utilisateur + API Key + purpose) ; changer de clé retourne 404 upload_not_found.
• Le purpose doit correspondre à l'usage réel, sinon vous obtenez également 404 upload_not_found.

Les tableaux complets des champs de requête et de réponse figurent dans les références API Image et API Vidéo.

Chaque purpose fixe les types MIME autorisés et un plafond de taille par fichier.

Les masques rejettent image/jpeg car le canal alpha exprime « où modifier », et jpeg n'a pas de transparence.

Donc : téléversez dès que vous avez l'URL, mais vous disposez ensuite de deux heures pour assembler et soumettre la requête de génération.

Un upload_id se lie à exactement une tâche ; sa réutilisation retourne 409 upload_already_used. C'est voulu — une ressource, une tâche, une facture. Si la création de la tâche échoue, l'objet temporaire est récupéré automatiquement.

Le rythme normal « téléverser puis utiliser » ne les atteint jamais. Pour les gros lots d'édition d'images, surveillez le plafond quotidien : 25 MiB × ~80 fichiers atteignent 2 GiB.

Étape de pré-signature :

Étape de liaison (lors de la création de la tâche) :