Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Formatos de ficheiros suportados

Aula 2 de 16 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. O único critério que importa
  2. As quatro categorias suportadas
  3. Armadilhas comuns
  4. Escolha o formato mais estruturado possível
  5. Pontos-chave

O único critério que importa

Antes de questionar se um formato específico funciona, coloque-se uma pergunta mais simples: o ficheiro contém texto extraível? A Files API da xAI processa ficheiros de texto. Se qualquer ferramenta conseguir extrair caracteres sem recorrer ao reconhecimento ótico de caracteres (OCR), o documento será provavelmente aceite. Ficheiros puramente binários — imagens, áudio, vídeo — não pertencem a este contexto; para uma imagem, a abordagem correta é utilizar input_image na Responses API, e não na Files API.

Este único critério explica a maioria das rejeições que encontrará. Explica também por que razão um relatório financeiro em PDF funciona perfeitamente, enquanto um PDF proveniente de um scanner de secretária falha: o primeiro possui uma camada de texto, o segundo é apenas uma série de fotografias de páginas.

As quatro categorias suportadas

Os formatos suportados dividem-se em quatro categorias, cada uma com as suas utilizações preferenciais.

CategoriaFormatosO que o Grok extrai
Documentos de escritórioPDF, DOCX, ODT, EPUB, RTFTexto, tabelas, estrutura de secções
Código-fonte.py, .js, .ts, .java, .go, .rs, .cpp, HTML, CSS, XML e mais de 80 linguagensImports, dependências, estrutura de ficheiros
Dados estruturadosCSV, TSV, JSON, JSON-LD, vCardHierarquia de campos, estatísticas, tendências
Texto simplesTXT, MDConteúdo linear, cabeçalhos e listas em Markdown

No âmbito dos documentos de escritório, o PDF continua a ser o formato mais comum, e o Grok extrai o seu texto, tabelas e divisão por secções. Um DOCX do Word mantém a sua formatação — negrito, itálico, listas — na extração, tal como o seu equivalente de código aberto ODT. O EPUB torna-se interessante assim que trabalha com publicações extensas, um white paper ou um manual completo, e o RTF, embora mais antigo, permanece suficientemente comum para ser suportado.

O código-fonte é onde a Files API se distingue mais claramente do simples copiar e colar. Enviar payment.py na íntegra, em vez de uma função isolada, altera a natureza da análise: o Grok visualiza os imports, as dependências e a organização do ficheiro, podendo assim detetar que uma exceção foi capturada trinta linhas acima ou que uma constante definida no topo contradiz um comentário no fundo. Estão cobertas mais de 80 linguagens com sintaxe baseada em texto.

Os formatos de dados servem primordialmente a análise quantitativa. Um CSV de vendas mensais permite ao Grok calcular variações, detetar sazonalidade e resumir um conjunto de dados de vários milhares de linhas; uma configuração JSON ou uma resposta de API dá-lhe acesso à hierarquia e às relações entre campos, algo que uma tabela achatada não mostraria. O JSON-LD adiciona contexto semântico a dados interligados, e o vCard abrange cartões de contacto. Por fim, o TXT e o MD funcionam conforme esperado, oferecendo o Markdown a vantagem de transmitir uma estrutura leve de cabeçalhos e listas.

Armadilhas comuns

Quatro restrições surgem constantemente em produção. A primeira é o tamanho: 48 MB por ficheiro, limite além do qual deve dividir o documento. A segunda é a codificação: os seus ficheiros devem estar em UTF-8, e uma exportação em ISO-8859 ou Windows-1252 produzirá caracteres acentuados corrompidos, por vezes de forma subtil — um `é` a tornar-se `é` no meio de um contrato passa despercebido até que uma pesquisa não devolva resultados. A terceira é a ausência de processamento de imagem: PNG, JPG ou GIF não pertencem a este contexto, devendo utilizar input_image. A quarta refere-se ao caso de um PDF digitalizado sem camada de texto OCR, que será aceite no carregamento mas não devolverá resultados quando consultado.

Esta última situação exige um hábito simples: antes de carregar um lote de PDFs de origem incerta, abra um e tente selecionar um parágrafo com o rato. Se nada for selecionado, os seus documentos devem passar previamente por um processamento OCR.

Escolha o formato mais estruturado possível

Quando a mesma informação existe sob múltiplas formas, escolha sempre a mais estruturada. Para análise de relatórios, prefira o PDF ou DOCX original, que preservam a hierarquia, em vez de uma exportação de texto plano. Para análise de dados, um CSV para tabelas e JSON para dados hierárquicos fornecerão melhores resultados do que uma exportação de folha de cálculo transformada em texto simples. Para uma revisão de código, envie o ficheiro fonte original com a sua extensão original. Para documentação, o Markdown ou o PDF funcionam dependendo do que possui na origem. A regra resume-se a uma frase: cada nível de estrutura que mantiver é um nível de contexto que o modelo não terá de reconstruir.

Pontos-chave

  • A Files API suporta documentos (PDF, DOCX, EPUB), código (mais de 80 linguagens), dados (CSV, JSON) e texto simples
  • O limite é de 48 MB por ficheiro, com codificação UTF-8
  • Imagens e ficheiros binários não são suportados — utilize input_image para imagens
  • Prefira sempre o formato mais estruturado possível para obter uma melhor análise