API Grok 4: Um guia passo a passo com exemplos

Começando com a API Grok 4

Antes de fazer nossa primeira solicitação de usuário, precisamos de uma chave API e um ambiente Python que consiga se conectar à API Grok.

Criando sua chave API

Para criar uma chave API que você pode usar para autenticar o cliente com a API, siga estas etapas:

1. Dá uma olhada no site oficial de documentação do xAI xAI.
2. Faça login com sua conta X, xAI ou Google. Se você ainda não tem uma conta, pode criar uma conta xAI nova.
3. Encontre a opção “Criar uma chave API”. Digite um nome para sua chave e clique em “salvar”.
4. Quando a chave aparecer, copia logo. Você não vai conseguir ver isso de novo depois, mas pode sempre criar um novo se precisar.
5. No diretório do seu projeto, crie um arquivo chamado .env. Coloque sua chave API aqui, usando esse formato:

XAI_API_KEY=<your_api_key_here>

Preços da API Grok 4

Embora usar a API possa ser mais barato do que optar por uma assinatura premium, ela não é gratuita. Diferente do plano SuperGrok, que começa em US$ 30 por mês com uma assinatura fixa, os custos da API são totalmente baseados em quanto você usa o serviço. Mas, se você quiser usar o Grok 4 Heavy, é diferente: você vai precisar de uma assinatura ativa do SuperGrok Heavy (US$ 300 por mês), mesmo se estiver usando a API.

Para ver um detalhamento das despesas possíveis, dá uma olhada na página de preços no xAI.

Fonte: xAI

O preço da API Grok é baseado no uso, medido por milhão de tokens. Só pra você saber, um milhão de tokens é mais ou menos igual a 750.000 palavras em inglês, seja como entrada ou saída. Mesmo que a janela de contexto tenha quase dobrado de tamanho em relação ao modelo anterior, o Grok 4 tem o mesmo preço do modelo padrão Grok 3. Você vai pagar US$ 3 por cada milhão de tokens de entrada e US$ 15 por cada milhão de tokens de saída.

Para acessar a API, você precisa comprar créditos. No começo, é melhor usar créditos pré-pagos em vez de cobrança automática — isso evita surpresas na conta. Você pode comprar tokens e acompanhar o uso no console xAI, em Faturas > Créditos.

Configuração do ambiente Python

Depois de ter sua chave API e créditos prontos, o próximo passo é preparar seu ambiente Python. Você vai precisar de dois pacotes pra uma integração API tranquila:

• python-dotenv para carregar sua chave API do arquivo .env como uma variável de ambiente.
• O cliente openai para interagir com a API Grok 4.

Para manter as dependências do seu projeto organizadas, é uma boa ideia usar o Anaconda. Depois de instalar o Anaconda, crie um novo ambiente chamado “ grok4 ” com o Python 3.10 executando:

conda create -n grok4 python=3.10
conda activate grok4

Com o ambiente ativo, instale os pacotes necessários:

pip install python-dotenv openai

Preparação final

Vamos começar escrevendo nosso primeiro script. Comece importando as funções necessárias dos pacotes que você instalou, junto com os para acessar sua chave API:

import os
from dotenv import load_dotenv
from openai import OpenAI

Depois, usa load_dotenv() do pacote dotenv pra carregar suas variáveis de ambiente, deixando sua chave API disponível pro script:

# Load environment variables
load_dotenv()

Agora, inicialize o cliente API passando sua chave API (do arquivo .env ) e a URL do servidor Grok para a classe OpenAI (vamos usar o SDK OpenAI neste tutorial, mas o Grok 4 também tem um SDK xAI Python nativo, que também é compatível com o SDK da Antrhopic). Atribua isso à variável client:

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

Com essas etapas, seu script está pronto para enviar solicitações ao Grok 4.

Reconhecimento de imagens com o Grok 4

Agora que já preparamos tudo, vamos testar o reconhecimento de imagens, uma das novas funcionalidades do Grok 4. Vamos mostrar isso colocando a foto de uma lasanha vegetariana e pedindo pro Grok identificar os ingredientes que dá pra ver.

Para analisar uma imagem com a API Grok 4, precisamos enviar uma solicitação que inclua uma imagem e um prompt. A maneira recomendada é usar um cliente Python compatível com OpenAI, especificando o modelo como grok-4 e incluindo a URL da imagem e sua pergunta na matriz de mensagens. A API vai mandar uma resposta detalhada com o conteúdo da imagem, que você pode ver no objeto de resposta.

