Como configurar chaves de API, selecionar endpoints de modelos e implementar Function Calling com a API xAI Grok

Integrar os modelos Grok da xAI em aplicações de software é um processo rápido e intuitivo, impulsionado pela compatibilidade direta com os padrões do ecossistema OpenAI e pelo suporte a SDKs nativos. Operando a partir do endereço base https://api.x.ai/v1, a API do Grok possibilita autenticação segura via Bearer Token, seleção estratégica de endpoints — desde modelos de raciocínio avançado como o grok-4.7 até motores de alta velocidade como o grok-build-0.1 — e implementação de chamada de funções (Function Calling / Tool Calling) em múltiplos turnos para conectar o modelo a bancos de dados e microsserviços internos.

Este guia prático orienta os desenvolvedores na obtenção e configuração de credenciais, na escolha do modelo mais adequado e na implementação robusta de chamadas de funções em produção.

1. Configuração de chaves de API e autenticação

O gerenciamento de credenciais da API Grok é centralizado no Console da xAI (https://console.x.ai).

Passo 1: Gerar a chave de API

1. Acesse e faça login no xAI Console.
2. Na aba Billing (Faturamento), recarregue créditos para habilitar as chamadas à API.
3. Acesse a página API Keys (https://console.x.ai/team/default/api-keys) e clique em Create API Key.
4. Copie imediatamente a chave gerada e armazene-a de forma segura em seu cofre de segredos; o console não exibirá o valor completo novamente.

Passo 2: Definir variáveis de ambiente

Recomenda-se exportar a chave em uma variável de ambiente chamada XAI_API_KEY:

export XAI_API_KEY="xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Em projetos Node.js ou Python, configure-a no arquivo .env na raiz do projeto:

XAI_API_KEY=xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Passo 3: Inicializar o SDK

Devido à compatibilidade com a especificação REST da OpenAI, é possível utilizar a biblioteca oficial xai-sdk, a tradicional biblioteca openai, ou frameworks modernos como o Vercel AI SDK.

Python (usando a biblioteca openai):

import os
from openai import OpenAI

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

Python (usando o SDK nativo xai-sdk):

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))

Node.js / TypeScript (usando a biblioteca openai):

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

2. Seleção de endpoints de modelos e arquitetura

A xAI disponibiliza duas interfaces HTTP principais e uma matriz de modelos desenhada para equilibrar custo, contexto e capacidade analítica.

Protocolos de endpoint: /v1/responses vs /v1/chat/completions

• https://api.x.ai/v1/responses (Endpoint moderno recomendado): Projetado para arquiteturas de agentes autônomos (Agentic workflows), suporte nativo a rastreamento de estado com previous_response_id, saídas estruturadas e coordenação de ferramentas no lado do servidor.
• https://api.x.ai/v1/chat/completions (Compatível com OpenAI): Ideal para migração direta de sistemas já construídos sobre o padrão Chat Completions, necessitando apenas da troca de baseURL e apiKey.

Matriz de modelos de linguagem e raciocínio

Nota: Além dos modelos textuais, a xAI oferece endpoints especializados em voz bidirecional em tempo real (grok-voice-think-fast-2.0 na Voice API) e geração de imagens/vídeos (grok-imagine-image-2.0 na Imagine API).

3. Implementação de chamada de funções (Function Calling)

A chamada de funções permite que o Grok atue de forma ativa em vez de depender apenas de dados pré-treinados: quando uma pergunta requer dados em tempo real, o modelo emite argumentos estruturados em JSON para que o código do desenvolvedor execute a consulta.

Ciclo de vida da execução de ferramentas

1. Declaração de ferramentas: O cliente envia uma lista de ferramentas estruturadas em JSON Schema (name, description, parameters).
2. Avaliação inteligente: O Grok avalia a pergunta do usuário e decide se a invocação de uma ferramenta é necessária.
3. Disparo da chamada: O modelo suspende a geração de texto e retorna um objeto tool_calls contendo o nome da função e os parâmetros JSON correspondentes.
4. Execução local: O backend da sua aplicação processa a função e recupera os dados reais.
5. Continuação do fluxo: O resultado do processamento é devolvido ao Grok, que sintetiza a resposta final em linguagem natural.

Exemplo prático de implementação (Python com cliente OpenAI)

