Carregar ficheiros com a API de Ficheiros
Nesta página
Do copiar-colar para documentos nativos
Provavelmente já colou quinze páginas de um relatório num prompt, na esperança de que a formatação se mantivesse. Isso nunca acontece: as colunas das tabelas misturam-se e o modelo acaba por raciocinar sobre uma massa de texto informe. A API de Ficheiros da xAI resolve exatamente este problema. Envie o documento original; a xAI analisa-o no lado do servidor e o Grok trabalha sobre um conteúdo onde a estrutura, as tabelas e as quebras de secção são preservadas.
O mecanismo encaixa num único endpoint, POST /v1/files. Envie o seu ficheiro como multipart/form-data com um parâmetro purpose definido como "assistants" e a API devolve um identificador único chamado file_id. Este identificador torna-se a chave para tudo o que fizer a seguir: consultar o documento, verificar os seus metadados, eliminá-lo ou adicioná-lo a uma coleção.
O seu primeiro upload
Pegue num relatório anual em formato PDF que tenha na sua unidade. O pedido de upload não é JSON, mas sim multipart/form-data, o que explica a sintaxe -F em vez de -d:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
A resposta chega em poucos segundos e contém o identificador do ficheiro juntamente com as suas características:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
Este file_id — neste caso file_abc123xyz — é a sua referência permanente ao documento. Anote-o assim que receber a resposta: um identificador perdido significa um ficheiro órfão que consome quota sem ser utilizável.
Parâmetros e autenticação
Apenas dois parâmetros, ambos obrigatórios:
- file: O conteúdo binário do ficheiro, enviado como multipart. O tamanho máximo é de 48 MB
- purpose: Sempre
"assistants", o único valor aceite até à data. Indica que o ficheiro será utilizado para interações com o modelo
Vai atingir o limite de 48 MB mais depressa do que imagina: uma exportação de logs de um dia ou documentação completa de um produto excede regularmente esse valor. Nesse caso, divida a sua fonte em vários ficheiros coerentes em vez de truncar arbitrariamente; mais tarde, encontrará todos eles na mesma coleção.
No que toca à autenticação, cada pedido à API de Ficheiros transporta a sua chave de API padrão no cabeçalho Authorization: Bearer. Tenha em mente, desde já, que esta chave não é a Chave de API de Gestão: essa, reservada para coleções, surge mais adiante no curso e é frequentemente confundida com a primeira durante as primeiras tentativas.
Utilizar o ficheiro
O ficheiro carregado é inútil se não o referenciar num pedido. É esta a função do bloco input_file na API de Respostas, que acompanha com uma instrução em texto livre:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Resuma os pontos-chave deste documento."
}
]
}
O Grok recebe o ficheiro, ativa automaticamente a ferramenta attachment_search no lado do servidor, extrai passagens relevantes e escreve a sua resposta com base nelas. Não é necessária qualquer ativação manual, nem é preciso adicionar parâmetros adicionais: a presença de um input_file é suficiente para desencadear toda a cadeia. Cada chamada de anexo é faturada a $10 por 1.000, tornando um único upload consultado dez vezes mais económico do que dez uploads do mesmo documento.
Preços a partir de 5 de agosto de 2026 — os preços mudam regularmente: antes de qualquer cálculo orçamental, consulte a grelha atual na página oficial de modelos e preços da xAI.
Pontos-chave
- O endpoint
POST /v1/filesaceita ficheiros até 48 MB emmultipart/form-data - O parâmetro
purposedeve ser"assistants" - O
file_iddevolvido é a sua referência para todas as operações subsequentes - A ferramenta
attachment_searchativa-se automaticamente quando um ficheiro é referenciado num pedido - O custo é de $10 por 1.000 chamadas de anexo