Antes de mandar a solicitação, precisamos ter certeza de que a imagem está de acordo com os requisitos da API. Só dá pra usar os formatos JPEG e PNG, e o tamanho do arquivo não pode passar de 20 MB. A imagem precisa estar acessível por um link direto, e o servidor precisa mandar o cabeçalho Content-Type certo ( image/jpeg ou image/png).

Depois de importar os pacotes necessários, carregar suas variáveis de ambiente e configurar o cliente, podemos enviar nossa consulta assim:

# Sending the query
response = client.chat.completions.create(
    model="grok-4",
    messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://shorturl.at/mVDEh",
            "detail": "high"
          }
        },
        {
          "type": "text",
          "text": "Which ingredients do you notice on the picture?"
        }
      ]
    }
  ],
    max_tokens=2000,
    temperature=0.2,  # lower temperature for more deterministic answers
)

# Print the response
print(response.choices[0].message.content)

Based on the picture, it looks like a delicious slice of vegetarian lasagna! Here's what I can clearly see in terms of ingredients (I'm basing this purely on visual cues, so it's not a full recipe—just what's noticeable):
### Main Visible Ingredients:
- **Pasta sheets/lasagna noodles**: The flat, layered pasta that's the base structure of the dish.
- **Tomato sauce**: A red, chunky sauce (likely marinara or similar) that's spread between layers and on top.
- **Cheese**:
  - Melted, bubbly cheese on top (probably mozzarella or Parmesan, given the golden-brown spots).
  - White, creamy cheese in the filling layers (looks like ricotta or cottage cheese).
- **Spinach (or similar greens)**: Dark green leaves mixed into the layers, giving it a veggie-packed look (this seems like a spinach lasagna variant).
- **Basil leaf**: A fresh green leaf garnishing the top for decoration and flavor.
It doesn't appear to have any meat (like ground beef or sausage), so it's likely a vegetarian version. If this is from a specific recipe or if you have more context, I could refine my observations! What do you think it is? 😊

Nesse caso, o Grok até percebeu que era uma versão vegetariana só pela foto — muito legal!

Raciocinando com o Grok 4

O Grok 4 foi feito pra raciocínio avançado e consegue resolver problemas complexos passo a passo. Mas, diferente de alguns modelos anteriores, o Grok 4 não mostra seus rastros de raciocínio interno, então você não consegue extrair um “processo de pensamento” detalhado ou uma cadeia de pensamentos como um campo separado da resposta da API. O resultado que você recebe é a resposta final, não os passos intermediários do modelo ou o conteúdo bruto do raciocínio.

Além disso, o Grok 4 não suporta o parâmetro “ reasoning_effort ” usado, por exemplo, no Grok 3 mini (para saber como usar esse parâmetro, confira este tutorial da API do Grok 3). Isso quer dizer que você não pode ajustar o quanto o modelo “pensa” antes de chegar a uma conclusão final. Então, qualquer consulta de raciocínio é feita exatamente como uma consulta normal.

Vamos testar o Grok com outra tarefa de raciocínio relacionada à lasanha e pedir pra ele mostrar seu raciocínio na saída.

# Send a basic reasoning query
response = client.chat.completions.create(
    model="grok-4",
    messages=[
        {"role": "user", "content": (
            "You want to cook lasagna for a dinner party, but several guests have dietary restrictions. One is vegetarian, one is lactose-intolerant, and another cannot eat gluten. You have six different lasagna recipes (classic, vegetarian, vegan, gluten-free, cheese-heavy, and meat-based). Which recipe or combination of recipes would best satisfy everyone, and what specific ingredient substitutions would you need to make? Explain your reasoning step by step."
        )}
    ],
    max_tokens=5000,
    temperature=0.2,  # lower randomness
)
# Print the final answer
print(response.choices[0].message.content)

