AiVideoEditor
Inizia gratis
Menù

Revisionato 2026-11-10 · Versione API 2026-11-09 · Leggi Markdown

Caricare e conservare i media

I byte dei media viaggiano direttamente verso uno storage a oggetti privato temporaneo. REST e MCP restituiscono le istruzioni di upload; non accettano contenuto binario di file nel JSON degli strumenti. Lo storage deve essere configurato sul deployment, altrimenti la creazione dell'upload restituisce provider_unavailable.

Ciclo di vita dell'upload

  1. Chiama POST /api/v1/media/upload-intents con filename, MIME dichiarato e numero di byte. Salva l'assetId e il sessionId restituiti come identità separate.
  2. Ispeziona method. Per presigned_put, carica l'intero file su uploadUrl usando gli header restituiti. Per multipart_initiated, dividi usando partSizeBytes, carica ogni parte numerata al suo URL restituito e conserva la sua ricevuta ETag. Non aggiungere mai la bearer key AiVideoEditor alle richieste di storage.
  3. Finalizza su POST /api/v1/media/{assetId}/finalize con sessionId e, per il multipart, multipart.parts contenente ogni partNumber ed etag.
  4. Usa l'ID dell'asset finalizzato nei mediaIds della bozza. Un intent di upload da solo non rende l'asset pubblicabile.

Il server osserva i byte effettivi e il formato su una copia finale immutabile. Dimensione/MIME dichiarati sono input di riservazione, non prova di validità del file. Le famiglie baseline supportate sono JPEG, PNG e MP4; le singole destinazioni possono imporre limiti più rigidi. L'attuale dimensione massima del file è 500 MiB (524,288,000 byte). I file da 50 MiB o più usano multipart, di norma con parti da 16 MiB. Segui sempre le dimensioni, gli URL e la scadenza restituiti invece di ricavarli da questi valori predefiniti.

{
  "sessionId": "<session UUID from upload-intents>",
  "multipart": {
    "parts": [
      { "partNumber": 1, "etag": "<ETag returned by storage>" }
    ]
  }
}

Questa è un'illustrazione della forma multipart; includi ogni parte effettiva. La finalizzazione con singola PUT invia solo sessionId. Dai a ogni nuova mutazione API il suo Idempotency-Key; conservalo per ripetizioni identiche sicure.

Riprendere o abbandonare

Gli URL firmati scaduti non sono indirizzi permanenti dei media. Richiedi nuovi URL delle parti multipart con POST /media/{id}/upload-parts usando fromPart e toPart (un intervallo inclusivo di al massimo 64 parti). Vedi il riferimento API per la forma delimitata della richiesta. Non ricaricare parti già completate inutilmente né completare l'assemblaggio multipart direttamente attraverso lo storage: la finalizzazione è controllata dal server.

Usa POST /media/{id}/abandon quando annulli un upload incompleto. Questo rilascia la sua riservazione attraverso il flusso di pulizia condiviso. La scadenza della sessione o lo stato multipart consumato possono richiedere un nuovo intent; non indovinare le chiavi degli oggetti di storage.

Conservazione temporanea

GET /media/{id} restituisce lo stato e le informazioni dinamiche su deleteAfter, non un URL pubblico permanente. Gli usi programmati e in corso proteggono i media attraverso il lavoro. La policy predefinita conserva i media delle bozze inutilizzati per 14 giorni, i media con esiti definiti per 72 ore, e il lavoro fallito o ambiguo per 7 giorni dopo il tentativo pertinente. La conservazione effettiva dipende da tutti i riferimenti rimanenti; deleteAfter può essere null. Conserva gli originali. Se un media è scaduto o in eliminazione, ricaricalo prima di pubblicare.