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:sizeestá ausente, não é um número inteiro ou é menor que 1, oufilenameoucontent_typenão são aceitos.details.fieldindica o campo. Enviesizecomo número, ou seja,48211904e não"48 MB". - 413
input_too_large: o arquivo é maior do que qualquer pipeline permite. O limite em bytes está emdetails.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.detailstraz os valores atuais, e o cabeçalhoRetry-Afterindica um tempo de espera em segundos. - Na tarefa: "O upload não existe, expirou ou já foi usado." O
upload_idestá 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.