Menu

Documentation

Media Processing API

Pass a source file and the outputs you want. Processing runs asynchronously on our servers, the results go to your storage via PUT or stay with us, and a signed callback reports the end.

Jobs
https://api.flowdata.one/v1/media/jobs
Direct upload
https://api.flowdata.one/v1/media/uploads
Watermarks
https://api.flowdata.one/v1/media/assets
Presets
https://api.flowdata.one/v1/media/presets
Webhook endpoints
https://api.flowdata.one/v1/media/webhook-endpoints

OpenAPI file for this area

Quick start

FlowData key
This API belongs to FlowData and uses its own keys (fd_...), which you create in the dashboard under API keys. The Media API does not accept FlowSuite keys (pk_..., at_...) and answers with HTTP 403.
Asynchronous
POST /jobs answers immediately with 202 and the job in status queued. The result arrives by callback (job.finished / job.failed) or by polling GET /jobs/{id}.

Overview

Base URL: https://api.flowdata.one/v1/media. Every request carries Authorization: Bearer fd_…. A job consists of a pipeline (or a custom preset), an input and named outputs.

  1. Provide the source: a publicly reachable https URL (for example a signed GET URL of your storage) or an upload_id from POST /uploads.
  2. Provide the targets: for each output a put_url (presigned PUT into your storage) or managed: true (we store it for 7 days and return a download link).
  3. Choose the callback: a registered webhook endpoint (callback.endpoint_id) or a free callback.url.

Job lifecycle

queued → downloading → processing → uploading → finished. Every running state can end in failed, a waiting job in cancelled. A job is attempted exactly once; error.retryable says whether a new attempt is worthwhile.

A source is decoded only once and all outputs are produced from it (for example watermarked and clean in one pass). Videos are encoded as H.264 High (at least level 4.1, the matching higher level for larger frames and higher frame rates, yuv420p, faststart) with AAC 128 kbit/s, HDR sources (HLG/PQ) are converted to SDR BT.709, metadata such as GPS is removed.

Pipelines & presets

No default logo
Outputs with a watermark always need options.watermark.asset (or logo) with the key of your own watermark from PUT /assets/{key} or from a team preset.

System pipelines

The names correspond to the fixed profiles. video and image are building blocks with freely nameable outputs whose type comes from type.

PipelineOutputs and defaultsRules
ugc_videowatermarked (video): 540×960 crop, crf 23, preset medium, max_fps 30, audio keep, watermark
clean (video): 540×960 crop, crf 23, preset medium, max_fps 30, audio keep
thumbnail (thumbnail): 540×960 crop, format jpg, quality 85
at least one of: watermarked, clean
standard queue (up to 30 min)
ugc_imagewatermarked (image): 640×640 max, format jpg, quality 85, watermark
clean (image): 640×640 max, format jpg, quality 85
at least one of: watermarked, clean
standard queue (up to 30 min)
video_thumbnailthumbnail (thumbnail): format jpg, quality 85Required: thumbnail
standard queue (up to 30 min)
chat_imagepreview (image): 1200×1200 max, format webp, quality 80Required: preview
standard queue (up to 30 min)
chat_videovideo (video): 1280×720 scale, crf 26, preset medium, max_fps 30, audio keep
poster (poster): 640×auto max, format webp, quality 80
Required: video
standard queue (up to 30 min)
course_videovideo (video): 1280×720 scale, crf 28, preset medium, max_fps 30, audio keepRequired: video
long queue (up to 3 h)
audio_extractaudio (audio): format mp3Required: audio
long queue (up to 3 h)
videoany name with type: video: 1280×720 scale, crf 23, preset medium, max_fps 30, audio keep
any name with type: thumbnail: format jpg, quality 85
any name with type: poster: 640×auto max, format webp, quality 80
standard queue (up to 30 min)
imageany name with type: image: 1200×1200 max, format jpg, quality 85standard queue (up to 30 min)

Overrides

Order, the later level wins: pipeline default → team preset options → team preset outputs.<name> → job options → job outputs.<name>.

  • width, height (16 to 7680 px), max_side, fit (crop fills and cuts, scale fits inside, max only shrinks)
  • Video: crf (18 to 32), preset (x264, ultrafast to veryslow), max_fps (only if the source is faster), audio (keep / strip)
  • Image, thumbnail, poster: format (jpg, webp, png), quality (1 to 100)
  • watermark (true / false) per video or image output
  • options.watermark: asset, width_percent (1 to 100), opacity (0 to 1), position (center, top_center, bottom_center, top_left, top_right, bottom_left, bottom_right, center_left, center_right), margin_x, margin_y (px)

