Menu

Documentação

API de Processamento de Mídia

Envie um arquivo de origem e as saídas desejadas. O processamento roda de forma assíncrona nos nossos servidores, os resultados vão para o seu armazenamento via PUT ou ficam conosco, e um callback assinado informa o fim.

Jobs
https://api.flowdata.one/v1/media/jobs
Upload direto
https://api.flowdata.one/v1/media/uploads
Marcas d'água
https://api.flowdata.one/v1/media/assets
Presets
https://api.flowdata.one/v1/media/presets
Endpoints de webhook
https://api.flowdata.one/v1/media/webhook-endpoints

Arquivo OpenAPI desta área

Início rápido

Chave FlowData
Esta API faz parte da FlowData e usa chaves próprias (fd_...), que você cria no dashboard em Chaves de API. A API de mídia não aceita chaves FlowSuite (pk_..., at_...) e responde com HTTP 403.
Assíncrono
POST /jobs responde imediatamente com 202 e o job em queued. O resultado chega por callback (job.finished / job.failed) ou consultando GET /jobs/{id}.

Visão geral

URL base: https://api.flowdata.one/v1/media. Toda requisição leva Authorization: Bearer fd_…. Um job é composto de uma pipeline (ou um preset próprio), uma entrada e saídas nomeadas.

  1. Informe a origem: uma URL https publicamente acessível (por exemplo uma URL GET assinada do seu armazenamento) ou um upload_id de POST /uploads.
  2. Informe os destinos: para cada saída um put_url (PUT pré-assinado no seu armazenamento) ou managed: true (guardamos por 7 dias e entregamos um link de download).
  3. Escolha o callback: um endpoint de webhook registrado (callback.endpoint_id) ou uma callback.url livre.

Ciclo de um job

queued → downloading → processing → uploading → finished. Todo estado em andamento pode terminar em failed, um job em espera em cancelled. Um job é tentado exatamente uma vez; error.retryable indica se vale tentar de novo.

Uma origem é decodificada só uma vez e todas as saídas são produzidas a partir dela (por exemplo watermarked e clean em uma passada). Vídeos são codificados em H.264 High (no mínimo nível 4.1, o nível maior correspondente para quadros maiores e taxas mais altas, yuv420p, faststart) com AAC 128 kbit/s, fontes HDR (HLG/PQ) são convertidas para SDR BT.709, metadados como GPS são removidos.

Pipelines e presets

Sem logo padrão
Saídas com marca d'água sempre precisam de options.watermark.asset (ou logo) com a chave de uma marca d'água própria de PUT /assets/{key} ou de um preset da equipe.

Pipelines do sistema

Os nomes correspondem aos perfis fixos. video e image são blocos com saídas de nome livre cujo tipo vem de type.

PipelineSaídas e padrõesRegras
ugc_videowatermarked (video): 540×960 crop, crf 23, preset medium, max_fps 30, audio keep, marca d'água
clean (video): 540×960 crop, crf 23, preset medium, max_fps 30, audio keep
thumbnail (thumbnail): 540×960 crop, format jpg, quality 85
pelo menos um de: watermarked, clean
fila padrão (até 30 min)
ugc_imagewatermarked (image): 640×640 max, format jpg, quality 85, marca d'água
clean (image): 640×640 max, format jpg, quality 85
pelo menos um de: watermarked, clean
fila padrão (até 30 min)
video_thumbnailthumbnail (thumbnail): format jpg, quality 85Obrigatório: thumbnail
fila padrão (até 30 min)
chat_imagepreview (image): 1200×1200 max, format webp, quality 80Obrigatório: preview
fila padrão (até 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
Obrigatório: video
fila padrão (até 30 min)
course_videovideo (video): 1280×720 scale, crf 28, preset medium, max_fps 30, audio keepObrigatório: video
fila longa (até 3 h)
audio_extractaudio (audio): format mp3Obrigatório: audio
fila longa (até 3 h)
videoqualquer nome com type: video: 1280×720 scale, crf 23, preset medium, max_fps 30, audio keep
qualquer nome com type: thumbnail: format jpg, quality 85
qualquer nome com type: poster: 640×auto max, format webp, quality 80
fila padrão (até 30 min)
imagequalquer nome com type: image: 1200×1200 max, format jpg, quality 85fila padrão (até 30 min)

Sobrescritas

Ordem, o nível posterior vence: padrão da pipeline → preset da equipe options → preset da equipe outputs.<name> → job options → job outputs.<name>.

  • width, height (16 a 7680 px), max_side, fit (crop preenche e corta, scale encaixa, max só reduz)
  • Vídeo: crf (18 a 32), preset (x264, ultrafast a veryslow), max_fps (apenas se a origem for mais rápida), audio (keep / strip)
  • Imagem, miniatura, pôster: format (jpg, webp, png), quality (1 a 100)
  • watermark (true / false) por saída de vídeo ou imagem
  • options.watermark: asset, width_percent (1 a 100), opacity (0 a 1), position (center, top_center, bottom_center, top_left, top_right, bottom_left, bottom_right, center_left, center_right), margin_x, margin_y (px)

Presets da equipe

Um preset da equipe agrupa uma pipeline base com modelos próprios de options e outputs e é usado com "preset": "<key>" no lugar de pipeline. Os modelos são verificados com as mesmas regras de um job ao salvar.

GET
/v1/media/presets

Listar presets

Todas as pipelines do sistema (system: true) e os presets da sua equipe.

Bearer fd_…

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

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE',
    'Accept': 'application/json',
  },
});

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

