Pular para o conteúdo principal
Casos de uso
  • Escolher um modelo capaz de ler o tipo de arquivo que está sendo enviado.
  • Enviar uma imagem ou um documento em uma requisição ao modelo sem fazer upload antes.
  • Decidir entre uma URL pública e base64 para um determinado provedor.
Esta página explica quais modelos aceitam arquivos e como montar a requisição. Exemplos completos por modalidade, além de geração de imagens e áudio, ficam em Imagem, PDF e áudio: entradas multimodais e geração. Envie arquivos como partes de conteúdo em uma requisição ao modelo. Passe uma URL pública ou um data URI base64 diretamente, ou faça upload de um documento antes e referencie seu file_id. O AI Gateway converte o conteúdo para o formato que o provedor de destino espera. Duas coisas atrapalham a maioria das primeiras requisições:
  • Suporte a imagens e suporte a PDF são funcionalidades separadas. Um modelo que lê imagens com muita frequência não consegue ler um PDF.
  • Imagens e documentos usam partes de conteúdo diferentes, com campos obrigatórios diferentes.
Faça upload e gerencie documentos e imagens reutilizáveis pela Files API. Referencie o file_id retornado em uma requisição ao modelo usando os formatos abaixo. Para imagens, use input_image com file_id na Responses API, ou image_url com o ID do arquivo como image_url.url em Chat Completions.

​
Quais modelos aceitam o quê

Entre os modelos do catálogo do AI Gateway, entrada de imagem, entrada de PDF e entrada de áudio têm taxas de aceitação bem diferentes — e os conjuntos não estão contidos uns nos outros: suporte a imagens não implica suporte a PDF.
“Modelo de visão” não significa “lê PDFs”. Famílias inteiras aceitam imagens sem aceitar PDFs, incluindo Mistral (Pixtral, Magistral, Ministral, Mistral Medium), Llama 3.2 e Llama 4, Qwen 3.5 e 3.6, Grok 4.5 e 4.6 e Amazon Nova. A capacidade também varia dentro de uma família, então verifique o modelo específico em vez da família.
As abas de modalidade na página Models filtram por tipo de modelo (chat, geração de imagens, embedding), não pela entrada aceita. Para um modelo que não está na tabela acima, consulte a documentação do provedor antes de enviar um PDF.

​
Enviar uma imagem vs. enviar um documento

Imagens e documentos são partes de conteúdo diferentes. A tabela mostra o formato; para exemplos completos e executáveis em cada linguagem, consulte Imagem, PDF e áudio: entradas multimodais e geração.
input_file não é exclusivo para PDF. Os modelos da Anthropic também aceitam CSV, texto simples, JSON, Markdown, XML e RTF como documentos, e o AWS Bedrock aceita ainda DOC, DOCX, XLS, XLSX e HTML. Defina filename com a extensão correta para que o tipo seja detectado. O Bedrock reescreve os nomes de documentos usando apenas caracteres alfanuméricos, espaços, hífens e colchetes, truncados em 64 caracteres.

​
Referenciar um arquivo enviado

Use o file_id retornado pela Files API em uma parte de conteúdo input_file na Responses API, ou dentro do objeto aninhado file em Chat Completions. filename é opcional ao referenciar um file_id do Toqan Router: o AI Gateway usa o nome de arquivo armazenado e detecta o tipo de documento a partir dos metadados do arquivo armazenado. Inclua filename apenas para substituir o nome enviado naquela requisição; isso não renomeia o arquivo armazenado.
Coloque a primeira mensagem no array input da Responses API, ou a segunda no array messages de Chat Completions. O AI Gateway verifica o acesso ao workspace e ao projeto do arquivo e, em seguida, lê e encaminha o conteúdo armazenado. O modelo selecionado deve oferecer suporte ao tipo de documento.

​
URL ou base64?

Um data URI base64 funciona com todos os provedores e é o padrão mais seguro. URLs públicas são tratadas de forma diferente pelos provedores, e o AI Gateway absorve a maior parte da diferença: quando um provedor não consegue buscar uma URL por conta própria, o gateway baixa o arquivo e o insere inline antes de encaminhar a requisição. Vale a pena conhecer dois comportamentos de provedores: O Gemini lida com arquivos nativamente, e o gateway aproveita isso. Um fileUri da Gemini Files API é repassado diretamente em vez de baixado. Conteúdo base64 maior que 4 MB é enviado automaticamente para a Gemini Files API e encaminhado como fileUri, o que mantém documentos grandes fora do corpo da requisição. Apenas URLs públicas arbitrárias são buscadas e inseridas inline, porque o Gemini rejeita URIs desconhecidos com Invalid or unsupported file uri. No Vertex AI, gs:// e URLs públicas são resolvidos no servidor e repassados sem alterações. Um file_url de documento não chega à OpenAI. No caminho de mensagens, o gateway encaminha file_data, file_id e filename, de modo que um PDF fornecido como file_url chega sem origem e é ignorado. Envie o documento como um data URI base64 em file_data, ou referencie um arquivo enviado ao Toqan Router com file_id. Use base64 quando o arquivo não puder ser acessado pela internet pública, quando a URL exigir autenticação ou quando for necessária uma entrada idêntica byte a byte em uma cadeia de fallbacks. Use uma URL para manter os corpos das requisições pequenos e aproveitar o cache do lado do provedor.
Uma parte de conteúdo que um provedor não aceita pode ser descartada em vez de rejeitada: a requisição é bem-sucedida e o modelo responde sem nunca ter visto o arquivo. Se uma resposta ignorar o anexo, confirme que o modelo aceita esse tipo de entrada e que o meio de envio é compatível antes de depurar o prompt.