FlowData

Como envio um arquivo próprio diretamente para o processamento de mídia?

Publicado em 10. novembro 2026

Para uma tarefa de mídia, o FlowData precisa do arquivo de entrada. Se ele não estiver em uma URL https acessível publicamente, por exemplo porque está só no seu servidor ou em um armazenamento privado, envie-o por upload direto. São três passos: solicitar a URL de upload, enviar o arquivo e iniciar a tarefa com o ID do upload.

Passo 1: Solicitar a URL de upload

Envie um POST para /v1/media/uploads com o tamanho do arquivo em bytes. O nome e o tipo do arquivo são opcionais.

curl -X POST "https://api.flowdata.one/v1/media/uploads" \
  -H "Authorization: Bearer fd_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"size": 48211904, "filename": "product-4711.mp4", "content_type": "video/mp4"}'
Campo Significado
size Obrigatório. O tamanho exato do arquivo em bytes, como número inteiro.
filename Opcional, no máximo 255 caracteres.
content_type Opcional, por exemplo video/mp4, image/jpeg ou audio/mpeg.

A resposta vem com HTTP 201:

{
  "id": "01JBX7Q2M4N8R6T0V2W4Y6Z8A0",
  "upload_url": "https://...",
  "method": "PUT",
  "headers": {"Content-Type": "video/mp4", "Content-Length": "48211904"},
  "expires_at": "2026-11-06T09:30:00Z"
}

Guarde o id e a upload_url. Os valores do exemplo são encurtados e inventados. Os cabeçalhos em headers dependem da sua requisição.

Passo 2: Enviar o arquivo

Envie o arquivo com PUT para a upload_url. Envie exatamente os cabeçalhos listados em headers e nenhuma chave do FlowData. A URL já está assinada.

curl -X PUT "URL_DE_UPLOAD_DO_PASSO_1" \
  -H "Content-Type: video/mp4" \
  --upload-file product-4711.mp4

O arquivo enviado deve ter exatamente o tamanho informado no passo 1. Caso contrário, o armazenamento recusa o upload.

Passo 3: Iniciar a tarefa

Inicie a tarefa de mídia normalmente, mas, em vez de input.url, informe o ID do passo 1 como input.upload_id:

{
  "pipeline": "chat_video",
  "reference": "order:4711",
  "input": {"upload_id": "01JBX7Q2M4N8R6T0V2W4Y6Z8A0"},
  "outputs": {"video": {"managed": true}, "poster": {"managed": true}}
}

Todo o resto sobre pipelines, saídas e retornos está em Como inicio uma tarefa de mídia?. Na visão de detalhes da tarefa, Origem mostra então Upload direto com o ID.

Validade e limites

  • Uma URL de upload é válida por 24 horas. O horário exato está em expires_at, em UTC.
  • Cada upload direto pode ser usado em exatamente uma tarefa. Para uma segunda tarefa com o mesmo arquivo, solicite uma nova URL de upload.
  • Cada equipe pode ter no máximo oito uploads diretos com um total de 10 GB de tamanho informado ao mesmo tempo. Um upload continua ocupando a sua vaga mesmo depois que a tarefa terminou. A vaga só é liberada quando o upload é removido pela limpeza diária, depois de passadas as 24 horas.
  • O FlowData também usa o tamanho informado para estimar o custo da tarefa antecipadamente. Há mais detalhes em Reserva e custo de uma tarefa de mídia.

Se algo der errado

Os erros voltam no formato {"error":{"code":"...","message":"...","details":{...},"type":"..."}}:

  • 422 validation_failed: size está ausente, não é um número inteiro ou é menor que 1, ou filename ou content_type não são aceitos. details.field indica o campo. Envie size como número, ou seja, 48211904 e não "48 MB".
  • 413 input_too_large: o arquivo é maior do que qualquer pipeline permite. O limite em bytes está em details.max_bytes. Cada pipeline tem os seus limites, por exemplo 2 GB para vídeos normais, 5 GB para vídeos longos e áudio e 50 MB para imagens.
  • 429 upload_quota_exceeded: a sua equipe já tem oito uploads diretos ou 10 GB informados. details traz os valores atuais, e o cabeçalho Retry-After indica um tempo de espera em segundos.
  • Na tarefa: "O upload não existe, expirou ou já foi usado." O upload_id está errado, tem mais de 24 horas ou já foi usado em outra tarefa. Solicite uma nova URL de upload.

Bom saber

Solicite a URL de upload somente quando for mesmo enviar o arquivo. Assim você não ocupa vagas com uploads que nunca serão usados.

Este artigo foi útil?

Voltar para Processamento de mídia