headers = {
    'Authorization': 'Bearer fd_SUA_CHAVE',
    '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

Criar ou substituir preset

Cria um preset da equipe (201) ou substitui um com a mesma chave (200). Nomes do sistema são reservados.

Bearer fd_…

Corpo da requisição

Nome Tipo Descrição
key string
Obrigatório
1 a 64 caracteres de a-z, 0-9, _ e -
name string Rótulo, no máximo 191 caracteres
pipeline string
Obrigatório
Pipeline base, por exemplo ugc_video
options object Opções para todas as saídas, inclusive watermark
outputs object Sobrescritas por nome de saída
curl -X POST "https://api.flowdata.one/v1/media/presets" \
  -H "Authorization: Bearer fd_SUA_CHAVE" \
  -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_SUA_CHAVE')
    ->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_SUA_CHAVE',
    '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_SUA_CHAVE',
    '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}

Excluir preset

Exclui um preset da equipe. Jobs já criados não são afetados, pois têm uma cópia das configurações.

Bearer fd_…

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

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE',
    'Accept': 'application/json',
  },
});

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

headers = {
    'Authorization': 'Bearer fd_SUA_CHAVE',
    '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

Idempotência
Envie o cabeçalho Idempotency-Key (1 a 191 caracteres de A-Z a-z 0-9 . _ : -). Em até 24 horas a mesma requisição com o mesmo corpo devolve o job original com 200; um corpo diferente gera 409 idempotency_conflict.
POST
/v1/media/jobs

Criar job

Cria um job e responde com 202 e queue_position. Exatamente um entre pipeline e preset, exatamente um entre input.url e input.upload_id, para cada saída exatamente um entre put_url e managed: true. Todas as URLs devem ser https e apontar para endereços públicos.

Bearer fd_… Vídeo por minuto de saída iniciado: SD 0,008 EUR (lado menor abaixo de 720), HD 0,014 EUR (720 a 1440), 4K 0,03 EUR (acima); áudio 0,004 EUR por minuto iniciado; imagem, miniatura e pôster 0,001 EUR por saída.

Corpo da requisição

Nome Tipo Descrição
pipeline string Pipeline do sistema (ver tabela), alternativa ao preset
preset string Chave de um preset da equipe, alternativa à pipeline
reference string Sua referência própria (no máximo 191 caracteres), consultável em GET /jobs?reference=
priority string high, normal (padrão) ou low; course_video é low por padrão
input.url string URL https pública da origem, até 3 redirecionamentos
input.upload_id string ID de POST /uploads, usável uma vez
input.filename string Nome original do arquivo (apenas exibição)
input.size integer Tamanho em bytes; verificado antes contra o limite e melhora a reserva de custo
outputs.<name>.put_url string URL de PUT pré-assinada para o resultado
outputs.<name>.managed boolean true: guardamos o resultado por 7 dias
outputs.<name>.content_type string Content-Type do PUT, padrão conforme o formato
outputs.<name>.* object Sobrescritas como width, height, fit, crf, format, quality, watermark
options object Opções para todas as saídas, inclusive watermark.asset
callback.endpoint_id string ID de um endpoint de webhook registrado
callback.url string URL https livre; assinada com o segredo do endpoint padrão, senão sem assinatura
callback.events array job.finished e/ou job.failed (padrão: ambos)
metadata object Qualquer JSON até 4 KB, volta inalterado no callback
curl -X POST "https://api.flowdata.one/v1/media/jobs" \
  -H "Authorization: Bearer fd_SUA_CHAVE" \
  -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_SUA_CHAVE')
    ->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_SUA_CHAVE',
    '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_SUA_CHAVE',
    '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}

Consultar job

Retorna o job no mesmo formato do callback. Em saídas managed, download_url traz um link assinado válido até expires_at.

Bearer fd_…

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

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE',
    'Accept': 'application/json',
  },
});

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