Team presets

A team preset bundles a base pipeline with its own options and outputs templates and is used with "preset": "<key>" instead of pipeline. The templates are checked with the same rules as a job when saved.

GET
/v1/media/presets

List presets

All system pipelines (system: true) and the presets of your team.

Bearer fd_…

curl -X GET "https://api.flowdata.one/v1/media/presets" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->get('https://api.flowdata.one/v1/media/presets');

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/presets', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
  },
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

response = requests.get(
    'https://api.flowdata.one/v1/media/presets',
    headers=headers,
)

data = response.json()
{
    "data": [
        {
            "key": "ugc_video",
            "system": true,
            "pipeline": "ugc_video",
            "outputs": [
                "watermarked",
                "clean",
                "thumbnail"
            ]
        },
        {
            "key": "ugc_hd",
            "system": false,
            "name": "UGC in HD",
            "pipeline": "ugc_video",
            "options": {
                "width": 720,
                "height": 1280
            },
            "outputs": {
                "clean": {
                    "crf": 20
                }
            },
            "updated_at": "2026-09-28T10:00:00Z"
        }
    ]
}
POST
/v1/media/presets

Create or replace a preset

Creates a team preset (201) or replaces one with the same key (200). System names are reserved.

Bearer fd_…

Request body

Name Type Description
key string
Required
1 to 64 characters from a-z, 0-9, _ and -
name string Label, at most 191 characters
pipeline string
Required
Base pipeline, for example ugc_video
options object Options for all outputs including watermark
outputs object Overrides per output name
curl -X POST "https://api.flowdata.one/v1/media/presets" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"key": "ugc_hd", "name": "UGC in HD", "pipeline": "ugc_video", "options": {"width":720,"height":1280,"watermark":{"asset":"brand_white","opacity":0.3}}, "outputs": {"clean":{"crf":20}}}'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->post('https://api.flowdata.one/v1/media/presets', [
        'key' => 'ugc_hd',
        'name' => 'UGC in HD',
        'pipeline' => 'ugc_video',
        'options' => array (
  'width' => 720,
  'height' => 1280,
  'watermark' => 
  array (
    'asset' => 'brand_white',
    'opacity' => 0.3,
  ),
),
        'outputs' => array (
  'clean' => 
  array (
    'crf' => 20,
  ),
),
    ]);

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/presets', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    key: "ugc_hd",
    name: "UGC in HD",
    pipeline: "ugc_video",
    options: {"width":720,"height":1280,"watermark":{"asset":"brand_white","opacity":0.3}},
    outputs: {"clean":{"crf":20}},
  }),
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

payload = {
    'key': "ugc_hd",
    'name': "UGC in HD",
    'pipeline': "ugc_video",
    'options': {"width": 720, "height": 1280, "watermark": {"asset": "brand_white", "opacity": 0.3}},
    'outputs': {"clean": {"crf": 20}},
}

response = requests.post(
    'https://api.flowdata.one/v1/media/presets',
    headers=headers,
    json=payload,
)

data = response.json()
{
    "key": "ugc_hd",
    "system": false,
    "name": "UGC in HD",
    "pipeline": "ugc_video",
    "options": {
        "width": 720,
        "height": 1280,
        "watermark": {
            "asset": "brand_white",
            "opacity": 0.3
        }
    },
    "outputs": {
        "clean": {
            "crf": 20
        }
    },
    "updated_at": "2026-09-28T10:00:00Z"
}
DELETE
/v1/media/presets/{key}

Delete a preset

Deletes a team preset. Jobs already created are not affected, they carry a copy of their settings.

Bearer fd_…

curl -X DELETE "https://api.flowdata.one/v1/media/presets/{key}" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->delete('https://api.flowdata.one/v1/media/presets/{key}');

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/presets/{key}', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
  },
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

response = requests.delete(
    'https://api.flowdata.one/v1/media/presets/{key}',
    headers=headers,
)

data = response.json()
{
    "deleted": true,
    "key": "ugc_hd"
}

Jobs

