AiVideoEditor
Kostenlos starten
Menü

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

  1. Rufe POST /api/v1/media/upload-intents mit Dateiname, deklariertem MIME und Bytezahl auf. Speichere die zurückgegebene assetId und sessionId als getrennte Identitäten.
  2. Prüfe method. Bei presigned_put lade die gesamte Datei mit den zurückgegebenen Headern zu uploadUrl hoch. Bei multipart_initiated teile mit partSizeBytes, 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.
  3. Finalisiere über POST /api/v1/media/{assetId}/finalize mit sessionId und, bei Multipart, multipart.parts mit jedem partNumber und etag.
  4. Verwende die finalisierte Asset-ID in den mediaIds des 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.