headers = {
    'Authorization': 'Bearer fd_SUA_CHAVE',
    '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

Buscar jobs por referência

Os até 20 jobs mais recentes com esta reference.

Bearer fd_…

Parâmetros de consulta

Nome Tipo Descrição
reference string
Obrigatório
Sua referência de POST /jobs
curl -X GET "https://api.flowdata.one/v1/media/jobs?reference=orderfile%3A12345" \
  -H "Authorization: Bearer fd_SUA_CHAVE" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE',
    'Accept': 'application/json',
  },
});

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

headers = {
    'Authorization': 'Bearer fd_SUA_CHAVE',
    '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}

Cancelar job

Um job em espera vira cancelled imediatamente (sem callback, a reserva é liberada). Um job em andamento recebe um pedido de cancelamento (cancel_requested: true), o worker para em poucos segundos e informa job.failed com error.code = cancelled. Um job encerrado gera 409 conflict.

Bearer fd_…

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

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE',
    'Accept': 'application/json',
  },
});

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

headers = {
    'Authorization': 'Bearer fd_SUA_CHAVE',
    '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

Criar upload direto

Para origens sem URL pública: retorna uma URL de PUT pré-assinada no nosso armazenamento. Envie o arquivo para lá e depois use como input.upload_id. Válido por 24 horas, usável uma vez. Por equipe, no máximo oito uploads diretos e 10 GB de tamanho declarado ficam abertos ao mesmo tempo. Um upload continua contando depois de atribuído a um job, até a linha ser removida.

Bearer fd_…

Corpo da requisição

Nome Tipo Descrição
filename string Nome do arquivo, no máximo 255 caracteres
size integer
Obrigatório
Tamanho em bytes, obrigatório. A URL de PUT pré-assinada assina exatamente este Content-Length; um corpo maior é rejeitado pelo armazenamento.
content_type string Content-Type que deve ser enviado no PUT
curl -X POST "https://api.flowdata.one/v1/media/uploads" \
  -H "Authorization: Bearer fd_SUA_CHAVE" \
  -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_SUA_CHAVE')
    ->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_SUA_CHAVE',
    '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_SUA_CHAVE',
    '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

Consultar uso

Jobs, falhas, tempo de processamento e volume de entrada no período (padrão: mês atual). Custos e saldo aparecem no dashboard em Faturamento.

Bearer fd_…

Parâmetros de consulta

Nome Tipo Descrição
from string Data inicial AAAA-MM-DD
to string Data final AAAA-MM-DD
curl -X GET "https://api.flowdata.one/v1/media/usage?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer fd_SUA_CHAVE" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE',
    'Accept': 'application/json',
  },
});

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

headers = {
    'Authorization': 'Bearer fd_SUA_CHAVE',
    '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

Sem autenticação. ok, degraded (manutenção ou processamento de imagem limitado) ou down, além do tamanho da fila.

Bearer fd_…

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

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE',
    'Accept': 'application/json',
  },
});

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

headers = {
    'Authorization': 'Bearer fd_SUA_CHAVE',
    '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"
}

Marcas d'água

Marcas d'água são arquivos PNG com transparência (canal alfa ou tRNS), no máximo 2 MB e 8000 × 8000 px. Cada versão é guardada sob seu SHA-256; um job guarda o hash (options.watermark.asset_sha256), então substituir depois não altera nenhum job em espera. Você também pode gerenciá-las no dashboard em Mídia → Marcas d'água.

PUT
/v1/media/assets/{key}

Enviar marca d'água

Corpo como PNG bruto (Content-Type: image/png) ou multipart com o campo file. Responde 201 para uma chave nova, 200 para uma nova versão.

Bearer fd_…

Corpo da requisição

Nome Tipo Descrição
file file
Obrigatório
PNG com canal alfa, no máximo 2 MB
curl -X PUT "https://api.flowdata.one/v1/media/assets/brand_white" \
  -H "Authorization: Bearer fd_SUA_CHAVE" \
  -H "Content-Type: image/png" \
  --data-binary @logo.png
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE', '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_SUA_CHAVE', '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}

