FlowData

Como inicio uma tarefa de mídia?

Publicado em 10. novembro 2026

Com o Processamento de mídia do FlowData, você reduz e comprime vídeos, imagens e áudio, aplica o seu logotipo ou cria miniaturas. Você envia uma tarefa para a API, o FlowData a processa em segundo plano e coloca os resultados onde você indicar. Este artigo mostra o processo com um pequeno exemplo.

O que você precisa antes

No FlowData, você encontra à esquerda, em Processamento de mídia, as Tarefas, os seus Presets, as Marcas d'água e os Webhooks.

Criando uma tarefa

Uma tarefa é composta por um pipeline (o que deve ser feito), uma entrada e as saídas desejadas. Este exemplo transforma uma foto grande de produto em uma prévia e guarda o resultado conosco:

curl -X POST "https://api.flowdata.one/v1/media/jobs" \
  -H "Authorization: Bearer fd_SUA_CHAVE" \
  -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 } }
  }'

A API responde com HTTP 202 e a tarefa no status queued. Guarde o id da resposta, pois é com ele que você consulta a tarefa depois com GET https://api.flowdata.one/v1/media/jobs/{id}.

Os campos mais importantes:

  • pipeline ou preset: exatamente um dos dois. Em vez de um pipeline do sistema, você pode indicar um preset próprio, veja Como crio presets para o processamento de mídia?.
  • reference (opcional): o seu próprio identificador, com até 191 caracteres, como um número de pedido. Você pode buscar por ele na lista de tarefas.
  • input.url ou input.upload_id: a origem. A URL deve começar com https:// e ser acessível publicamente.
  • outputs: para cada saída, ou "managed": true (guardamos o arquivo por sete dias) ou uma put_url, para a qual o FlowData envia o resultado diretamente ao seu armazenamento. No máximo dez saídas por tarefa.
  • priority (opcional): high, normal ou low.
  • callback (opcional): o endpoint_id de um endpoint de webhook ou uma url livre. O FlowData avisa assim que a tarefa terminar ou falhar, veja Como configuro webhooks para o processamento de mídia?.
  • metadata (opcional): qualquer JSON de até 4 KB, devolvido sem alterações no retorno.
  • Idempotency-Key (cabeçalho, recomendado): se você enviar a mesma tarefa de novo com a mesma chave em até 24 horas, recebe a tarefa original com HTTP 200 em vez de uma duplicada. A mesma chave com outro conteúdo resulta em 409 idempotency_conflict.

Todos os campos estão na documentação da API de processamento de mídia.

Os pipelines do sistema

Pipeline Para quê Saídas
ugc_video Vídeo vertical com ou sem marca d'água, mais miniatura watermarked, clean, thumbnail. Pelo menos watermarked ou clean.
ugc_image Imagem com ou sem marca d'água watermarked, clean. Pelo menos uma das duas.
video_thumbnail Miniatura de um vídeo thumbnail
chat_image Prévia reduzida em WebP preview
chat_video Vídeo comprimido mais imagem de pôster video (obrigatória), poster
course_video Reduzir vídeos longos de cursos video
audio_extract Extrair a faixa de áudio em MP3 audio
video, image Saídas com nome livre para combinações próprias qualquer

Você vê os valores padrão exatos de cada pipeline no FlowData em Presets, na seção Presets do sistema. Saídas com marca d'água sempre precisam do seu próprio logotipo, veja Como envio uma marca d'água para o processamento de mídia?.

Enviando arquivos próprios diretamente

Se o seu arquivo não estiver disponível publicamente na internet, obtenha uma URL de upload com POST /v1/media/uploads e informe na tarefa o upload_id no lugar da URL. Os passos estão em Como envio um arquivo próprio diretamente para o processamento de mídia?.

Limites

  • Vídeos de até 2 GB e 10 minutos, vídeos de curso e áudio de até 5 GB e 3 horas
  • Vídeos de até 8.192 pixels por lado
  • Imagens de até 50 MB e 16.000 × 16.000 pixels
  • 60 novas tarefas por minuto por chave, 600 outras requisições por minuto por chave
  • no máximo 200 tarefas aguardando por equipe

Quanto custa uma tarefa?

Você paga apenas pelas saídas realmente criadas e enviadas: vídeo e áudio por minuto iniciado da saída, imagens, miniaturas e pôsteres por saída. Em vídeos, a faixa de preço depende do lado menor da saída. Na criação, o FlowData reserva uma estimativa, e no final é cobrado o valor real. Há mais detalhes em Reserva e custo de uma tarefa de mídia, e os valores estão na página de preços.

Se algo der errado

  • 422 validation_failed: um campo está ausente ou inválido. O campo aparece em details.field.
  • 413 input_too_large: o tamanho informado está acima do limite do pipeline.
  • 429 insufficient_quota: o saldo, o limite de crédito ou o limite mensal não é suficiente.
  • 429 spend_limit_exceeded: o limite de gastos da chave ou da equipe foi atingido.
  • 429 rate_limited: requisições demais por minuto, ou a fila da sua equipe está cheia. O cabeçalho Retry-After informa quanto tempo esperar.
  • 429 upload_quota_exceeded: já existem uploads diretos abertos demais.

O que acontece depois de criar a tarefa está em Como acompanho o status das minhas tarefas de mídia?.

Este artigo foi útil?

Voltar para Processamento de mídia