Como Obter uma Chave API Grok e Fazer Sua Primeira Chamada (Grok 4.6)

Uma chave de API Grok é a credencial que a xAI emite de seu console de desenvolvedor para que seu código possa chamar modelos Grok via HTTPS. Você a cria uma vez, a envia como um token Bearer em cada requisição, e a xAI fatura os tokens que você usa contra os créditos pré-pagos da sua equipe. Se o conceito é novo, o que é uma chave de API aborda o básico; este guia é para desenvolvedores que querem a chave funcionando hoje.

A sequência é a seguinte: crie a chave em console.x.ai, faça uma requisição com curl e outra com Python, então mova a chave para o Apidog para que você possa armazená-la com segurança, enviar requisições sem colá-la em um shell e transformar essa primeira requisição em um teste salvo. O modelo carro-chefe atual é o grok-4.6, e todos os exemplos abaixo o utilizam.

button

O que você precisa antes de começar

Uma conta xAI. Cadastre-se em console.x.ai.

Créditos na conta. O console funciona com créditos pré-pagos, e o guia de início rápido oficial recomenda carregar créditos logo após o cadastro. Com saldo zero, as requisições são rejeitadas.
curl (vem com macOS e a maioria das distribuições Linux) e Python 3.9 ou posterior com pip.
Apidog se você deseja que a requisição seja armazenada, testada e compartilhável. O plano gratuito cobre 4 usuários, o que é suficiente para uma pequena equipe. Baixe o Apidog antes da Etapa 4.

Etapa 1: crie a chave no console xAI

Faça login e abra Faturamento. Em gerenciamento de gastos com API, compre créditos com cartão (eles são creditados imediatamente) ou transferência bancária (dois a três dias úteis, de acordo com a documentação de faturamento).
Abra a página Chaves de API. O início rápido a vincula em console.x.ai/team/default/api-keys. O segmento team é importante: as chaves pertencem a uma equipe, não ao seu login pessoal.
Clique em Criar chave de API e dê a ela um nome que você reconhecerá em seis meses. “apidog-local-dev” é melhor que “chave1”.
Copie a chave assim que ela for criada. Considere esta a única vez que você verá o valor completo.
Armazene-a como uma variável de ambiente em vez de no código:

export XAI_API_KEY="cole-sua-chave-aqui"

XAI_API_KEY é o nome da variável que a documentação oficial usa, então o próprio SDK da xAI e a maioria das integrações da comunidade o reconhecem sem configuração extra.

Uma chave por ambiente é um bom hábito. Chaves separadas para desenvolvimento local, CI e produção significam que uma chave de laptop vazada pode ser excluída sem afetar qualquer outra coisa.

Etapa 2: faça sua primeira chamada com curl

O endpoint de texto primário da xAI é POST https://api.x.ai/v1/responses. Envie a chave no cabeçalho Authorization, JSON no corpo e o ID do modelo no campo model:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "instructions": "You are a senior backend engineer. Answer in three sentences.",
    "input": "My API returns 429 to a client that retries instantly. What should the client change?"
  }'

Uma resposta bem-sucedida é um JSON com um array output. O texto está em output[].content[].text com "type": "output_text", e um objeto usage reporta input_tokens, output_tokens e total_tokens, além de detalhamentos para tokens de raciocínio e cache. Esses números de uso são o que você é cobrado, então registre-os desde o primeiro dia.

Dois detalhes que vale a pena saber:

instructions é o prompt do sistema. Você também pode passar input como um array de mensagens {role, content} se preferir o formato de chat.
Se você tem código existente no estilo OpenAI, POST https://api.x.ai/v1/chat/completions ainda funciona com a mesma chave e ID de modelo. A xAI o rotula como um endpoint legado e lança novos recursos para Respostas primeiro, então inicie novos projetos em /v1/responses.

Para streaming, chamadas de ferramentas e entrada de imagem neste mesmo endpoint, consulte como usar a API Grok 4.6.