Idempotency
Send an Idempotency-Key header (1 to 191 characters from A-Z a-z 0-9 . _ : -). Within 24 hours the same request with the same body returns the original job with 200; a different body gives 409 idempotency_conflict.
POST
/v1/media/jobs

Create a job

Creates a job and answers with 202 and queue_position. Exactly one of pipeline and preset, exactly one of input.url and input.upload_id, for each output exactly one of put_url and managed: true. All URLs must be https and point to public addresses.

Bearer fd_… Video per started output minute: SD 0.008 EUR (shorter side below 720), HD 0.014 EUR (720 to 1440), 4K 0.03 EUR (above); audio 0.004 EUR per started minute; image, thumbnail and poster 0.001 EUR per output.

Request body

Name Type Description
pipeline string System pipeline (see table), alternatively preset
preset string Key of a team preset, alternatively pipeline
reference string Your own reference (at most 191 characters), queryable through GET /jobs?reference=
priority string high, normal (default) or low; course_video defaults to low
input.url string Public https URL of the source, up to 3 redirects
input.upload_id string ID from POST /uploads, usable once
input.filename string Original file name (display only)
input.size integer Size in bytes; checked against the limit up front and improves the cost reservation
outputs.<name>.put_url string Presigned PUT URL for the result
outputs.<name>.managed boolean true: we store the result for 7 days
outputs.<name>.content_type string Content-Type for the PUT, default matching the format
outputs.<name>.* object Overrides such as width, height, fit, crf, format, quality, watermark
options object Options for all outputs, including watermark.asset
callback.endpoint_id string ID of a registered webhook endpoint
callback.url string Free https URL; signed with the secret of the default endpoint, otherwise unsigned
callback.events array job.finished and/or job.failed (default: both)
metadata object Any JSON up to 4 KB, returned unchanged in the callback
curl -X POST "https://api.flowdata.one/v1/media/jobs" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"pipeline": "ugc_video", "reference": "orderfile:12345", "input": {"url":"https://files.example.com/in/abc.mov?X-Amz-Signature=…","filename":"abc.mov"}, "outputs": {"watermarked":{"put_url":"https://uploads.example.com/out/wm.mp4?X-Amz-Signature=…"},"clean":{"managed":true},"thumbnail":{"put_url":"https://uploads.example.com/out/thumb.jpg?X-Amz-Signature=…"}}, "options": {"watermark":{"asset":"brand_white"}}, "callback": {"endpoint_id":"01J8Z6Q4T0M3S1V7B2X9K5N4WH"}, "metadata": {"entity":"order_file"}}'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->post('https://api.flowdata.one/v1/media/jobs', [
        'pipeline' => 'ugc_video',
        'reference' => 'orderfile:12345',
        'input' => array (
  'url' => 'https://files.example.com/in/abc.mov?X-Amz-Signature=…',
  'filename' => 'abc.mov',
),
        'outputs' => array (
  'watermarked' => 
  array (
    'put_url' => 'https://uploads.example.com/out/wm.mp4?X-Amz-Signature=…',
  ),
  'clean' => 
  array (
    'managed' => true,
  ),
  'thumbnail' => 
  array (
    'put_url' => 'https://uploads.example.com/out/thumb.jpg?X-Amz-Signature=…',
  ),
),
        'options' => array (
  'watermark' => 
  array (
    'asset' => 'brand_white',
  ),
),
        'callback' => array (
  'endpoint_id' => '01J8Z6Q4T0M3S1V7B2X9K5N4WH',
),
        'metadata' => array (
  'entity' => 'order_file',
),
    ]);

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/jobs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    pipeline: "ugc_video",
    reference: "orderfile:12345",
    input: {"url":"https://files.example.com/in/abc.mov?X-Amz-Signature=…","filename":"abc.mov"},
    outputs: {"watermarked":{"put_url":"https://uploads.example.com/out/wm.mp4?X-Amz-Signature=…"},"clean":{"managed":true},"thumbnail":{"put_url":"https://uploads.example.com/out/thumb.jpg?X-Amz-Signature=…"}},
    options: {"watermark":{"asset":"brand_white"}},
    callback: {"endpoint_id":"01J8Z6Q4T0M3S1V7B2X9K5N4WH"},
    metadata: {"entity":"order_file"},
  }),
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

