API do Grok: integrando o Grok ao seu código

Duas maneiras de acessar o Grok via código

Os desenvolvedores podem chamar os modelos Grok de duas formas principais. A primeira é a API da xAI, gerenciada pela própria empresa (agora sob a marca SpaceXSI), com chaves obtidas no console.x.ai. A segunda é um roteador de modelos, como o OpenRouter, que reúne modelos de vários provedores em uma única chave e fatura. Ambos aceitam requisições no formato Chat Completions da OpenAI, portanto os SDKs oficiais da OpenAI funcionam perfeitamente assim que você altera o endereço base e o nome do modelo.

Qual opção escolher

• API da xAI se você quiser todos os recursos do Grok em primeira mão: a lista completa de modelos, a Responses API, ferramentas de busca na web e no X do lado do servidor, geração de imagens e vídeos com o Grok Imagine, voz, processamento em lote (batch) e descontos para prompts em cache. URL base: https://api.x.ai/v1.
• OpenRouter se você deseja alternar entre o Grok e modelos de outras empresas sem novos contratos, ou se já tiver uma conta no OpenRouter. URL base: https://openrouter.ai/api/v1, com IDs de modelos prefixados por x-ai/. As instruções de configuração estão no guia de início rápido do OpenRouter.

De qualquer forma, mantenha a chave em um servidor ou em uma variável de ambiente. Nunca a inclua diretamente em uma página web ou aplicativo móvel, onde qualquer pessoa possa visualizá-la.

Sua primeira requisição para a API da xAI

Crie uma chave no console, salve-a como XAI_API_KEY e envie uma mensagem para o Grok 4.7:

curl

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "reasoning_effort": "low",
    "messages": [
      {"role": "system", "content": "Você é um assistente conciso."},
      {"role": "user", "content": "Dê-me três dicas para a minha primeira maratona."}
    ]
  }'

Python, com a biblioteca da OpenAI

import os
from openai import OpenAI

grok = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

answer = grok.chat.completions.create(
    model="grok-4.3",
    reasoning_effort="medium",
    messages=[{"role": "user", "content": "O número 391 é primo? Mostre o passo a passo da verificação."}],
)
print(answer.choices[0].message.content)

O parâmetro reasoning_effort define por quanto tempo o modelo pensa antes de responder. O Grok 4.3 aceita none, low, medium, high e xhigh, tendo low como padrão; o Grok 4.7 aceita low, medium, high e xhigh, tendo high como padrão. Para o Grok 4.20, a xAI disponibiliza IDs separados: grok-4.20-0309-reasoning e grok-4.20-0309-non-reasoning.

O mesmo processo pelo OpenRouter

No OpenRouter, salve a chave em OPENROUTER_API_KEY e utilize os IDs com prefixo x-ai/. O OpenRouter controla o raciocínio por meio de um objeto reasoning. Este código JavaScript roda no Node.js 18 ou superior:

const endpoint = "https://openrouter.ai/api/v1/chat/completions";

const reply = await fetch(endpoint, {
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  method: "POST",
  body: JSON.stringify({
    model: "x-ai/grok-4.20",
    reasoning: { enabled: false },
    stream: false,
    messages: [{ role: "user", content: "Reescreva esta manchete em um tom mais calmo: OS PREÇOS EXPLODIRAM DE NOVO" }],
  }),
});
const json = await reply.json();
console.log(json.choices[0].message.content);

Para ativar o raciocínio do modelo, envie reasoning: { effort: "low" } (ou medium, high). Adicione exclude: true se quiser que o raciocínio seja processado, mas não retornado na resposta. Defina stream: true para receber a resposta em tempo real conforme ela é gerada, o que proporciona uma experiência bem mais rápida em interfaces de chat.

Enviando uma imagem

O Grok 4.20, o Grok 4.3 e o Grok 4.7 aceitam imagens. Use a estrutura de mensagens padrão da OpenAI com uma lista de partes. A documentação da xAI aceita imagens em JPEG e PNG de até 20 MiB; você pode utilizar tanto uma URL pública quanto uma URL base64.