Enviar marca d'água (POST)

Igual ao PUT, para clientes que só enviam multipart com POST.

Bearer fd_…

Corpo da requisição

Nome Tipo Descrição
file file
Obrigatório
PNG com canal alfa, no máximo 2 MB
curl -X POST "https://api.flowdata.one/v1/media/assets/{key}" \
  -H "Authorization: Bearer fd_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"file": "value"}'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    file: 'value',
  }),
});

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

headers = {
    'Authorization': 'Bearer fd_SUA_CHAVE',
    '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

Listar marcas d'água

Todas as marcas d'água da sua equipe com a versão atual.

Bearer fd_…

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

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE',
    'Accept': 'application/json',
  },
});

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

headers = {
    'Authorization': 'Bearer fd_SUA_CHAVE',
    '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)

Sempre verifique a assinatura
Confira webhook-signature com o corpo bruto e rejeite carimbos de data com mais de cinco minutos de diferença. O segredo (whsec_…) só é mostrado ao criar e ao renovar.

Formato

Eventos: job.finished (todas as saídas enviadas) e job.failed (inclusive cancelamento). Corpo: {"event": "job.finished", "job": { …como GET /jobs/{id}… }, "metadata": { …seus metadata… }}. Uma entrega de teste do dashboard leva "event": "webhook.test".

Assinatura segundo Standard Webhooks

  • webhook-id: ID da entrega, igual nas repetições (para detectar duplicatas)
  • webhook-timestamp: segundos Unix do envio
  • webhook-signature: v1,<base64>, HMAC-SHA256 sobre {webhook-id}.{webhook-timestamp}.{body} com a parte decodificada em base64 do segredo depois de whsec_. Durante uma rotação (24 horas) há duas assinaturas no cabeçalho, separadas por espaço.
  • Além disso: X-Media-Event com o nome do evento e User-Agent: CreativeSkyline-Media/1.0.

Uma callback.url livre é assinada com o segredo do endpoint padrão da sua equipe; sem ele, sai sem assinatura. Qualquer biblioteca Standard Webhooks verifica a assinatura, ou assim:

// Controller Laravel que verifica um callback da FlowData (Standard Webhooks).
$secret = 'whsec_...';                       // de FlowData > Webhooks
$key = base64_decode(substr($secret, 6));    // chave HMAC = parte depois de "whsec_"

$id = $request->header('webhook-id');
$timestamp = (int) $request->header('webhook-timestamp');
$body = $request->getContent();              // corpo bruto, não recodificar

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

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

// Durante uma rotação o cabeçalho traz duas assinaturas: "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 é estável por entrega: ignore IDs já processados.
$event = json_decode($body, true);  // {"event":"job.finished","job":{...},"metadata":{...}}

Entrega e repetição

Sucesso é qualquer resposta 2xx em até 10 segundos. Redirecionamentos não são seguidos. Caso contrário há repetições após 30 s, 2 min, 10 min, 30 min, 1 h, 3 h e 6 h. Os callbacks de um job saem em ordem e nunca ao mesmo tempo. No dashboard cada entrega pode ser reenviada no job.

GET
/v1/media/webhook-endpoints

Listar endpoints

Todos os endpoints da sua equipe, sem o segredo.

Bearer fd_…

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

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE',
    'Accept': 'application/json',
  },
});

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

headers = {
    'Authorization': 'Bearer fd_SUA_CHAVE',
    '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

Criar endpoint

Cria um endpoint e retorna o segredo uma única vez no campo secret. is_default: true retira a marcação de outro endpoint.

Bearer fd_…

Corpo da requisição

Nome Tipo Descrição
url string
Obrigatório
URL https pública
events array job.finished e/ou job.failed (padrão: ambos)
description string No máximo 191 caracteres
is_default boolean Também assina callback.url livre
curl -X POST "https://api.flowdata.one/v1/media/webhook-endpoints" \
  -H "Authorization: Bearer fd_SUA_CHAVE" \
  -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_SUA_CHAVE')
    ->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_SUA_CHAVE',
    '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_SUA_CHAVE',
    '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

Renovar segredo

Cria um novo segredo e o retorna uma vez. O antigo continua assinando por 24 horas (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_SUA_CHAVE" \
  -H "Accept: application/json"
use Illuminate\Support\Facades\Http;

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE',
    'Accept': 'application/json',
  },
});

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

