FlowData

How do I start a media job?

Published on 10. November 2026

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

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:

  • pipeline or preset: 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.url or input.upload_id: the source. The URL must start with https:// and be publicly reachable.
  • outputs: for each output, either "managed": true (we store the file for seven days) or a put_url where FlowData uploads the result directly to your own storage. At most ten outputs per job.
  • priority (optional): high, normal or low.
  • callback (optional): the endpoint_id of a webhook endpoint or a free url. 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 in 409 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 in details.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. The Retry-After header 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?.

Was this article helpful?

Back to Media processing