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
- Chiama
POST /api/v1/media/upload-intentscon filename, MIME dichiarato e numero di byte. Salva l'assetIde ilsessionIdrestituiti come identità separate. - Ispeziona
method. Perpresigned_put, carica l'intero file suuploadUrlusando gli header restituiti. Permultipart_initiated, dividi usandopartSizeBytes, 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. - Finalizza su
POST /api/v1/media/{assetId}/finalizeconsessionIde, per il multipart,multipart.partscontenente ognipartNumberedetag. - Usa l'ID dell'asset finalizzato nei
mediaIdsdella 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.