headers = {
    'Authorization': 'Bearer fd_SUA_CHAVE',
    '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}

Excluir endpoint

Exclui o endpoint. Entregas abertas para ele são abandonadas.

Bearer fd_…

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

$response = Http::withToken('fd_SUA_CHAVE')
    ->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_SUA_CHAVE',
    'Accept': 'application/json',
  },
});

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

headers = {
    'Authorization': 'Bearer fd_SUA_CHAVE',
    '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"
}

Erros e limites

Formato de erro

Toda resposta de erro tem a forma {"error": {"code", "message", "details", "type"}}. Um job com falha traz error = {"code", "message", "stage", "retryable"}.

HTTPcodeSignificado
400bad_requestObjeto JSON inválido ou Idempotency-Key inválido
401unauthenticatedChave ausente ou inválida
403forbiddenChave sem acesso à FlowData
404not_foundID desconhecido ou de outra equipe
409idempotency_conflictIdempotency-Key com corpo diferente
409conflictCancelamento de job já encerrado
413input_too_largeinput.size ou marca d'água acima do limite
422validation_failedCampos inválidos; details.field e details.errors os indicam
429rate_limitedRequisições demais ou mais de 200 jobs em espera; respeite Retry-After
429upload_quota_exceededUploads diretos abertos demais (quantidade ou soma dos bytes declarados, inclusive os já atribuídos)
429insufficient_quotaPré-pago: o saldo não é suficiente. Pós-pago: o limite de crédito ou mensal não é suficiente
429spend_limit_exceededLimite de gasto da chave ou limite mensal da equipe atingido
500 / 503internal_error / unavailableErro do nosso lado

Códigos de erro de um job

coderetryableSignificado
input_download_failedsimOrigem temporariamente indisponível
input_not_foundnãoOrigem expirada, excluída ou bloqueada (403/404)
input_too_largenãoTamanho, duração ou dimensões acima do limite
input_unreadablenãoArquivo danificado ou formato não suportado
input_no_video_streamnãoPipeline de vídeo sem faixa de vídeo
input_no_audio_streamnãoaudio_extract sem faixa de áudio
processing_failednãoCodificação ou verificação de qualidade falhou
output_upload_failedsimPUT na sua URL com 5xx ou erro de rede
output_url_expirednãoURL de PUT expirada ou rejeitada (403)
timeoutsimTempo máximo de processamento excedido
cancellednãoCancelado via DELETE
insufficient_quotanãoApós a análise, o saldo (pré-pago) ou o limite de crédito ou mensal (pós-pago) não é suficiente para a duração real
spend_limit_exceedednãoLimite de gasto da chave ou da equipe atingido durante o processamento, ou faturamento bloqueado
forbiddennãoA chave foi desativada durante o processamento ou não pode mais faturar
internal_errorsimErro do nosso lado

Limites

PipelineTam. máx.Duração máx.
Vídeo (ugc_video, chat_video, video, video_thumbnail)2 GB10 min
Vídeo longo (course_video)5 GB3 h
Áudio (audio_extract)5 GB3 h
Imagem (ugc_image, chat_image, image)50 MB–

Imagens no máximo 16000 × 16000 px. Por padrão 60 criações de job por minuto e chave e no máximo 200 jobs em espera por equipe. metadata no máximo 4 KB. Até quatro jobs rodam ao mesmo tempo, vídeos de curso e faixas de áudio em fila própria.

Faturamento

O faturamento é feito pela conta FlowData da sua equipe e cobre apenas saídas realmente enviadas. Vídeo por minuto de saída iniciado: SD 0,008 EUR (lado menor abaixo de 720), HD 0,014 EUR (720 a 1440), 4K 0,03 EUR (acima); áudio 0,004 EUR por minuto iniciado; imagem, miniatura e pôster 0,001 EUR por saída. Uma estimativa é reservada ao criar o job e compensada no fim com o valor real; as dimensões da saída decidem a faixa do vídeo. As saídas enviadas de um job com falha parcial também são cobradas. Os preços válidos para sua equipe aparecem no dashboard em Faturamento.

Retenção

Saídas guardadas conosco (managed) são excluídas após 7 dias, uploads diretos com o fim do job (não usados após 24 horas), dados de job após 90 dias. Dados de faturamento ficam permanentemente. URLs assinadas são guardadas criptografadas e nunca registradas em log.

Uma chave basta para começar.

Crie uma chave e chame a API. As informações do cliente são gratuitas; o restante é cobrado por solicitação bem-sucedida.

Criar chave de API Documentação

O FlowData é destinado exclusivamente a empresas e profissionais autônomos.