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

Carregar ficheiros com a API de Ficheiros

Aula 1 de 16 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Do copiar-colar para documentos nativos
  2. O seu primeiro upload
  3. Parâmetros e autenticação
  4. Utilizar o ficheiro
  5. Pontos-chave

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.

48 MB
Tamanho máximo por ficheiro
POST
Método de upload HTTP
$10
Por 1.000 chamadas
Auto
Ativação do attachment_search

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/files aceita ficheiros até 48 MB em multipart/form-data
  • O parâmetro purpose deve ser "assistants"
  • O file_id devolvido é a sua referência para todas as operações subsequentes
  • A ferramenta attachment_search ativa-se automaticamente quando um ficheiro é referenciado num pedido
  • O custo é de $10 por 1.000 chamadas de anexo