O exemplo a seguir demonstra a definição de uma ferramenta de busca de clientes no endpoint responses, o tratamento da chamada e a devolução da resposta ao grok-4.7:

import os
import json
from openai import OpenAI

# 1. Inicialização do cliente
client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

# 2. Definição do schema da ferramenta
tools = [
    {
        "type": "function",
        "name": "fetch_user_account",
        "description": "Obtém dados do perfil do cliente, nível de plano contratado e status da conta via ID.",
        "parameters": {
            "type": "object",
            "properties": {
                "account_id": {
                    "type": "string",
                    "description": "Identificador exclusivo do cliente, ex: 'usr_10294'"
                },
                "include_usage_stats": {
                    "type": "boolean",
                    "description": "Se deve incluir o consumo de tokens do ciclo atual de faturamento.",
                    "default": False
                }
            },
            "required": ["account_id"]
        }
    }
]

# Simulação da função local de backend
def execute_fetch_user_account(account_id: str, include_usage_stats: bool = False):
    return {
        "account_id": account_id,
        "name": "Alex Mercer",
        "tier": "Enterprise",
        "status": "Active",
        "usage_tokens": 1420500 if include_usage_stats else None
    }

# 3. Consulta inicial do usuário
user_query = "Consulte o perfil do usuário usr_10294 e confirme se ele possui uma assinatura Enterprise ativa."

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": user_query}],
    tools=tools,
)

# 4. Tratamento do disparo de chamada de ferramenta
for item in response.output:
    if item.type == "function_call":
        func_name = item.name
        func_args = json.loads(item.arguments)
        call_id = item.call_id
        
        print(f"Chamada de função solicitada: {func_name} com argumentos: {func_args}")
        
        if func_name == "fetch_user_account":
            tool_result = execute_fetch_user_account(**func_args)
            
            # 5. Enviar o resultado da ferramenta de volta ao Grok
            followup = client.responses.create(
                model="grok-4.7",
                input=[{
                    "type": "function_call_output",
                    "call_id": call_id,
                    "output": json.dumps(tool_result)
                }],
                tools=tools,
                previous_response_id=response.id,
            )
            
            # Exibição da resposta sintetizada final
            for followup_item in followup.output:
                if followup_item.type == "message":
                    print("\nResposta Final:\n", followup_item.content[0].text)

4. Regras fundamentais e recursos avançados

Durante a arquitetura de ferramentas com o Grok em ambientes corporativos, leve em consideração:

• Obrigatoriedade de objeto raiz no schema: No campo parameters de qualquer ferramenta, a raiz precisa ser expressamente "type": "object" (ou uma união oneOf/anyOf contendo ramos de objetos). Esquemas com tipos primitivos ou listas na raiz são rejeitados com erro HTTP 400.
• Chamadas de funções em paralelo (Parallel Function Calling): Por padrão, os modelos Grok podem disparar múltiplas chamadas simultâneas quando a solicitação envolve mais de uma fonte de dados. Caso deseje processamento estritamente sequencial, passe parallel_tool_calls: false no corpo da requisição.
• Controle de decisão (tool_choice):
  • "auto" (padrão): O Grok decide autonomamente se responde com texto ou aciona ferramentas.
  • "required": Força o modelo a invocar ao menos uma ferramenta antes de responder.
  • "none": Desativa a execução de ferramentas nessa interação.
  • {"type": "function", "function": {"name": "fetch_user_account"}}: Força o modelo a executar uma ferramenta específica.
• Integração de ferramentas do servidor e do cliente: O Grok permite arquiteturas híbridas. Desenvolvedores podem combinar funções locais com ferramentas gerenciadas nos servidores da xAI (como {"type": "web_search"} para busca web ou {"type": "x_search"} para busca no X). Ferramentas gerenciadas rodam na nuvem da xAI de forma autônoma, enquanto as funções locais são pausadas para o backend da sua aplicação responder.
• Streaming em bloco único: Em requisições com streaming ativado, o Grok entrega os metadados da chamada de função em um único bloco consolidado, eliminando a complexidade de remontar fragmentos parciais de JSON no cliente.

Referências

• Grok API Quickstart: Get Your API Key | SpaceXAI Docs
• Grok Models & Pricing | SpaceXAI Docs
• API Pricing | SpaceXAI Docs
• Function Calling | SpaceXAI Docs
• API Reference - REST API Reference | SpaceXAI Docs