Atualizado em Aug 11, 2026

Inspecionar Mídia

Use esta ação quando um workflow precisa conhecer o formato de um arquivo de mídia — a duração de um vídeo ou áudio, o tamanho de uma imagem e em que formato ele está — antes de decidir o que fazer com ele.

Ideal para

• Verificar a duração de um vídeo ou gravação antes de converter ou transcrever
• Garantir que uma imagem enviada é grande o suficiente antes de usá-la como logotipo ou foto de perfil
• Verificar se um vídeo realmente contém som antes de tentar usar o áudio dele
• Estimar quanto custará uma transcrição antes de iniciá-la

Por que isso importa

Todas as outras formas de olhar para um arquivo informam o tamanho em bytes e o tipo — e nada além disso. Isso basta para saber que um arquivo é um vídeo de 4 MB, mas não para saber se ele tem quatro segundos ou quarenta minutos, e cada caso leva a decisões bem diferentes.

Esta ação é o único lugar que responde a essas perguntas. Coloque-a antes da etapa que age sobre o arquivo e use as respostas dela na condição daquela etapa.

Campos principais

Campo	O que faz
Arquivo	O arquivo a inspecionar, normalmente step(0).file de uma etapa de upload, download ou geração de documento
Bucket e Caminho completo	Uma alternativa ao campo Arquivo, quando você quer apontar diretamente para o arquivo
Finalidade	Rótulo opcional que descreve a etapa nos logs. Não altera qual arquivo é inspecionado

O que as etapas seguintes podem usar

Valor	O que é
step(N).durationSeconds	A duração do vídeo ou áudio, em segundos. 0 para imagens
step(N).width, step(N).height	Tamanho em pixels, para vídeos e imagens. Vazio para arquivos só de áudio
step(N).hasAudio	Se o arquivo contém uma trilha de áudio
step(N).formatName	O formato do contêiner, como as ferramentas de mídia o identificam
step(N).videoCodec, step(N).audioCodec	Como a imagem e o som estão codificados
step(N).sizeBytes, step(N).contentType	Tamanho em bytes e tipo do arquivo
step(N).cached	Se a resposta já era conhecida — veja abaixo

Quanto custa

Ler esses detalhes exige ler o próprio arquivo, então esta etapa é cobrada da sua cota de transcodificação conforme o tempo que isso leva. Arquivos maiores custam mais; o tamanho do arquivo pesa mais do que a duração. Um podcast longo em um formato compacto é barato; um clipe curto em um formato de altíssima qualidade não é.

Duas coisas mantêm isso sob controle:

• Arquivos acima de 512 MiB são recusados em vez de inspecionados, com um erro claro informando o limite.
• Inspecionar o mesmo arquivo duas vezes é gratuito. A primeira leitura fica registrada no próprio arquivo, então qualquer etapa ou workflow que o inspecione novamente recebe a resposta sem custo. step(N).cached indica o que aconteceu. Mídias que chegaram por uma conversa normalmente já foram inspecionadas, então são gratuitas desde o início.

Quais arquivos funcionam

Vídeos e áudios funcionam de forma geral. Imagens funcionam — PNG, JPEG, WebP, GIF e SVG — e retornam duração 0.

Um arquivo que não é realmente mídia normalmente não falha. Se alguém enviar um arquivo de texto chamado foto.png, esta etapa em geral vai concluir mesmo assim. Ela informa largura e altura vazias — mas uma duração de cerca de 0,04 segundo, que parece real. Ou seja, verificar se a duração é maior que zero não detecta um arquivo ruim. Quando o arquivo vier de uma origem que você não controla, verifique step(N).width e não conte com a falha da etapa.

Dicas

• Encadeie diretamente: coloque Enviar para armazenamento, Baixar para armazenamento ou um arquivo recebido em uma etapa, esta ação na seguinte, e a sua decisão na etapa posterior.
• Use como proteção antes de trabalho caro: confira step(N).durationSeconds antes de iniciar uma transcrição e ignore o arquivo se ele for mais longo do que você quer pagar.
• Confira step(N).hasAudio antes de tentar transcrever um vídeo. Um vídeo mudo não produz nada útil, e descobrir isso cedo evita a tentativa.
• Inspecionar um arquivo nunca altera o conteúdo dele. A ação registra no próprio arquivo o que encontrou, e é isso que torna a segunda leitura gratuita.