FlowData

How do I upload my own file directly for media processing?

Published on 10. November 2026

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: size is missing, not a whole number or less than 1, or filename or content_type isn't acceptable. details.field names the field. Make sure you send size as a number, so 48211904 and not "48 MB".
  • 413 input_too_large: the file is larger than any pipeline allows. The upper limit in bytes is in details.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. details holds the current values, and the Retry-After header gives a waiting time in seconds.
  • On the job: "The upload does not exist, has expired or was already used." The upload_id is 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.

Was this article helpful?

Back to Media processing