payload = {
    'pipeline': "ugc_video",
    'reference': "orderfile:12345",
    'input': {"url": "https://files.example.com/in/abc.mov?X-Amz-Signature=…", "filename": "abc.mov"},
    'outputs': {"watermarked": {"put_url": "https://uploads.example.com/out/wm.mp4?X-Amz-Signature=…"}, "clean": {"managed": True}, "thumbnail": {"put_url": "https://uploads.example.com/out/thumb.jpg?X-Amz-Signature=…"}},
    'options': {"watermark": {"asset": "brand_white"}},
    'callback': {"endpoint_id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH"},
    'metadata': {"entity": "order_file"},
}

response = requests.post(
    'https://api.flowdata.one/v1/media/jobs',
    headers=headers,
    json=payload,
)

data = response.json()
{
    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4RD",
    "status": "queued",
    "pipeline": "ugc_video",
    "reference": "orderfile:12345",
    "priority": "normal",
    "outputs": {
        "watermarked": {
            "status": "pending",
            "target": "put"
        },
        "clean": {
            "status": "pending",
            "target": "managed",
            "download_url": null,
            "expires_at": null
        },
        "thumbnail": {
            "status": "pending",
            "target": "put"
        }
    },
    "error": null,
    "queue_position": 1
}
GET
/v1/media/jobs/{job_id}

Get a job

Returns the job in the same shape as the callback. For managed outputs download_url carries a signed link valid until expires_at.

Bearer fd_…

curl -X GET "https://api.flowdata.one/v1/media/jobs/{job_id}" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->get('https://api.flowdata.one/v1/media/jobs/{job_id}');

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/jobs/{job_id}', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
  },
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

response = requests.get(
    'https://api.flowdata.one/v1/media/jobs/{job_id}',
    headers=headers,
)

data = response.json()
{
    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4RD",
    "status": "finished",
    "pipeline": "ugc_video",
    "preset": null,
    "reference": "orderfile:12345",
    "priority": "normal",
    "created_at": "2026-09-28T10:00:00Z",
    "started_at": "2026-09-28T10:00:02Z",
    "finished_at": "2026-09-28T10:00:31Z",
    "input": {
        "size": 48211234,
        "duration": 27.4,
        "width": 1080,
        "height": 1920,
        "video_codec": "hevc",
        "has_audio": true
    },
    "outputs": {
        "watermarked": {
            "status": "uploaded",
            "target": "put",
            "size": 6123456,
            "width": 540,
            "height": 960,
            "duration": 27.4,
            "sha256": "9f2c…"
        },
        "clean": {
            "status": "uploaded",
            "target": "managed",
            "size": 6101234,
            "width": 540,
            "height": 960,
            "duration": 27.4,
            "sha256": "4b1a…",
            "download_url": "https://…",
            "expires_at": "2026-10-05T10:00:31Z"
        }
    },
    "options": {
        "watermark": {
            "asset": "brand_white",
            "asset_sha256": "c0ff…"
        }
    },
    "error": null,
    "processing_seconds": 28.6,
    "cancel_requested": false
}
GET
/v1/media/jobs

Find jobs by reference

The up to 20 newest jobs with this reference.

Bearer fd_…

Query parameters

Name Type Description
reference string
Required
Your reference from POST /jobs
curl -X GET "https://api.flowdata.one/v1/media/jobs?reference=orderfile%3A12345" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->get('https://api.flowdata.one/v1/media/jobs?reference=orderfile%3A12345');

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/jobs?reference=orderfile%3A12345', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
  },
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

response = requests.get(
    'https://api.flowdata.one/v1/media/jobs?reference=orderfile%3A12345',
    headers=headers,
)

data = response.json()
{
    "data": [
        {
            "id": "01J8Z6Q4T0M3S1V7B2X9K5N4RD",
            "status": "finished",
            "pipeline": "ugc_video",
            "preset": null,
            "reference": "orderfile:12345",
            "priority": "normal",
            "created_at": "2026-09-28T10:00:00Z",
            "started_at": "2026-09-28T10:00:02Z",
            "finished_at": "2026-09-28T10:00:31Z",
            "input": {
                "size": 48211234,
                "duration": 27.4,
                "width": 1080,
                "height": 1920,
                "video_codec": "hevc",
                "has_audio": true
            },
            "outputs": {
                "watermarked": {
                    "status": "uploaded",
                    "target": "put",
                    "size": 6123456,
                    "width": 540,
                    "height": 960,
                    "duration": 27.4,
                    "sha256": "9f2c…"
                },
                "clean": {
                    "status": "uploaded",
                    "target": "managed",
                    "size": 6101234,
                    "width": 540,
                    "height": 960,
                    "duration": 27.4,
                    "sha256": "4b1a…",
                    "download_url": "https://…",
                    "expires_at": "2026-10-05T10:00:31Z"
                }
            },
            "options": {
                "watermark": {
                    "asset": "brand_white",
                    "asset_sha256": "c0ff…"
                }
            },
            "error": null,
            "processing_seconds": 28.6,
            "cancel_requested": false
        }
    ]
}
DELETE
/v1/media/jobs/{job_id}

