AiVideoEditor
Commencez gratuitement
Menu

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

  1. Appelez POST /api/v1/media/upload-intents avec le nom de fichier, le MIME déclaré et le nombre d'octets. Conservez l'assetId et le sessionId retournés comme identités séparées.
  2. Examinez method. Pour presigned_put, téléversez le fichier entier vers uploadUrl en utilisant les en-têtes retournés. Pour multipart_initiated, découpez selon partSizeBytes, 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.
  3. Finalisez à POST /api/v1/media/{assetId}/finalize avec sessionId et, pour le multipart, multipart.parts contenant chaque partNumber et etag.
  4. Utilisez l'ID d'asset finalisé dans les mediaIds du 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.