Geprüft am 2026-11-10 · API-Version 2026-11-09 · Markdown lesen
Medien hochladen und aufbewahren
Medienbytes werden direkt in einen temporären privaten Objektspeicher übertragen. REST und MCP
liefern Upload-Anweisungen zurück; sie akzeptieren keinen binären Dateiinhalt im Tool-JSON.
Der Storage muss auf dem Deployment konfiguriert sein, sonst gibt die Erstellung eines Uploads
provider_unavailable zurück.
Upload-Lebenszyklus
- Rufe
POST /api/v1/media/upload-intentsmit Dateiname, deklariertem MIME und Bytezahl auf. Speichere die zurückgegebeneassetIdundsessionIdals getrennte Identitäten. - Prüfe
method. Beipresigned_putlade die gesamte Datei mit den zurückgegebenen Headern zuuploadUrlhoch. Beimultipart_initiatedteile mitpartSizeBytes, lade jeden nummerierten Teil zu seiner zurückgegebenen URL hoch und bewahre seinen ETag-Beleg auf. Füge den AiVideoEditor-Bearer-Key niemals zu Storage-Anfragen hinzu. - Finalisiere über
POST /api/v1/media/{assetId}/finalizemitsessionIdund, bei Multipart,multipart.partsmit jedempartNumberundetag. - Verwende die finalisierte Asset-ID in den
mediaIdsdes Entwurfs. Ein Upload-Intent allein macht das Asset noch nicht veröffentlichbar.
Der Server beobachtet tatsächliche Bytes und Format an der unveränderlichen finalen Kopie. Deklarierte Größe/MIME sind Reservierungseingaben, kein Nachweis der Dateigültigkeit. Unterstützte Basis- familien sind JPEG, PNG und MP4; einzelne Ziele können strengere Limits verhängen. Die aktuelle maximale Dateigröße beträgt 500 MiB (524.288.000 Bytes). Dateien ab 50 MiB verwenden Multipart, normalerweise mit 16-MiB-Teilen. Folge immer den zurückgegebenen Größen, URLs und Ablaufzeiten, statt sie aus diesen Standardwerten abzuleiten.
{
"sessionId": "<session UUID from upload-intents>",
"multipart": {
"parts": [
{ "partNumber": 1, "etag": "<ETag returned by storage>" }
]
}
}
Dies ist eine Illustration der Multipart-Form; schließe jeden tatsächlichen Teil ein. Die Single-PUT-
Finalisierung sendet nur sessionId. Gib jeder neuen API-Mutation ihren eigenen
Idempotency-Key; bewahre ihn für sichere identische Wiederholungen auf.
Fortsetzen oder aufgeben
Abgelaufene signierte URLs sind keine permanenten Medienadressen. Fordere neue Multipart-
Teil-URLs mit POST /media/{id}/upload-parts an, mit fromPart und toPart (ein inklusiver Bereich von maximal 64 Teilen). Siehe die API-Referenz für die begrenzte Anfrage-
form. Lade abgeschlossene Teile nicht unnötig erneut hoch und schließe die Multipart-
Montage nicht direkt über den Storage ab: Die Finalisierung wird serverseitig gesteuert.
Verwende POST /media/{id}/abandon, wenn du einen unvollständigen Upload abbrichst. Dies gibt
seine Reservierung über den gemeinsamen Bereinigungs-Workflow frei. Sitzungsablauf oder verbrauchter
Multipart-Zustand kann einen neuen Intent erforderlich machen; rate keine Storage-Objektschlüssel.
Temporäre Aufbewahrung
GET /media/{id} liefert Status und dynamische deleteAfter-Informationen zurück, keine
permanente öffentliche URL. Geplante und laufende Verwendungen schützen Medien für die Dauer der Arbeit.
Die Standardrichtlinie bewahrt ungenutzte Entwurfsmedien für 14 Tage auf, abgeschlossene Medien für 72 Stunden
und fehlgeschlagene oder mehrdeutige Arbeiten für 7 Tage nach dem relevanten Versuch. Die tatsächliche
Aufbewahrung hängt von allen verbleibenden Referenzen ab; deleteAfter kann null sein.
Bewahre Originale auf. Wenn Medien abgelaufen sind oder gelöscht werden, lade sie vor dem Veröffentlichen erneut hoch.