Vérifié le 2026-11-10 · Version API 2026-11-09 · Lire le Markdown
Téléversement et conservation des médias
Les octets des médias transitent directement vers un stockage d'objets privé temporaire. REST et MCP
retournent des instructions de téléversement ; ils n'acceptent pas de contenu de fichier binaire dans le JSON
des outils. Le stockage doit être configuré sur le déploiement, sinon la création d'un téléversement renvoie
provider_unavailable.
Cycle de vie du téléversement
- Appelez
POST /api/v1/media/upload-intentsavec le nom de fichier, le MIME déclaré et le nombre d'octets. Conservez l'assetIdet lesessionIdretournés comme identités séparées. - Examinez
method. Pourpresigned_put, téléversez le fichier entier versuploadUrlen utilisant les en-têtes retournés. Pourmultipart_initiated, découpez selonpartSizeBytes, téléversez chaque partie numérotée vers son URL retournée et conservez son reçu ETag. N'ajoutez jamais la clé bearer AiVideoEditor aux requêtes de stockage. - Finalisez à
POST /api/v1/media/{assetId}/finalizeavecsessionIdet, pour le multipart,multipart.partscontenant chaquepartNumberetetag. - Utilisez l'ID d'asset finalisé dans les
mediaIdsdu brouillon. Une intention de téléversement seule ne rend pas l'asset publiable.
Le serveur observe les octets et le format réels sur une copie finale immuable. La taille/MIME déclarés sont des entrées de réservation, pas une preuve de validité du fichier. Les familles de base prises en charge sont JPEG, PNG et MP4 ; les destinations individuelles peuvent imposer des limites plus strictes. La taille de fichier maximale actuelle est de 500 MiB (524 288 000 octets). Les fichiers de 50 MiB ou plus utilisent le multipart, normalement avec des parties de 16 MiB. Suivez toujours les tailles, URL et expirations retournées plutôt que de les déduire de ces valeurs par défaut.
{
"sessionId": "<session UUID from upload-intents>",
"multipart": {
"parts": [
{ "partNumber": 1, "etag": "<ETag returned by storage>" }
]
}
}
Ceci est une illustration de la forme multipart ; incluez chaque partie réelle. La finalisation en
PUT unique n'envoie que sessionId. Donnez à chaque nouvelle mutation d'API sa propre
Idempotency-Key ; conservez-la pour des rejeux identiques sûrs.
Reprendre ou abandonner
Les URL signées expirées ne sont pas des adresses de médias permanentes. Demandez de nouvelles URL de
parties multipart avec POST /media/{id}/upload-parts en utilisant fromPart et toPart (une plage inclusive d'au plus 64 parties). Voir la référence API pour la forme bornée de la requête.
Ne retéléversez pas inutilement des parties déjà complétées et ne terminez pas l'assemblage multipart
directement via le stockage : la finalisation est contrôlée par le serveur.
Utilisez POST /media/{id}/abandon pour annuler un téléversement incomplet. Cela libère
sa réservation via le flux de nettoyage partagé. L'expiration de session ou un état multipart
consommé peut nécessiter une nouvelle intention ; ne devinez pas les clés d'objets du stockage.
Conservation temporaire
GET /media/{id} renvoie le statut et les informations dynamiques deleteAfter, pas une
URL publique permanente. Les utilisations planifiées et en cours protègent les médias pendant le travail.
La politique par défaut conserve les médias de brouillons inutilisés pendant 14 jours, les médias conclus
pendant 72 heures, et le travail en échec ou ambigu pendant 7 jours après la tentative concernée. La
conservation réelle dépend de toutes les références restantes ; deleteAfter peut être null.
Gardez les originaux. Si un média est expiré ou en suppression, téléversez-le à nouveau avant de publier.