Passando arquivos

Um arquivo se move por um workflow como um objeto de arquivo padronizado. Blocos o recebem, agem sobre ele e o passam adiante — esta página cobre a forma do objeto, como referenciá-lo entre blocos e como arquivos entram e saem pela API.

Objetos de arquivo

Quando blocos produzem arquivos (como anexos do Gmail, imagens geradas ou documentos parseados), eles retornam um objeto de arquivo padronizado:

{
  "id": "f_8c2...",
  "name": "report.pdf",
  "url": "https://...",
  "size": 245678,
  "type": "application/pdf",
  "base64": "JVBERi0xLjQK..."
}

Você pode acessar qualquer uma dessas propriedades ao referenciar arquivos de blocos anteriores.

O bloco File

O bloco File traz um arquivo para um workflow. Aceita arquivos de qualquer fonte e produz objetos de arquivo padronizados que todo bloco entende.

Entradas:

• Arquivos enviados - Arraste e solte ou selecione arquivos diretamente
• URLs externas - Qualquer URL de arquivo publicamente acessível
• Arquivos de outros blocos - Passe arquivos de anexos do Gmail, downloads do Slack etc.

Saídas:

• Uma lista de objetos UserFile com estrutura consistente (id, name, url, size, type, base64)
• contents - Texto extraído por arquivo (a operação Get Content)
• combinedContent - O texto de todos os arquivos buscados mesclado em uma string (a operação Fetch)

Exemplo de uso:

// Get all files from the File block
<file.files>

// Get the first file
<file.files[0]>

// Get the first file's extracted text (Get Content operation)
<file.contents[0]>

O bloco File automaticamente:

• Detecta tipos de arquivo a partir de URLs e extensões
• Extrai texto de PDFs, CSVs e documentos
• Gera encoding base64 para arquivos binários
• Cria URLs pré-assinadas para acesso seguro

Use o bloco File quando precisar normalizar arquivos de fontes diferentes antes de passá-los a outros blocos como Vision, STT ou integrações de e-mail.

Passando arquivos entre blocos

Referencie arquivos de blocos anteriores pelo dropdown de tags. Clique em qualquer campo de entrada de arquivo e digite < para ver as saídas disponíveis.

Padrões comuns:

// Single file from a block
<gmail.attachments[0]>

// Pass the whole file object
<file_parser.files[0]>

// Access specific properties
<gmail.attachments[0].name>
<gmail.attachments[0].base64>

A maioria dos blocos aceita o objeto de arquivo completo e extrai o que precisa automaticamente. Você não precisa extrair base64 ou url manualmente na maioria dos casos.

Disparando workflows com arquivos

Ao chamar um workflow via API que espera entrada de arquivo, inclua arquivos na sua request:

curl -X POST "https://app.zoen.space/api/workflows/YOUR_WORKFLOW_ID/execute" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "document": {
      "name": "report.pdf",
      "base64": "JVBERi0xLjQK...",
      "type": "application/pdf"
    }
  }'

curl -X POST "https://app.zoen.space/api/workflows/YOUR_WORKFLOW_ID/execute" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "document": {
      "name": "report.pdf",
      "url": "https://example.com/report.pdf",
      "type": "application/pdf"
    }
  }'

O bloco Start do workflow deve ter um campo de entrada configurado para receber o parâmetro de arquivo.

Recebendo arquivos em respostas da API

Quando um workflow produz arquivos, eles são incluídos na resposta:

{
  "success": true,
  "output": {
    "generatedFile": {
      "name": "output.png",
      "url": "https://...",
      "base64": "iVBORw0KGgo...",
      "type": "image/png",
      "size": 34567
    }
  }
}

Use url para downloads diretos ou base64 para processamento inline.

Blocos que trabalham com arquivos

Entradas de arquivo:

• File - Parseia documentos, imagens e arquivos de texto
• Agent - Lê imagens com um modelo com visão, ou documentos como texto
• Mistral Parser - Extrai texto de PDFs

Saídas de arquivo:

• Gmail - Anexos de e-mail
• Slack - Arquivos baixados
• TTS - Arquivos de áudio gerados
• Video Generator - Vídeos gerados
• Image Generator - Imagens geradas

Armazenamento de arquivos:

• Supabase - Upload/download do storage
• S3 - Operações AWS S3
• Google Drive - Operações de arquivo no Drive
• Dropbox - Operações de arquivo no Dropbox

Boas práticas

1. Use objetos de arquivo diretamente - Passe o objeto de arquivo completo em vez de extrair propriedades individuais. Os blocos cuidam da conversão automaticamente.

2. Cheque os tipos de arquivo - Garanta que o tipo do arquivo corresponde ao que o bloco receptor espera. Um Agent com modelo com visão pode ler imagens, enquanto o bloco File lida com documentos.

3. Considere o tamanho do arquivo - Arquivos grandes aumentam o tempo de execução. Para arquivos muito grandes, considere usar blocos de storage (S3, Supabase) para armazenamento intermediário.