Für einen Medienauftrag braucht FlowData die Eingabedatei. Liegt sie nicht unter einer öffentlich erreichbaren https-Adresse, etwa weil sie nur auf deinem Server oder in einem privaten Speicher liegt, lädst du sie per Direkt-Upload hoch. Das läuft in drei Schritten: Upload-Adresse anfordern, Datei hochladen, Auftrag mit der Upload-Kennung starten.
Schritt 1: Upload-Adresse anfordern
Schick ein POST an /v1/media/uploads mit der Größe der Datei in Byte. Dateiname und Dateityp sind optional.
curl -X POST "https://api.flowdata.one/v1/media/uploads" \
-H "Authorization: Bearer fd_DEIN_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{"size": 48211904, "filename": "product-4711.mp4", "content_type": "video/mp4"}'
| Feld | Bedeutung |
|---|---|
size |
Pflicht. Die genaue Dateigröße in Byte als ganze Zahl. |
filename |
Optional, höchstens 255 Zeichen. |
content_type |
Optional, zum Beispiel video/mp4, image/jpeg oder audio/mpeg. |
Die Antwort kommt mit HTTP 201:
{
"id": "01JBX7Q2M4N8R6T0V2W4Y6Z8A0",
"upload_url": "https://...",
"method": "PUT",
"headers": {"Content-Type": "video/mp4", "Content-Length": "48211904"},
"expires_at": "2026-11-06T09:30:00Z"
}
Merk dir id und upload_url. Die Werte im Beispiel sind gekürzt und erfunden. Welche Header unter headers stehen, hängt von deiner Anfrage ab.
Schritt 2: Datei hochladen
Lade die Datei mit PUT an die upload_url hoch. Schick dabei genau die Header mit, die in headers stehen, und keinen FlowData-Schlüssel. Die Adresse ist bereits signiert.
curl -X PUT "UPLOAD_URL_AUS_SCHRITT_1" \
-H "Content-Type: video/mp4" \
--upload-file product-4711.mp4
Die hochgeladene Datei muss genau die Größe haben, die du in Schritt 1 angegeben hast. Sonst lehnt der Speicher den Upload ab.
Schritt 3: Auftrag starten
Starte den Medienauftrag wie gewohnt, gib aber statt input.url die Kennung aus Schritt 1 als input.upload_id an:
{
"pipeline": "chat_video",
"reference": "order:4711",
"input": {"upload_id": "01JBX7Q2M4N8R6T0V2W4Y6Z8A0"},
"outputs": {"video": {"managed": true}, "poster": {"managed": true}}
}
Alles Weitere zu Pipelines, Ausgaben und Rückmeldungen steht in Wie starte ich einen Medienauftrag?. In der Detailansicht des Auftrags steht unter Quelle dann Direkt-Upload mit der Kennung.
Gültigkeit und Grenzen
- Eine Upload-Adresse ist 24 Stunden gültig. Die genaue Uhrzeit steht in
expires_at, in UTC. - Jeder Direkt-Upload lässt sich genau einmal für einen Auftrag verwenden. Für einen zweiten Auftrag mit derselben Datei forderst du eine neue Upload-Adresse an.
- Je Team sind höchstens acht Direkt-Uploads mit zusammen 10 GB angemeldeter Größe gleichzeitig möglich. Ein Upload belegt seinen Platz auch dann noch, wenn sein Auftrag längst fertig ist. Frei wird der Platz erst, wenn der Upload nach Ablauf der 24 Stunden bei der täglichen Bereinigung entfernt wird.
- Die angegebene Größe nutzt FlowData auch, um die Kosten des Auftrags vorab zu schätzen. Mehr dazu in Warum ist Guthaben reserviert und wie setzen sich die Kosten eines Medienauftrags zusammen?.
Wenn etwas nicht klappt
Fehler kommen in der Form {"error":{"code":"...","message":"...","details":{...},"type":"..."}} zurück:
- 422
validation_failed:sizefehlt, ist keine ganze Zahl oder kleiner als 1, oderfilenamebeziehungsweisecontent_typepassen nicht. Unterdetails.fieldsteht das betroffene Feld. Achte darauf,sizeals Zahl zu schicken, also48211904und nicht"48 MB". - 413
input_too_large: Die Datei ist größer als jede Pipeline erlaubt. Die Obergrenze in Byte steht indetails.max_bytes. Je Pipeline gelten eigene Grenzen, zum Beispiel 2 GB für normale Videos, 5 GB für lange Videos und Audio und 50 MB für Bilder. - 429
upload_quota_exceeded: Dein Team hat schon acht Direkt-Uploads oder zusammen 10 GB angemeldet. Indetailsstehen die aktuellen Werte, der HeaderRetry-Afternennt eine Wartezeit in Sekunden. - Beim Auftrag: „Der Upload existiert nicht, ist abgelaufen oder wurde bereits verwendet.“ Die
upload_idist falsch, älter als 24 Stunden oder schon in einem anderen Auftrag benutzt. Fordere eine neue Upload-Adresse an.
Gut zu wissen
Fordere die Upload-Adresse erst an, wenn du die Datei auch wirklich hochladen willst. So belegst du keine Plätze mit Uploads, die nie genutzt werden.