Below, I'll explain my reasoning step by step for selecting the best recipe (or combination of recipes) to satisfy all guests at your dinner party, including the vegetarian, the lactose-intolerant person, the gluten-intolerant person, and everyone else (who presumably have no restrictions). I'll base this on logical inferences about what each recipe likely contains, since the problem doesn't provide exact ingredient lists. Then, I'll recommend specific ingredient substitutions and why this approach works.
(...)
### Step 3: Selecting the Best Recipe or Combination
- **Recommended approach**: Use a **combination of the vegan and gluten-free recipes** to create a single modified lasagna that everyone can eat. Start with the vegan recipe as your base (it already handles no meat and no lactose/dairy), then incorporate elements from the gluten-free recipe (e.g., ingredient swaps to eliminate gluten). This results in a **vegan, gluten-free lasagna**.
  - Why not multiple lasagnas? Preparing separate dishes (e.g., one vegetarian, one gluten-free) could work but might not fully satisfy everyone in a shared meal—e.g., the lactose-intolerant guest couldn't eat a dairy-based vegetarian version. A single inclusive dish promotes unity at the party and simplifies cooking/serving. If you have time and oven space, you could make a small "classic" version on the side for unrestricted guests who prefer meat and cheese, but the modified vegan/gluten-free one would still be the core option.
  - Why this combination over others? Vegan + gluten-free covers all restrictions without needing to add meat or dairy (which would violate rules). Starting with gluten-free and making it vegan would require more substitutions (e.g., removing meat and cheese), while vegan is already "80% there." Other combos (e.g., vegetarian + gluten-free) would still need dairy removals for lactose intolerance, making them less efficient.
This approach ensures:
- The vegetarian can eat it (no meat).
- The lactose-intolerant can eat it (no dairy/lactose).
- The gluten-intolerant can eat it (no gluten).
- Others can eat it (it's still a flavorful lasagna, though it won't have "real" meat or cheese—unrestricted guests might find it less indulgent, but it's a fair compromise).
(...)

Cortei a resposta do Grok pra destacar os pontos principais, mas mesmo com essa versão mais curta, dá pra ver que o modelo funcionou bem. Grok fez tudo passo a passo para

• Entenda as restrições alimentares
• Dá uma olhada nas receitas que tem por aí.
• Escolha a melhor combinação de receitas
• Sugira substituições específicas de ingredientes
• Dá uma receita completa com todas as mudanças.
• Voltar ao motivo pelo qual isso satisfaz a todos
• Conversar sobre possíveis desvantagens e alternativas

Chamada de função com o Grok 4

Assim como o Grok 3, o Grok 4 também dá suporte a chamadas de funções. Permite que o modelo interaja diretamente com ferramentas e serviços externos. Isso quer dizer que o Grok não é só bom em criar textos — ele também consegue fazer coisas como pegar atualizações do tempo, ver horários de eventos, analisar registros de bancos de dados ou até mesmo controlar aparelhos inteligentes em casa.

Quando você manda uma solicitação, o Grok consegue ver se precisa de mais dados e pede pra chamar uma função específica com os parâmetros certos. O cliente Python cuida de rodar essa função localmente, passa o resultado de volta pro Grok e aí você recebe uma resposta completa e bem fundamentada.

Preparação

Para trabalhar com chamadas de funções, precisamos importar o pacote json, que nos permite acessar a estrutura de argumentos de qualquer função que o Grok chama. Depois, vamos definir uma função de retorno de chamada que o Grok vai chamar quando precisar de dados específicos.

Neste exemplo, a função “ suggest_lasagna_recipe ” é uma função Python simples que retorna uma sugestão de receita fixa. Essa abordagem codificada mantém a demonstração simples e evita a dependência de serviços externos.

import json

# Define the callback function
def suggest_lasagna_recipe(ingredients: list) -> dict:
    # Very simplified logic for demo purposes
    if "zucchini" in ingredients:
        return {"recipe": "Vegetarian Zucchini Lasagna"}
    if "beef" in ingredients:
        return {"recipe": "Classic Beef Lasagna"}
    if "tofu" in ingredients:
        return {"recipe": "Vegan Tofu Lasagna"}
    return {"recipe": "Basic Cheese Lasagna"}

Também precisamos definir a ferramenta que o Grok pode chamar. Isso envolve especificar o nome da ferramenta, a finalidade e os parâmetros necessários em um esquema JSON. Esse esquema é enviado para o Grok junto com a solicitação, dizendo que ele pode chamar essa ferramenta sempre que precisar de mais informações para ajudar no raciocínio.

# Define the JSON schema for the tool
tools = [
    {
        "type": "function",
        "function": {
            "name": "suggest_lasagna_recipe",
            "description": "Suggests a lasagna recipe based on available ingredients.",
            "parameters": {
                "type": "object",
                "properties": {
                    "ingredients": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "List of available ingredients"
                    }
                },
                "required": ["ingredients"]
            }
        }
    }
]

Por fim, o dicionário tools_map conecta os nomes das funções que o Grok usa às funções Python reais no seu código. Esse mapeamento permite que o cliente execute as chamadas de função solicitadas da maneira certa.

# link the function names to the functions
tools_map = {
    "suggest_lasagna_recipe": suggest_lasagna_recipe
}

