FlowModels

Enviar imagens, PDFs e áudio para um modelo

Publicado em 11. novembro 2026

Além de texto, você pode enviar a um modelo imagens, PDFs, documentos do Office e áudio, por exemplo para extrair dados de uma fatura ou descrever uma foto. Os anexos vão diretamente na mensagem, no formato da OpenAI. Veja aqui quais são os caminhos possíveis, qual o tamanho máximo dos anexos e o que acontece quando um modelo não entende um tipo de arquivo por conta própria.

Anexos em uma mensagem

Em vez de um texto simples, você envia em content uma lista de blocos. Estes tipos são permitidos:

  • text: texto normal
  • image_url: uma imagem
  • file: um documento ou outro arquivo
  • input_audio: áudio no formato wav ou mp3

Anexos só são permitidos em mensagens com role: "user". Em mensagens de sistema, de assistente ou de tool, a API os recusa com 400 unsupported_field.

{
  "model": "openai/gpt-5.6-luna",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "O que aparece na foto?"},
      {"type": "image_url", "image_url": {"url": "https://www.example.de/bilder/lager.jpg"}}
    ]
  }]
}

Três caminhos para passar um arquivo

Um bloco file contém exatamente uma destas fontes:

  1. file_url: um endereço https acessível publicamente. Nós mesmos baixamos o arquivo.
  2. file_data: o arquivo em Base64, junto com filename. Dados enviados diretamente têm limite total de 8 MiB por requisição.
  3. file_id: um arquivo que você enviou antes (veja abaixo).
{"type": "file", "file": {"file_id": "file-018f1234-5678-7abc-9def-0123456789ab"}}

Imagens vão por image_url, como endereço https ou como endereço data: em Base64. Se você enviar várias fontes ao mesmo tempo em um bloco, a requisição é recusada.

Enviar arquivos antes

Para arquivos grandes, ou quando você precisa do mesmo arquivo várias vezes, faça o upload uma vez:

curl -X POST https://api.flowmodels.one/v1/files \
  -H "Authorization: Bearer at_sua_chave" \
  -F "file=@fatura-2026-117.pdf" \
  -F "purpose=user_data"
  • purpose é user_data ou vision.
  • Um arquivo pode ter no máximo 32 MiB. A API recusa arquivos maiores com 413 file_too_large.
  • A resposta contém o id, que você usa depois como file_id.
  • Arquivos enviados ficam armazenados até você excluí-los. Não há prazo de exclusão automática. Exclua os arquivos que não precisar mais com DELETE /v1/files/{id}.

GET /v1/files lista seus arquivos, GET /v1/files/{id} mostra apenas as informações do arquivo, e GET /v1/files/{id}/content baixa o conteúdo.

O que o modelo faz com o anexo

  • Imagens e vídeos só são vistos por um modelo que aceita esse tipo. Se ele entende imagens, GET /models indica em capabilities.vision. Caso contrário, você recebe 400 unsupported_for_model.
  • Documentos que um modelo não consegue ler por conta própria são convertidos em texto antes. O modelo recebe então o texto extraído.
  • Áudio que um modelo não consegue ouvir por conta própria é transcrito antes. Essa transcrição é cobrada à parte.

Diferença em relação aos arquivos de usuário final

Anexos de uma mensagem vão diretamente para o modelo e só valem para aquela requisição. Se você quiser associar de forma permanente a um usuário final da sua aplicação documentos que o Brain consulta em perguntas futuras, use os arquivos de usuário final, veja Enviar documentos para um usuário final e usá-los como contexto.

Quando algo não funciona

  • 400 unsupported_for_model em uma imagem: o modelo não tem reconhecimento de imagem. Escolha um modelo com vision: true.
  • 400 unsupported_field: o anexo não está em uma mensagem de usuário, ou o tipo do bloco é desconhecido.
  • A URL do arquivo é recusada: ela precisa começar com https:// e ser acessível publicamente. Endereços internos e endereços com login não funcionam.
  • 413 file_too_large: um arquivo tem mais de 32 MiB, ou os dados enviados diretamente passam de 8 MiB. Reduza o arquivo, faça o upload antes ou passe uma URL.

Este artigo foi útil?

Voltar para Modelos, limites e erros