Como usar a API GLM-5.2?

A API GLM-5.2 oferece acesso programático ao novo carro-chefe de pesos abertos da Z.ai, um modelo MoE de ~753B parâmetros que obtém as pontuações mais altas entre os modelos de código aberto em benchmarks de codificação de longo prazo. Este guia é prático. Você obtém uma chave de API, faz sua primeira requisição e, em seguida, trabalha com Python, curl, modos de pensamento, streaming, chamadas de ferramentas e rastreamento de custos, tudo com valores reais que você pode colar em um terminal.

Se você está vindo da versão anterior, comece por aqui.

O que mudou desde o GLM-5.1

O GLM-5.2 substitui a geração 5.1. Se você já escreveu código de integração para a API GLM-5.1, o formato de comunicação é o mesmo, então você basicamente só precisa trocar o ID do modelo. As diferenças que valem a pena conhecer são:

• Um novo esquema de atenção esparsa. O GLM-5.2 introduz o “IndexShare”, que reutiliza um único indexador em cada quatro camadas de atenção esparsa para reduzir o custo da atenção em contextos longos. Você não precisa interagir com ele como usuário da API; ele apenas torna a janela de 1M tokens mais barata de servir.
• Um salto real na codificação agêntica. Os resultados publicados da Z.ai colocam o Terminal-Bench 2.1 em 81.0, um aumento em relação ao 62.0 do GLM-5.1. Esta é a estatística principal para qualquer pessoa que esteja construindo agentes de codificação.
• Dois níveis de esforço de pensamento. O GLM-5.2 expõe os níveis de esforço de raciocínio Alto (High) e Máximo (Max), e a Z.ai recomenda o Máximo especificamente para tarefas de codificação. Mais detalhes abaixo.

Como o código de requisição da versão 5.1 já funciona, este guia não o repete. Tudo aqui se destina diretamente ao glm-5.2.

Passo 1: Obtenha uma chave de API GLM-5.2

Faça login em z.ai e abra a seção de chaves de API do seu painel de conta. Crie uma chave, copie-a uma vez (geralmente você não poderá vê-la novamente) e armazene-a em uma variável de ambiente em vez de colá-la no código-fonte:

export ZAI_API_KEY="your-glm-5.2-api-key"

Mantenha sua chave de API glm-5.2 fora do Git. Uma chave vazada gerará cobranças em sua conta, e a saída do GLM-5.2 é precificada por milhão de tokens, então um script descontrolado custa dinheiro de verdade.

Passo 2: Conheça o endpoint e a base_url

O GLM-5.2 é compatível com o formato OpenAI, o que significa que qualquer cliente que utilize o formato OpenAI Chat Completions funcionará assim que você redirecionar a URL base. Os valores que você precisa são:

O alias do OpenRouter é z-ai/glm-5.2 se você preferir rotear através do OpenRouter em vez de chamar o Z.ai diretamente. Para execuções locais, o Ollama publica os pesos como glm-5.2 (veja a biblioteca Ollama), e os pesos abertos estão disponíveis no Hugging Face sob uma licença MIT.

Uma observação sobre os limites antes de você começar a construir: a janela de contexto é de 1M tokens (1.048.576). Para saída máxima, a documentação do z.ai lista até 128K, mas o OpenRouter não publica um número, então considere até 128K conforme a documentação do z.ai (verifique ao vivo) em vez de uma garantia fixa.

Passo 3: Sua primeira requisição com curl

Aqui está uma chamada curl mínima para o glm-5.2. Ela envia uma mensagem de usuário e imprime a resposta JSON:

curl https://api.z.ai/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $ZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.2",
    "messages": [
      {"role": "system", "content": "You are a concise backend engineer."},
      {"role": "user", "content": "Write a SQL query that returns the 5 newest orders per customer."}
    ]
  }'

O formato da resposta corresponde ao padrão OpenAI: um id, um array choices com a mensagem do assistente e um objeto usage. Esse último campo é como você rastreia o custo, abordado no final.

Passo 4: Chame-o do Python com o SDK do OpenAI

Como a API é compatível com o OpenAI, você não precisa de um cliente especial. Instale o SDK padrão e aponte a base_url para Z.ai. Esta é a configuração canônica do python para glm-5.2:

pip install openai

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ZAI_API_KEY"],
    base_url="https://api.z.ai/api/paas/v4/",
)

resp = client.chat.completions.create(
    model="glm-5.2",
    messages=[
        {"role": "system", "content": "You are a concise backend engineer."},
        {"role": "user", "content": "Explain idempotency keys in 3 sentences."},
    ],
)

print(resp.choices[0].message.content)

Essa é a integração completa. O objeto client se comporta exatamente como faria com o OpenAI, então o código auxiliar existente, retentativas e logs são todos transferíveis. Se você quiser um tour mais aprofundado pela plataforma em si, a visão geral da API GLM-5 cobre as convenções de toda a família.