Embora definir manualmente esquemas de ferramentas funcione bem para projetos simples, usar uma biblioteca de validação de dados como o Pydantic é super recomendado conforme seu projeto cresce. O Pydantic faz a validação automática das entradas das funções, melhora o tratamento de erros e deixa o código mais limpo e fácil de manter.

Execução

Vamos ver se o Grok usa nossa função quando pedimos uma receita de lasanha. Veja como funciona o fluxo de trabalho da chamada de função:

1. Primeiro, mandamos uma pergunta do usuário — “Que lasanha posso fazer com os ingredientes que tenho?” — pro Grok, junto com as receitas disponíveis tools. 
2. O Grok então analisa a solicitação e, se achar que precisa chamar uma função, pede a receita ativando nossa função local. Se não for chamada nenhuma ferramenta, a gente só usa a resposta inicial do Grok.
3. Quando alguém pede uma ferramenta, a gente chama a função local que faz isso e coloca o resultado no histórico de mensagens.
4. Esse histórico atualizado é enviado de volta para o Grok, permitindo que ele termine seu raciocínio e dê uma resposta final que faz sentido no contexto.

# Step 1: Send the initial user request
messages = [
    {"role": "user", "content": "I have beef, ricotta, and tomato sauce. Which lasagna can I make?"}
]

response = client.chat.completions.create(
    model="grok-4",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

# Step 2: Check if a tool call was requested
tool_calls = getattr(response.choices[0].message, "tool_calls", [])


if tool_calls:
    for tool_call in tool_calls:
        function_name = tool_call.function.name
        print(f"{function_name} successfully called")
        function_args = json.loads(tool_call.function.arguments)

        # Find and call the matching local function
        if function_name in tools_map:
            function_result = tools_map[function_name](**function_args)

            # Step 3: Add the function result back to the message history
            messages.append(response.choices[0].message)  # Assistant's tool call message
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps(function_result)
            })

            # Step 4: Send a new request including the tool response
            final_response = client.chat.completions.create(
                model="grok-4",
                messages=messages,
                tools=tools,
                tool_choice="auto"
            )

            # Print the final answer
            print("\nFinal Answer:")
            print(final_response.choices[0].message.content)
   
else:
    # No tool call: respond directly
    print("\nNo tool call was requested. Final Answer:")
    print(response.choices[0].message.content)

suggest_lasagna_recipe successfully called

Final Answer:
Based on your available ingredients (beef, ricotta, and tomato sauce), you can make a **Classic Beef Lasagna**! (...)

Como dá pra ver, o Grok chamou nossa função e sugeriu a receita certa.

Você também pode notar o argumento tool_choice na solicitação inicial. Por padrão, “auto” deixa o Grok decidir se deve chamar alguma função e qual. Se você quiser mais controle, pode forçar uma chamada de função específica, dizer exatamente qual função usar ou desligar completamente as chamadas de função mudando esse parâmetro.

Saídas estruturadas com o Grok 4

Parecido com a chamada de funções, as saídas estruturadas são um recurso que veio junto com o Grok 3. Eles deixam o Grok mandar respostas num formato bem específico, tipo JSON, em vez de texto simples. Essa abordagem facilita muito a análise, a validação e o uso das respostas do modelo em seus aplicativos ou fluxos de trabalho.

Ao definir um esquema com antecedência, você pode ter certeza de que os resultados do Grok serão sempre consistentes, legíveis por máquina e prontos para processamento posterior. Isso é super útil quando você precisa extrair dados organizados de documentos ou mandar conteúdo gerado por IA direto para bancos de dados, painéis ou ferramentas de automação, sem se preocupar com a análise de texto que pode dar errado.

Para definir o esquema de saída, usamos o Pydantic, que torna a estruturação de dados complexos mais simples e legível (este tutorial do Pydantic é muito bom). tutorial do Pydantic vai te ajudar a aprender mais). Pra isso, você vai precisar importar tanto BaseModel quanto Field de pydantic. Como nossa saída tem uma lista de ingredientes, também importamos List do módulo typing do Python pra deixar claro o tipo de cada elemento da lista.

Embora a gente pudesse configurar o esquema usando JSON simples, o Grok às vezes mostra resultados que não batem exatamente com a estrutura esperada. O significado pode ser o mesmo, mas o esquema pode ser diferente, o que pode causar problemas se o seu aplicativo precisar de um formato específico. Isso é especialmente verdadeiro para elementos aninhados, como listas. É por isso que recomendo usar o Pydantic — ele ajuda a garantir que a saída estruturada seja validada e analisada de forma confiável todas as vezes.