Cancel a job

A waiting job becomes cancelled immediately (without a callback, the reservation is released). A running job gets a cancel request (cancel_requested: true), the worker stops within a few seconds and reports job.failed with error.code = cancelled. A finished job gives 409 conflict.

Bearer fd_…

curl -X DELETE "https://api.flowdata.one/v1/media/jobs/{job_id}" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->delete('https://api.flowdata.one/v1/media/jobs/{job_id}');

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/jobs/{job_id}', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
  },
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

response = requests.delete(
    'https://api.flowdata.one/v1/media/jobs/{job_id}',
    headers=headers,
)

data = response.json()
{
    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4RD",
    "status": "cancelled",
    "error": null,
    "cancel_requested": false
}
POST
/v1/media/uploads

Create a direct upload

For sources without a public URL: returns a presigned PUT URL into our storage. Upload the file there and then use it as input.upload_id. Valid for 24 hours, usable once. Per team at most eight direct uploads and 10 GB of declared size in total are open at the same time. An upload keeps counting after it was assigned to a job until the row is removed.

Bearer fd_…

Request body

Name Type Description
filename string File name, at most 255 characters
size integer
Required
Size in bytes, required. The presigned PUT URL signs exactly this Content-Length; a larger body is rejected by the storage.
content_type string Content-Type that must be sent with the PUT
curl -X POST "https://api.flowdata.one/v1/media/uploads" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"filename": "kurs-01.mp4", "size": 734003200, "content_type": "video/mp4"}'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->post('https://api.flowdata.one/v1/media/uploads', [
        'filename' => 'kurs-01.mp4',
        'size' => 734003200,
        'content_type' => 'video/mp4',
    ]);

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/uploads', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filename: "kurs-01.mp4",
    size: 734003200,
    content_type: "video/mp4",
  }),
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

payload = {
    'filename': "kurs-01.mp4",
    'size': 734003200,
    'content_type': "video/mp4",
}

response = requests.post(
    'https://api.flowdata.one/v1/media/uploads',
    headers=headers,
    json=payload,
)

data = response.json()
{
    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4UP",
    "upload_url": "https://…",
    "method": "PUT",
    "headers": {
        "Content-Type": "video/mp4",
        "Content-Length": "734003200"
    },
    "expires_at": "2026-09-29T10:00:00Z"
}
GET
/v1/media/usage

Get usage

Jobs, failures, compute time and input volume for the period (default: current month). Costs and balance are shown in the dashboard under Billing.

Bearer fd_…

Query parameters

Name Type Description
from string Start date YYYY-MM-DD
to string End date YYYY-MM-DD
curl -X GET "https://api.flowdata.one/v1/media/usage?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->get('https://api.flowdata.one/v1/media/usage?from=2026-09-01&to=2026-09-30');

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/usage?from=2026-09-01&to=2026-09-30', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
  },
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

response = requests.get(
    'https://api.flowdata.one/v1/media/usage?from=2026-09-01&to=2026-09-30',
    headers=headers,
)

data = response.json()
{
    "from": "2026-09-01",
    "to": "2026-09-30",
    "jobs": 2143,
    "failed": 12,
    "processing_seconds": 61234.5,
    "input_bytes": 98765432100,
    "by_pipeline": {
        "ugc_video": 2051,
        "ugc_image": 92
    }
}
GET
/v1/media/health

Status

No authentication. ok, degraded (maintenance or limited image processing) or down, plus the queue length.

Bearer fd_…

curl -X GET "https://api.flowdata.one/v1/media/health" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->get('https://api.flowdata.one/v1/media/health');

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/health', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
  },
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

response = requests.get(
    'https://api.flowdata.one/v1/media/health',
    headers=headers,
)