Passo 5: Controle o raciocínio com thinking e reasoning_effort

O GLM-5.2 é um modelo de raciocínio. Você pode ligar ou desligar seu "pensamento" interno e, quando ligado, pode definir o quão intensamente ele trabalha.

Desabilite o "pensamento" para respostas rápidas, baratas e de baixa latência (classificação, pequenas reescritas, roteamento):

resp = client.chat.completions.create(
    model="glm-5.2",
    messages=[{"role": "user", "content": "Classify: 'my card was charged twice'"}],
    extra_body={"thinking": {"type": "disabled"}},
)

Habilite o "pensamento" e defina o esforço como Máximo para codificação e matemática complexas. A Z.ai recomenda o Máximo especificamente para codificação:

resp = client.chat.completions.create(
    model="glm-5.2",
    messages=[
        {"role": "user", "content": "Refactor this function to remove the N+1 query and explain the fix."},
    ],
    extra_body={
        "thinking": {"type": "enabled"},
        "reasoning_effort": "max",
    },
)

O wrapper extra_body é como o SDK Python do OpenAI passa campos não padronizados para a Z.ai. Em um corpo curl bruto, você colocaria thinking e reasoning_effort no nível superior, ao lado de model. O esforço máximo consome mais tokens de saída (o raciocínio conta), então reserve-o para tarefas onde o salto de qualidade compensa.

Passo 6: Transmita a resposta (Stream)

Para UIs de chat e gerações longas, transmita os tokens à medida que chegam, em vez de esperar pela conclusão completa. Defina stream: true e itere sobre os blocos:

stream = client.chat.completions.create(
    model="glm-5.2",
    messages=[{"role": "user", "content": "Write a 200-word changelog entry for a rate-limit fix."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

No curl, adicione "stream": true ao corpo e o servidor retornará Eventos Enviados pelo Servidor (Server-Sent Events), uma linha data: por bloco, terminando com data: [DONE]. O streaming não altera nada sobre os preços; você ainda paga por token, apenas os vê mais cedo.

Passo 7: Chamada de função e ferramentas

A chamada de ferramentas é onde a força agêntica do GLM-5.2 se destaca, e ele obtém 77.0 no MCP-Atlas nos resultados publicados da Z.ai, próximo ao Claude Opus 4.8. O padrão é o processo padrão de dois passos do OpenAI: você descreve uma ferramenta, o modelo retorna uma requisição tool_calls, você executa a função e, em seguida, alimenta o resultado de volta.

Aqui está um pequeno exemplo realista da API glm-5.2 com uma consulta de clima:

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current temperature for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name, e.g. Berlin"},
                    "unit": {"type": "string", "enum": ["c", "f"]},
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "What's the weather in Berlin in celsius?"}]

first = client.chat.completions.create(
    model="glm-5.2",
    messages=messages,
    tools=tools,
)

call = first.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)

# You run the real function here. Stubbed for the example:
def get_weather(city, unit="c"):
    return {"city": city, "temp": 12, "unit": unit}

result = get_weather(**args)

# Append the assistant's tool call, then your tool's result.
messages.append(first.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": call.id,
    "content": json.dumps(result),
})

final = client.chat.completions.create(
    model="glm-5.2",
    messages=messages,
    tools=tools,
)

print(final.choices[0].message.content)

O modelo decide quando chamar a ferramenta, você a executa, e a segunda requisição permite que o GLM-5.2 transforme o resultado bruto em uma resposta natural. O mesmo loop se adapta a múltiplas ferramentas e a frameworks de agentes; nada no contrato é específico da Z.ai.

Testar este loop manualmente se torna tedioso rapidamente. Este é um bom lugar para usar o Apidog: você pode definir o endpoint do GLM-5.2 uma vez, salvar os corpos das requisições para cada modo de pensamento e reproduzir as chamadas de ferramentas sem reescrever o curl a cada vez. Ele lida com o esquema estilo OpenAI e permite inspecionar as respostas transmitidas em um só lugar.

Passo 8: Leia o objeto de uso para custos

Cada resposta não-transmitida contém um objeto usage. Essa é sua fonte de verdade para faturamento:

resp = client.chat.completions.create(
    model="glm-5.2",
    messages=[{"role": "user", "content": "Summarize REST vs gRPC in 4 bullets."}],
)

u = resp.usage
print(u.prompt_tokens, u.completion_tokens, u.total_tokens)

O preço do GLM-5.2 é de $1.40 por 1M de tokens de entrada e $4.40 por 1M de tokens de saída (confirmado pelo OpenRouter). A entrada em cache custa cerca de $0.26 por 1M (segundo a VentureBeat, atribuindo a eles o valor). Assim, uma chamada com 8.000 tokens de entrada e 1.500 tokens de saída custa aproximadamente:

(8000 / 1_000_000 * 1.40) + (1500 / 1_000_000 * 4.40)
= 0.0112 + 0.0066
= cerca de $0.0178

Tokens de raciocínio provenientes do esforço Máximo são contabilizados na contagem de saída, então uma chamada de codificação com esforço Máximo será mais cara do que uma com o "pensamento" desabilitado. A VentureBeat relata que o GLM-5.2 “supera o GPT-5.5 em codificação de longo prazo a aproximadamente 1/6 do custo”, o que é a proposta econômica por trás desses números (atribuindo a afirmação à VentureBeat).

Se você preferir usar um plano de tarifa fixa em vez de chamadas de API por medição, a Z.ai também oferece níveis de planos de codificação GLM (Lite, Pro, Max, mais Equipe). Os preços exatos podem mudar, portanto, a partir de junho de 2026, verifique os níveis atuais em z.ai antes de se comprometer. Para uma comparação direta no lado da medição, a análise de preços do GLM-5.2 aprofunda-se, e como usar o GLM-5.2 gratuitamente aborda a rota de pesos locais.

Usando GLM-5.2 dentro do Claude Code

O GLM-5.2 também oferece um caminho compatível com Anthropic, para que você possa utilizá-lo a partir do Claude Code. Aponte a URL base de codificação para https://api.z.ai/api/coding/paas/v4 (algumas fontes mostram open.z.ai/api/paas/v4, então verifique ao vivo), então defina estas variáveis de ambiente:

export ANTHROPIC_BASE_URL="https://api.z.ai/api/coding/paas/v4"
export ANTHROPIC_API_KEY="your-glm-coding-plan-key"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-5.2[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-5.2[1m]"
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000
export API_TIMEOUT_MS=3000000

O sufixo [1m] seleciona a variante de contexto de 1M, e o longo API_TIMEOUT_MS é importante: sem ele, o Claude Code pode encerrar chamadas longas de grande contexto antes que elas retornem. O guia completo está em nosso artigo sobre como executar GLM com Claude Code, e se você está avaliando ferramentas, Claude Code vs Codex vs Cursor vs GLM Plan apresenta os trade-offs.

Como o GLM-5.2 se compara

Referência rápida para os valores que impulsionam as decisões de integração:

Para detalhes de benchmark, os resultados publicados da Z.ai incluem SWE-bench Pro 62.1 (GPT-5.5 58.6), Humanity’s Last Exam com ferramentas 54.7, e AIME 2026 99.2. O resumo dos benchmarks do GLM-5.2 detalha esses resultados, e GLM-5.2 vs GPT-5.5, Claude Opus e Gemini os compara lado a lado.

FAQ

A API GLM-5.2 é realmente compatível com OpenAI? Sim. Aponte a base_url do SDK do OpenAI para https://api.z.ai/api/paas/v4/ e defina o modelo para glm-5.2. O código padrão de chat, streaming e chamada de ferramentas funciona sem alterações.

Qual é o ID do modelo GLM-5.2 que devo enviar? Envie glm-5.2 para a API da Z.ai. No OpenRouter é z-ai/glm-5.2, no Ollama é glm-5.2, e a variante do Claude Code é glm-5.2[1m] para a janela de contexto de 1M.

Como desligo o raciocínio para aumentar a velocidade? Passe thinking: {"type": "disabled"} (via extra_body no SDK Python). Para tarefas de codificação complexas, habilite o pensamento e defina reasoning_effort: "max", que a Z.ai recomenda para código.

Quanto custa cada chamada do GLM-5.2? $1.40 por 1M de tokens de entrada e $4.40 por 1M de tokens de saída (confirmado pelo OpenRouter). Leia o objeto usage em cada resposta para calcular o custo exato; lembre-se de que os tokens de raciocínio de esforço Máximo contam como saída.

O GLM-5.2 possui um modelo de visão? Não há variante de visão confirmada até junho de 2026. A API é de texto de entrada, texto de saída. Não dependa de entradas de imagem até que a Z.ai documente o suporte.

Conclusão

A API GLM-5.2 está a um passo de qualquer base de código compatível com OpenAI: troque a URL base, envie glm-5.2, e você terá um modelo de codificação com contexto de 1M, licença MIT e raciocínio ajustável com preço de saída de $4.40 por 1M de tokens. Comece com um ping curl, passe para o SDK Python e, em seguida, adicione modos de pensamento e chamada de ferramentas conforme suas necessidades de uso.

Quando estiver pronto para testar endpoints, salvar variantes de requisição e inspecionar as chamadas de ferramentas sem precisar escrever curl manualmente a cada vez, baixe o Apidog e configure o endpoint GLM-5.2 uma vez. Para uma visão mais ampla sobre o modelo em si, veja o que é o GLM-5.2 e a comparação GLM-5.2 vs GLM-5.1.