Etapa 3: a mesma chamada do Python

A API REST da xAI é compatível com o SDK OpenAI, então você não precisa de uma nova biblioteca cliente. Aponte base_url para a xAI e leia a chave do ambiente:

import os
from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.6",
    instructions="You are a senior backend engineer. Answer in three sentences.",
    input="My API returns 429 to a client that retries instantly. What should the client change?",
)

print(response.output_text)
print(response.usage.input_tokens, response.usage.output_tokens)

Instale o SDK com pip install openai. A leitura de os.environ["XAI_API_KEY"] levanta um claro KeyError se a variável estiver faltando, o que é melhor do que enviar um cabeçalho Bearer vazio e depurar um 401.

A xAI também publica um SDK Python nativo (xai-sdk) com transporte gRPC e recursos extras como Coleções e a API de Voz. Para uma primeira chamada, o cliente OpenAI é o caminho mais curto.

Etapa 4: armazene e teste a chave no Apidog

Colar uma chave em um terminal funciona uma vez. Compartilhar a requisição com um colega de equipe, executá-la novamente após uma atualização de modelo ou colocá-la em CI é onde um cliente de API ganha seu lugar. Veja o fluxo no Apidog.

Armazene a chave como um valor local. Abra Ambientes, crie um chamado “xAI” e adicione duas variáveis: baseUrl com o valor compartilhado https://api.x.ai/v1, e XAI_API_KEY com um placeholder como seu valor compartilhado e sua chave real em seu valor local. Valores compartilhados sincronizam com colegas de equipe; valores locais permanecem no cache do seu cliente em sua máquina e nunca chegam aos servidores do Apidog. O nome da variável é enviado com o projeto, o segredo não. Ambientes Apidog e variáveis secretas cobrem a divisão entre compartilhado e local em detalhes, incluindo como o CI injeta sua própria chave.

Envie a primeira requisição. Crie um novo endpoint: POST {{baseUrl}}/responses. Na aba Auth, escolha Bearer Token e insira {{XAI_API_KEY}}. Cole o corpo JSON da Etapa 2, selecione o ambiente xAI e clique em Enviar. O painel de resposta mostra status, tempo e o corpo analisado, para que você possa clicar em output e usage em vez de ler o JSON bruto.

Salve-o como um teste. Em Processadores Pós-Requisição, adicione uma etapa de Asserção: código de status igual a 200, e uma verificação JSONPath que $.model seja igual a grok-4.6. Adicione uma segunda asserção de que $.usage.output_tokens é maior que 0. Salve o endpoint, abra Testes, crie um cenário de teste e importe o endpoint para ele. A partir daí, um clique executa novamente a chamada e informa se a chave, o ID do modelo e a forma da resposta ainda funcionam.

Opcional: simule. Salve a resposta real como um exemplo no endpoint e mude para a URL de mock do Apidog. O trabalho de front-end e os testes de unidade podem ser executados contra uma resposta falsa do Grok sem gastar créditos ou atingir limites de taxa.

Limites, créditos e preços

Faturamento. Os créditos são pré-pagos por equipe. A recarga automática pode comprar mais quando seu saldo cai abaixo de um limite que você define (mínimo de US$ 5 por recarga), com um limite mensal e um aviso em 80% dele. O faturamento mensal existe, mas está desativado por padrão e passa pelas vendas da xAI; com o limite faturado padrão de US$ 0, as requisições são rejeitadas no momento em que os créditos pré-pagos acabam.

Preços do Grok 4.6 por milhão de tokens, da página de preços oficial:

Tamanho do Prompt	Entrada	Entrada em Cache	Saída
Abaixo de 200k tokens	$2.00	$0.50	$6.00
200k tokens ou mais	$4.00	$1.00	$12.00

A janela de contexto é de 500k tokens. Uma requisição cujo prompt ultrapassa o limite de 200k é cobrada pela taxa mais alta por todos os seus tokens, não apenas pelo excesso.

