With FlowData Media processing you can resize and compress video, images and audio, overlay your logo or create thumbnails. You send a job to the API, FlowData processes it in the background and puts the results where you tell it to. This article walks through the process with a small example.
What you need first
- a FlowData key (
fd_…), see Create a FlowData API key - enough balance or a credit line, see FlowData billing, balance and spend limit
- the input file at a publicly reachable
httpsURL or as a direct upload
In FlowData you'll find Jobs, your Presets, the Watermarks and the Webhooks on the left under Media processing.
Creating a job
A job consists of a pipeline (what should be done), an input and the outputs you want. This example turns a large product photo into a preview and has the result stored by us:
curl -X POST "https://api.flowdata.one/v1/media/jobs" \
-H "Authorization: Bearer fd_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-4712-v1" \
-d '{
"pipeline": "chat_image",
"reference": "order:4712",
"input": { "url": "https://files.example.com/products/4712.png" },
"outputs": { "preview": { "managed": true } }
}'
The API responds with HTTP 202 and the job in status queued. Keep the id from the response, you'll use it to look up the job later with GET https://api.flowdata.one/v1/media/jobs/{id}.
The most important fields:
pipelineorpreset: exactly one of the two. Instead of a system pipeline you can name your own preset, see How do I create presets for media processing?.reference(optional): your own identifier of up to 191 characters, such as an order number. You can search for it in the job list.input.urlorinput.upload_id: the source. The URL must start withhttps://and be publicly reachable.outputs: for each output, either"managed": true(we store the file for seven days) or aput_urlwhere FlowData uploads the result directly to your own storage. At most ten outputs per job.priority(optional):high,normalorlow.callback(optional): theendpoint_idof a webhook endpoint or a freeurl. FlowData then notifies you as soon as the job has finished or failed, see How do I set up webhooks for media processing?.metadata(optional): any JSON up to 4 KB, returned unchanged in the callback.Idempotency-Key(header, recommended): if you send the same job again with the same key within 24 hours, you get the original job back with HTTP 200 instead of a duplicate. The same key with different content results in409 idempotency_conflict.
All fields are in the media processing API documentation.
The system pipelines
| Pipeline | Purpose | Outputs |
|---|---|---|
ugc_video |
Vertical video with or without a watermark, plus thumbnail | watermarked, clean, thumbnail. At least watermarked or clean. |
ugc_image |
Image with or without a watermark | watermarked, clean. At least one of the two. |
video_thumbnail |
Thumbnail from a video | thumbnail |
chat_image |
Downsized preview as WebP | preview |
chat_video |
Compressed video plus poster image | video (required), poster |
course_video |
Downsize long course videos | video |
audio_extract |
Extract the audio track as MP3 | audio |
video, image |
Freely named outputs for your own combinations | any |
You can see the exact defaults of each pipeline in FlowData under Presets in the System presets section. Outputs with a watermark always need your own logo, see How do I upload a watermark for media processing?.
Uploading your own files directly
If your file isn't publicly available online, get an upload URL with POST /v1/media/uploads and pass the upload_id in the job instead of the URL. The steps are in How do I upload my own file directly for media processing?.
Limits
- Videos up to 2 GB and 10 minutes, course videos and audio up to 5 GB and 3 hours
- Videos up to 8,192 pixels per side
- Images up to 50 MB and 16,000 × 16,000 pixels
- 60 new jobs per minute per key, 600 other requests per minute per key
- at most 200 waiting jobs per team
What does a job cost?
You only pay for outputs that were actually created and uploaded: video and audio per started minute of output, images, thumbnails and posters per output. For video, the price tier depends on the shorter side of the output. When the job is created, FlowData reserves an estimate, and the actual amount is charged at the end. There's more in Reservation and cost of a media job, and the amounts are on the pricing page.
If something goes wrong
- 422
validation_failed: a field is missing or invalid. The field is named indetails.field. - 413
input_too_large: the stated size is above the pipeline's limit. - 429
insufficient_quota: the balance, credit line or monthly limit isn't enough. - 429
spend_limit_exceeded: the spend limit of the key or team has been reached. - 429
rate_limited: too many requests per minute, or your team's queue is full. TheRetry-Afterheader tells you how long to wait. - 429
upload_quota_exceeded: there are already too many open direct uploads.
What happens after creating a job is covered in How do I track the status of my media jobs?.