data = response.json()
{
    "status": "ok",
    "queue": {
        "pending": 3,
        "processing": 4
    },
    "version": "1.0.0"
}

Watermarks

Watermarks are PNG files with transparency (alpha channel or tRNS), at most 2 MB and 8000 × 8000 px. Every version is stored under its SHA-256; a job remembers the hash (options.watermark.asset_sha256), so replacing a watermark later changes no waiting job. You can also manage them in the dashboard under Media → Watermarks.

PUT
/v1/media/assets/{key}

Upload a watermark

Body as raw PNG (Content-Type: image/png) or multipart with the field file. Answers 201 for a new key, 200 for a new version.

Bearer fd_…

Request body

Name Type Description
file file
Required
PNG with alpha channel, at most 2 MB
curl -X PUT "https://api.flowdata.one/v1/media/assets/brand_white" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @logo.png
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->withBody(file_get_contents('logo.png'), 'image/png')
    ->put('https://api.flowdata.one/v1/media/assets/brand_white');
const response = await fetch('https://api.flowdata.one/v1/media/assets/brand_white', {
  method: 'PUT',
  headers: { Authorization: 'Bearer fd_YOUR_KEY', 'Content-Type': 'image/png' },
  body: pngBlob,
});
import requests

with open('logo.png', 'rb') as file:
    response = requests.put(
        'https://api.flowdata.one/v1/media/assets/brand_white',
        headers={'Authorization': 'Bearer fd_YOUR_KEY', 'Content-Type': 'image/png'},
        data=file,
    )
{
    "key": "brand_white",
    "sha256": "c0ffee…",
    "width": 800,
    "height": 200,
    "size": 18234,
    "updated_at": "2026-09-28T10:00:00Z"
}
POST
/v1/media/assets/{key}

Upload a watermark (POST)

Same as PUT, for clients that can only send multipart with POST.

Bearer fd_…

Request body

Name Type Description
file file
Required
PNG with alpha channel, at most 2 MB
curl -X POST "https://api.flowdata.one/v1/media/assets/{key}" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"file": "value"}'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->post('https://api.flowdata.one/v1/media/assets/{key}', [
        'file' => 'value',
    ]);

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/assets/{key}', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    file: 'value',
  }),
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

payload = {
    'file': 'value',
}

response = requests.post(
    'https://api.flowdata.one/v1/media/assets/{key}',
    headers=headers,
    json=payload,
)

data = response.json()
{
    "key": "brand_white",
    "sha256": "c0ffee…",
    "width": 800,
    "height": 200,
    "size": 18234,
    "updated_at": "2026-09-28T10:00:00Z"
}
GET
/v1/media/assets

List watermarks

All watermarks of your team with their current version.

Bearer fd_…

curl -X GET "https://api.flowdata.one/v1/media/assets" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->get('https://api.flowdata.one/v1/media/assets');

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/assets', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
  },
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

response = requests.get(
    'https://api.flowdata.one/v1/media/assets',
    headers=headers,
)

data = response.json()
{
    "data": [
        {
            "key": "brand_white",
            "sha256": "c0ffee…",
            "width": 800,
            "height": 200,
            "size": 18234,
            "updated_at": "2026-09-28T10:00:00Z"
        }
    ]
}

Callbacks (webhooks)

Always verify the signature
Check webhook-signature against the raw body and reject timestamps that differ by more than five minutes. The secret (whsec_…) is shown only when created and when rotated.

Format

Events: job.finished (all outputs uploaded) and job.failed (including cancellation). Body: {"event": "job.finished", "job": { …like GET /jobs/{id}… }, "metadata": { …your metadata… }}. A test delivery from the dashboard carries "event": "webhook.test".

Signature according to Standard Webhooks

  • webhook-id: ID of the delivery, the same across retries (for duplicate detection)
  • webhook-timestamp: Unix seconds of the send
  • webhook-signature: v1,<base64>, HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{body} with the base64-decoded part of the secret after whsec_. During a rotation (24 hours) two signatures, separated by a space, are in the header.
  • Additionally: X-Media-Event with the event name and User-Agent: CreativeSkyline-Media/1.0.

A free callback.url is signed with the secret of your team's default endpoint; without one it goes out unsigned. Any Standard Webhooks library can verify the signature, alternatively like this:

// Laravel controller that verifies a FlowData callback (Standard Webhooks).
$secret = 'whsec_...';                       // from FlowData > Webhooks
$key = base64_decode(substr($secret, 6));    // HMAC key = part after "whsec_"

$id = $request->header('webhook-id');
$timestamp = (int) $request->header('webhook-timestamp');
$body = $request->getContent();              // raw body, do not re-encode

if (abs(time() - $timestamp) > 300) {
    abort(400, 'timestamp outside tolerance');
}

$expected = base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$body}", $key, true));
$valid = false;

// During a rotation the header carries two signatures: "v1,<a> v1,<b>".
foreach (explode(' ', (string) $request->header('webhook-signature')) as $candidate) {
    [$version, $signature] = array_pad(explode(',', $candidate, 2), 2, '');
    if ($version === 'v1' && hash_equals($expected, $signature)) {
        $valid = true;
    }
}

abort_unless($valid, 401);

// webhook-id is stable per delivery: skip IDs you have already processed.
$event = json_decode($body, true);  // {"event":"job.finished","job":{...},"metadata":{...}}

Delivery and retries

Any response with 2xx within 10 seconds is a success. Redirects are not followed. Otherwise retries follow after 30 s, 2 min, 10 min, 30 min, 1 h, 3 h and 6 h. Callbacks of a job go out in order and never at the same time. In the dashboard every delivery can be resent from the job.

GET
/v1/media/webhook-endpoints

List endpoints

All endpoints of your team, without the secret.

Bearer fd_…

curl -X GET "https://api.flowdata.one/v1/media/webhook-endpoints" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->get('https://api.flowdata.one/v1/media/webhook-endpoints');

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/webhook-endpoints', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
  },
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

response = requests.get(
    'https://api.flowdata.one/v1/media/webhook-endpoints',
    headers=headers,
)

data = response.json()
{
    "data": [
        {
            "id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH",
            "url": "https://example.com/hooks/media",
            "description": null,
            "events": [
                "job.finished",
                "job.failed"
            ],
            "is_default": true,
            "active": true,
            "previous_secret_expires_at": null,
            "created_at": "2026-09-28T10:00:00Z"
        }
    ]
}
POST
/v1/media/webhook-endpoints

Create an endpoint

Creates an endpoint and returns the secret once in the field secret. is_default: true takes the marker away from another endpoint.

Bearer fd_…

Request body

Name Type Description
url string
Required
Public https URL
events array job.finished and/or job.failed (default: both)
description string At most 191 characters
is_default boolean Also signs free callback.url
curl -X POST "https://api.flowdata.one/v1/media/webhook-endpoints" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/media", "events": ["job.finished","job.failed"], "is_default": true}'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->post('https://api.flowdata.one/v1/media/webhook-endpoints', [
        'url' => 'https://example.com/hooks/media',
        'events' => array (
  0 => 'job.finished',
  1 => 'job.failed',
),
        'is_default' => true,
    ]);

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/webhook-endpoints', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: "https://example.com/hooks/media",
    events: ["job.finished","job.failed"],
    is_default: true,
  }),
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

payload = {
    'url': "https://example.com/hooks/media",
    'events': ["job.finished", "job.failed"],
    'is_default': True,
}

response = requests.post(
    'https://api.flowdata.one/v1/media/webhook-endpoints',
    headers=headers,
    json=payload,
)

data = response.json()
{
    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH",
    "url": "https://example.com/hooks/media",
    "events": [
        "job.finished",
        "job.failed"
    ],
    "is_default": true,
    "active": true,
    "secret": "whsec_BEISPIEL00000000000000000000000"
}
POST
/v1/media/webhook-endpoints/{endpoint_id}/rotate-secret

Rotate the secret

Creates a new secret and returns it once. The old one keeps signing for 24 hours (previous_secret_expires_at).

Bearer fd_…

curl -X POST "https://api.flowdata.one/v1/media/webhook-endpoints/{endpoint_id}/rotate-secret" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->post('https://api.flowdata.one/v1/media/webhook-endpoints/{endpoint_id}/rotate-secret');

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/webhook-endpoints/{endpoint_id}/rotate-secret', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
  },
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

response = requests.post(
    'https://api.flowdata.one/v1/media/webhook-endpoints/{endpoint_id}/rotate-secret',
    headers=headers,
)