Limites de taxa. A xAI limita requisições por segundo e tokens por minuto. Os números dependem do seu nível: cinco níveis (0 a 4) mais Empresarial, desbloqueados automaticamente pelo gasto cumulativo desde 1º de janeiro de 2026, e um nível nunca regride. Os limites atuais da sua equipe estão na página Modelos no console. Cada token conta para o TPM, incluindo tokens de raciocínio e tokens de prompt em cache.

Créditos gratuitos. A documentação da xAI descreve um modelo pré-pago e não anuncia um nível gratuito permanente para a API. Créditos promocionais apareceram no console em alguns momentos; verifique sua própria página de Faturamento em vez de confiar em uma postagem de blog.

Erros comuns e como corrigi-los

401 Não Autorizado. A chave estava faltando, malformada ou foi excluída. Verifique se o cabeçalho lê Authorization: Bearer <key> com um único espaço, se $XAI_API_KEY está definido no shell que executa o curl (echo $XAI_API_KEY | wc -c deve imprimir mais de 1), e se a chave ainda existe no console. Uma quebra de linha extra de um copiar e colar é uma causa clássica.

403 Proibido. A chave é válida, mas não tem permissão para fazer o que você pediu. Razões prováveis: a chave ou equipe está bloqueada, os créditos foram esgotados com um limite faturado de US$ 0, ou a equipe não tem acesso ao modelo. Verifique o Faturamento primeiro, depois a chave na página Chaves de API.

429 Muitas Requisições. Você atingiu o limite de RPS ou TPM para o seu nível. Adicione um recuo exponencial com jitter, limite a concorrência, reduza o tamanho do prompt e mova o trabalho em massa para a API Batch. Se você permanece no limite o dia todo, a solução é o nível de gasto, não o código.

400 Requisição Inválida. Geralmente um ID de modelo incorreto (grok-4.6, não grok-4-6) ou JSON inválido. O corpo do erro nomeia o campo.

Um guia mais completo para ler essas respostas, incluindo falhas de streaming e chamadas de ferramentas, está em como testar e depurar requisições da API Grok 4.6.

FAQ

Existe uma chave de API Grok gratuita?

Não como uma oferta documentada e permanente. A API funciona com créditos pré-pagos, e o guia de início rápido informa para carregar créditos antes da primeira chamada. Se seu objetivo é experimentar o Grok em vez de construir sobre ele, como usar o Grok gratuitamente aborda as rotas de consumidor que não precisam de uma chave.

Uma chave de API Grok funciona com o SDK da OpenAI?

Sim. Defina base_url="https://api.x.ai/v1" e passe sua chave xAI como api_key. Tanto client.responses.create() quanto o legado client.chat.completions.create() funcionam com model="grok-4.6".

Qual ID de modelo devo colocar nas requisições?

grok-4.6 para o carro-chefe. O alias grok-4.6-latest rastreia a revisão mais recente. IDs mais antigos como grok-4.5 e grok-4.3 permanecem listados com seus próprios preços, mas novos trabalhos devem começar com o 4.6.

O que devo fazer se minha chave vazar?

Exclua-a imediatamente na página Chaves de API, crie uma substituta e atualize a variável de ambiente em todos os lugares onde ela é usada. Em seguida, procure em seus repositórios e logs de CI pelo valor antigo. No plano Enterprise do Apidog, o Secret Scanner sinaliza chaves em requisições, variáveis, scripts e documentos, o que detecta o caso em que alguém colou uma chave em um valor compartilhado em vez de um local.

Próximo passo

Agora você tem uma chave de API Grok funcionando, uma chamada curl e Python bem-sucedida, e a requisição salva no Apidog como um teste repetível. Aponte esse teste para seus prompts reais, observe os números de usage, e você saberá seus gastos e margem de limite de taxa antes que o tráfego de produção o faça.