For a media job, FlowData needs the input file. If it isn't available at a publicly reachable https URL, for example because it's only on your server or in private storage, upload it with a direct upload. There are three steps: request an upload URL, upload the file, start the job with the upload ID.
Step 1: Request an upload URL
Send a POST to /v1/media/uploads with the file size in bytes. The file name and file type are optional.
curl -X POST "https://api.flowdata.one/v1/media/uploads" \
-H "Authorization: Bearer fd_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"size": 48211904, "filename": "product-4711.mp4", "content_type": "video/mp4"}'
| Field | Meaning |
|---|---|
size |
Required. The exact file size in bytes as a whole number. |
filename |
Optional, at most 255 characters. |
content_type |
Optional, for example video/mp4, image/jpeg or audio/mpeg. |
The response comes with HTTP 201:
{
"id": "01JBX7Q2M4N8R6T0V2W4Y6Z8A0",
"upload_url": "https://...",
"method": "PUT",
"headers": {"Content-Type": "video/mp4", "Content-Length": "48211904"},
"expires_at": "2026-11-06T09:30:00Z"
}
Keep the id and upload_url. The values in the example are shortened and made up. Which headers appear under headers depends on your request.
Step 2: Upload the file
Upload the file with PUT to the upload_url. Send exactly the headers listed in headers, and no FlowData key. The URL is already signed.
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
-H "Content-Type: video/mp4" \
--upload-file product-4711.mp4
The uploaded file must be exactly the size you stated in step 1. Otherwise the storage rejects the upload.
Step 3: Start the job
Start the media job as usual, but instead of input.url, give the ID from step 1 as input.upload_id:
{
"pipeline": "chat_video",
"reference": "order:4711",
"input": {"upload_id": "01JBX7Q2M4N8R6T0V2W4Y6Z8A0"},
"outputs": {"video": {"managed": true}, "poster": {"managed": true}}
}
Everything else about pipelines, outputs and callbacks is in How do I start a media job?. In the job's detail view, Source then shows Direct upload with the ID.
Validity and limits
- An upload URL is valid for 24 hours. The exact time is in
expires_at, in UTC. - Each direct upload can be used for exactly one job. For a second job with the same file, request a new upload URL.
- Each team can have at most eight direct uploads with a total declared size of 10 GB at the same time. An upload keeps taking up its slot even after its job has finished. The slot only becomes free when the upload is removed by the daily cleanup after the 24 hours have passed.
- FlowData also uses the stated size to estimate the job's cost in advance. There's more in Reservation and cost of a media job.
If something goes wrong
Errors come back in the form {"error":{"code":"...","message":"...","details":{...},"type":"..."}}:
- 422
validation_failed:sizeis missing, not a whole number or less than 1, orfilenameorcontent_typeisn't acceptable.details.fieldnames the field. Make sure you sendsizeas a number, so48211904and not"48 MB". - 413
input_too_large: the file is larger than any pipeline allows. The upper limit in bytes is indetails.max_bytes. Each pipeline has its own limits, for example 2 GB for regular videos, 5 GB for long videos and audio, and 50 MB for images. - 429
upload_quota_exceeded: your team already has eight direct uploads or 10 GB declared.detailsholds the current values, and theRetry-Afterheader gives a waiting time in seconds. - On the job: "The upload does not exist, has expired or was already used." The
upload_idis wrong, older than 24 hours or already used in another job. Request a new upload URL.
Good to know
Only request the upload URL when you're actually about to upload the file. That way you don't fill slots with uploads that are never used.