data = response.json()
{
    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH",
    "previous_secret_expires_at": "2026-09-29T10:00:00Z",
    "secret": "whsec_…"
}
DELETE
/v1/media/webhook-endpoints/{endpoint_id}

Delete an endpoint

Deletes the endpoint. Open deliveries to it are given up.

Bearer fd_…

curl -X DELETE "https://api.flowdata.one/v1/media/webhook-endpoints/{endpoint_id}" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_YOUR_KEY')
    ->delete('https://api.flowdata.one/v1/media/webhook-endpoints/{endpoint_id}');

$data = $response->json();
const response = await fetch('https://api.flowdata.one/v1/media/webhook-endpoints/{endpoint_id}', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
  },
});

const data = await response.json();
import requests

headers = {
    'Authorization': 'Bearer fd_YOUR_KEY',
    'Accept': 'application/json',
}

response = requests.delete(
    'https://api.flowdata.one/v1/media/webhook-endpoints/{endpoint_id}',
    headers=headers,
)

data = response.json()
{
    "deleted": true,
    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH"
}

Errors & limits

Error format

Every error response has the form {"error": {"code", "message", "details", "type"}}. A failed job carries error = {"code", "message", "stage", "retryable"}.

HTTPcodeMeaning
400bad_requestNot a valid JSON object or invalid Idempotency-Key
401unauthenticatedMissing or invalid key
403forbiddenKey without FlowData access
404not_foundUnknown or foreign ID
409idempotency_conflictIdempotency-Key with a different body
409conflictCancelling a job that has already ended
413input_too_largeinput.size or watermark above the limit
422validation_failedInvalid fields; details.field and details.errors name them
429rate_limitedToo many requests or more than 200 waiting jobs; respect Retry-After
429upload_quota_exceededToo many open direct uploads (count or sum of the declared bytes, including those already assigned)
429insufficient_quotaPrepaid: the balance is not enough. Postpaid: the credit line or monthly limit is not enough
429spend_limit_exceededSpending limit of the key or monthly limit of the team reached
500 / 503internal_error / unavailableError on our side

Error codes of a job

coderetryableMeaning
input_download_failedyesSource temporarily not loadable
input_not_foundnoSource expired, deleted or blocked (403/404)
input_too_largenoSize, duration or dimensions above the limit
input_unreadablenoFile damaged or format not supported
input_no_video_streamnoVideo pipeline without a video track
input_no_audio_streamnoaudio_extract without an audio track
processing_failednoEncoding or quality check failed
output_upload_failedyesPUT to your URL with 5xx or network error
output_url_expirednoPUT URL expired or rejected (403)
timeoutyesMaximum processing time exceeded
cancellednoCancelled via DELETE
insufficient_quotanoAfter the analysis the balance (prepaid) or the credit line or monthly limit (postpaid) is not enough for the actual duration
spend_limit_exceedednoSpending limit of key or team reached during processing, or billing suspended
forbiddennoThe key was deactivated during processing or may no longer bill
internal_erroryesError on our side

Limits

PipelineMax. sizeMax. duration
Video (ugc_video, chat_video, video, video_thumbnail)2 GB10 min
Long video (course_video)5 GB3 h
Audio (audio_extract)5 GB3 h
Image (ugc_image, chat_image, image)50 MB–

Images at most 16000 × 16000 px. By default 60 job creations per minute and key and at most 200 waiting jobs per team. metadata at most 4 KB. Up to four jobs run at the same time, course videos and audio tracks in a queue of their own.

Billing

Billing goes through the FlowData account of your team and covers only outputs that were actually uploaded. Video per started output minute: SD 0.008 EUR (shorter side below 720), HD 0.014 EUR (720 to 1440), 4K 0.03 EUR (above); audio 0.004 EUR per started minute; image, thumbnail and poster 0.001 EUR per output. An estimate is reserved when the job is created and settled against the actual value at the end; the output dimensions decide the video tier. The uploaded outputs of a partly failed job are billed as well. The prices that apply to your team are shown in the dashboard under Billing.

Retention

Outputs stored with us (managed) are deleted after 7 days, direct uploads with the end of their job (unused after 24 hours), job data after 90 days. Billing data stays permanently. Signed URLs are stored encrypted and never logged.

One key is all it takes to start.

Create a key and call the API. Client info is free; everything else is billed per successful request.

Create an API key Documentation

FlowData is aimed exclusively at businesses and self-employed professionals.