{
  "model": "grok-4.20-0309-non-reasoning",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/receipt.png"}},
      {"type": "text", "text": "Liste os itens e o valor total deste recibo."}
    ]
  }]
}

IDs e preços dos modelos Grok

Estes são os modelos de texto atuais listados pelo OpenRouter para a SpaceXAI, com o tamanho de contexto e os preços por milhão de tokens (tabela do OpenRouter, out. de 2026). A API da xAI cobra as mesmas tarifas-base para prompts com menos de 200.000 tokens.

Alguns detalhes da página de modelos e preços da xAI (preços oficiais da xAI, out. de 2026):

• Prompts longos custam mais. Quando um prompt atinge 200.000 tokens, toda a requisição é cobrada pela taxa mais alta: $4 / $12 para o Grok 4.7, $2.50 / $5 para o Grok 4.3 e 4.20.
• Entradas em cache são mais baratas: $0.50 por milhão para o Grok 4.7 e $0.20 para o Grok 4.3 e 4.20, em prefixos de prompt reutilizados.
• Processamento em lote (batch) que pode aguardar na fila tem desconto, e o OpenRouter também oferece x-ai/grok-4.3:batch a $1 / $2.
• O tamanho do contexto varia conforme a fonte: o OpenRouter lista 2.000.000 de tokens para o Grok 4.20, enquanto a página oficial da xAI indica 1.000.000.

Tokens de raciocínio são contabilizados como saída, portanto um modelo de reasoning pode custar mais por resposta do que o valor base por token sugere.

Dicas práticas

• Comece com o Grok 4.20 non-reasoning para chats, reescrita e extração de dados. Ele é rápido e econômico. Migre para o Grok 4.3 ou 4.7 quando a qualidade em tarefas complexas for mais importante do que a velocidade.
• Fique atento ao limite de conhecimento (cut-off). O Grok 4.7 possui informações até maio de 2026, de acordo com a xAI. Para eventos mais recentes, inclua os fatos no próprio prompt ou utilize as ferramentas de busca na web e no X da xAI, que são cobradas por chamada.
• Defina uma mensagem de sistema especificando o papel, o tom e o formato de saída desejados, e exija JSON com validação de esquema quando seu código precisar processar a resposta.
• Gerencie os limites de requisições (rate limits). Tente novamente após uma breve pausa caso receba um erro 429.
• Siga os termos de uso. A política de uso aceitável da xAI se aplica ao uso da API, e o campo safety_identifier permite identificar as requisições de cada usuário final.

Solução de problemas

• Erros 401 ou 403: a chave de API não foi informada, foi revogada ou foi carregada no ambiente incorreto. Exiba os primeiros caracteres da chave no servidor para confirmar se ela foi carregada.
• Modelo não encontrado: confira o prefixo. O OpenRouter exige x-ai/grok-4.7, enquanto a xAI espera apenas grok-4.7.
• Respostas vazias ou muito lentas em modelos com raciocínio geralmente indicam que o limite de tokens de saída foi consumido pelo processo de pensamento. Reduza o nível de esforço ou aumente o max_tokens.
• Imagem recusada: converta o arquivo para JPEG ou PNG e certifique-se de que ele esteja abaixo do limite de tamanho.

Perguntas frequentes

A API do Grok é compatível com o SDK da OpenAI?

Sim. Basta direcionar o SDK para https://api.x.ai/v1 com uma chave da xAI, ou para o OpenRouter com uma chave do OpenRouter, e definir o ID de modelo do Grok.

Existe uma API gratuita do Grok?

Não há um plano gratuito permanente disponível. Tanto a xAI quanto o OpenRouter cobram pelo uso por token, embora testes curtos custem muito pouco.

Posso gerar imagens com a API do Grok?

Sim, por meio dos modelos Grok Imagine da xAI em um endpoint dedicado para imagens. Consulte nossa página sobre o Grok Imagine. Nosso chat não gera imagens.

Qual modelo do Grok é utilizado no Grok.Online?

Nosso chat disponibiliza o Grok 4.20 sem raciocínio, o Grok 4.3 com esforço de raciocínio baixo e o Grok 4.7 com limite de até 10 mensagens por dia, tudo integrado via OpenRouter.