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 normalimage_url: uma imagemfile: um documento ou outro arquivoinput_audio: áudio no formatowavoump3
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:
file_url: um endereçohttpsacessível publicamente. Nós mesmos baixamos o arquivo.file_data: o arquivo em Base64, junto comfilename. Dados enviados diretamente têm limite total de 8 MiB por requisição.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_dataouvision.- 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 comofile_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 /modelsindica emcapabilities.vision. Caso contrário, você recebe400 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_modelem uma imagem: o modelo não tem reconhecimento de imagem. Escolha um modelo comvision: 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.