No nosso exemplo, o esquema — chamado “ Recipe” — inclui o nome, o número de porções e uma lista de ingredientes. Cada ingrediente ( Ingredient ) é definido pelo nome, a quantidade necessária para a receita, a disponibilidade, o preço por quilo e se é vegetariano, vegano ou sem glúten. É útil definir valores padrão no próprio esquema, como estamos fazendo para o número de porções.

# import additionally needed packages
from pydantic import BaseModel, Field
from typing import List

# Define the schema for the structured output
class Ingredient(BaseModel):
    name: str = Field(description="Name of the ingredient")
    amount: int = Field(description="Amount in g needed for recipe")
    is_at_home: bool = Field(description="Is the item already at home?")
    price: float = Field(description="Price of the ingredient in USD per kg")
    is_vegetarian: bool = Field(description="Is the ingredient vegetarian?")
    is_vegan: bool = Field(description="Is the ingredient vegan?")
    is_gluten_free: bool = Field(description="Is the ingredient gluten-free?")

class Recipe(BaseModel):
    name: str = Field(description="The name of the recipe")
    portions: int = Field(default=4, description="Amount of portions")
    ingredients: List[Ingredient] = Field(description="List of ingredients for the recipe")

Tem alguns detalhes que você precisa lembrar na hora de fazer o pedido. Em vez de usar client.chat.completions.create(), queremos chamar client.beta.chat.completions.parse(). Isso diz ao Grok que a gente espera a saída num formato específico, e nosso esquema Recipeé passado como o argumento response_format.

Também é legal colocar todas as instruções importantes da tarefa no prompt do sistema. Isso faz com que o Grok 4 fique focado e consistente durante toda a conversa. Como o esquema é definido separadamente, o prompt do usuário pode se concentrar na tarefa em si, sem precisar listar os campos necessários para a saída JSON.

Por exemplo, você pode configurar o Grok pra ser tipo um chef italiano, garantindo que todas as receitas que ele te dá sejam bem italianas, pra você não encontrar abacaxi na sua pizza!

# Send a prompt and request structured output
completion = client.beta.chat.completions.parse(
    model="grok-4",
    messages=[
        {"role": "system", "content": (
        "You are a master chef specialized in italian cuisine."
        "When asked about recipes, return the output in structured JSON format following the provided schema, without any extra text."
        )},
        {"role": "user", "content": (
        "I have beef, ricotta, and tomato sauce, and want to cook for 4 persons. Which lasagna can I make?"
        )}
    ],
    response_format=Recipe,
)

Depois de analisarmos a saída estruturada do Grok 4, as vantagens em relação ao texto simples ficam bem claras. A gente pode reorganizar e personalizar as informações facilmente pra se adequar às nossas necessidades, ou até mesmo inserir dados específicos diretamente em fluxos de trabalho automatizados. No nosso exemplo, isso quer dizer que a gente pode multiplicar rapidinho os preços dos ingredientes por quilo pelas quantidades necessárias, somar os custos com base no que já tem na despensa e calcular o preço final por porção com só algumas etapas.

# Access the parsed result
recipe = completion.choices[0].message.parsed


price = 0 # initialize price variable
print(f"Recipe: {recipe.name}")
print("Ingredients:")
for i in recipe.ingredients:
    print("- " + i.name + " " + str(i.amount) + " g")
    if not i.is_at_home:
        price += (i.price * i.amount / 1000)
print(f"Price per portion: USD {round((price/recipe.portions), 2)}")

Recipe: Classic Beef Lasagna
Ingredients:
- Ground beef 500 g
- Ricotta cheese 400 g
- Tomato sauce 800 g
- Lasagna noodles 300 g
- Mozzarella cheese 300 g
- Parmesan cheese 100 g
- Onion 200 g
- Garlic 20 g
- Olive oil 30 g
- Egg 50 g
Price per portion: USD 1.7625

Conclusão

O Grok 4 traz novas funcionalidades, como uma janela de contexto maior e melhores capacidades de raciocínio. O reconhecimento de imagens e a chamada de funções abrem possibilidades incríveis para juntar IA com dados e ações do mundo real, enquanto os resultados estruturados garantem respostas confiáveis e que podem ser lidas por máquinas. A configuração da API é simples, permitindo uma integração rápida nos seus projetos Python com apenas algumas dependências.

E se todos esses exemplos de lasanha deixaram você com fome, você não está sozinho — acho que vou ter que pegar uma fatia também!