Como usar a API GLM-5.2?

A API GLM-5.2 dá acesso programático ao novo modelo flagship de pesos abertos da Z.ai: um MoE de ~753B parâmetros com forte foco em codificação de longo contexto. Neste guia, você vai configurar a chave de API, fazer a primeira chamada com curl, integrar com Python, usar streaming, controlar raciocínio, executar tool calling e calcular custos por token.

Experimente o Apidog hoje

Se você já usava a versão anterior, comece pelas mudanças abaixo.

O que mudou desde o GLM-5.1

O GLM-5.2 substitui a geração 5.1. Se você já integrou a API GLM-5.1, o formato de comunicação permanece compatível. Na prática, a principal alteração no código é trocar o ID do modelo para glm-5.2.

Pontos importantes:

• Novo esquema de atenção esparsa: o GLM-5.2 introduz o IndexShare, que reutiliza um indexador em cada quatro camadas de atenção esparsa para reduzir custo em contextos longos. Como usuário da API, você não precisa configurar isso.
• Melhor desempenho em codificação agêntica: resultados publicados pela Z.ai colocam o Terminal-Bench 2.1 em 81.0, acima dos 62.0 do GLM-5.1.
• Dois níveis de esforço de raciocínio: o modelo expõe High e Max. A Z.ai recomenda Max para tarefas de codificação.

Tudo abaixo usa diretamente o modelo glm-5.2.

Passo 1: Obtenha uma chave de API GLM-5.2

Acesse z.ai, entre na sua conta e abra a seção de chaves de API. Crie uma chave e salve-a como variável de ambiente:

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

Não coloque a chave no código-fonte nem envie para o Git. Uma chave vazada pode gerar cobranças reais, já que o uso é calculado por tokens.

Passo 2: Configure endpoint, base URL e modelo

O GLM-5.2 é compatível com o formato OpenAI Chat Completions. Isso significa que clientes existentes do SDK da OpenAI podem ser reaproveitados mudando a base_url.

Configuração	Valor
Endpoint de Chat Completions	https://api.z.ai/api/paas/v4/chat/completions
URL base para SDKs	https://api.z.ai/api/paas/v4/
ID do modelo	glm-5.2
Autenticação	Authorization: Bearer $ZAI_API_KEY

Se preferir usar roteamento via OpenRouter, o alias é:

z-ai/glm-5.2

Para execução local, o Ollama publica o modelo como glm-5.2 na biblioteca Ollama. Os pesos abertos estão disponíveis no Hugging Face sob licença MIT.

Sobre limites:

• Janela de contexto: 1M tokens ou 1.048.576.
• Saída máxima: a documentação do z.ai lista até 128K tokens. Verifique a documentação ao vivo antes de depender desse limite em produção.

Passo 3: Faça a primeira requisição com curl

Use este exemplo mínimo para validar autenticação, endpoint e modelo:

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."}
    ]
  }'

A resposta segue o padrão OpenAI:

• id: identificador da requisição.
• choices: respostas geradas.
• usage: contagem de tokens para cálculo de custo.

Passo 4: Use o SDK Python da OpenAI

Instale o SDK:

pip install openai

Crie o cliente apontando para a API da Z.ai:

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)

Esse é o caminho mais simples para migrar código compatível com OpenAI. Retentativas, logs, wrappers e middlewares existentes geralmente continuam funcionando.

Para uma visão geral da família GLM, veja a visão geral da API GLM-5.

Passo 5: Controle raciocínio com thinking e reasoning_effort

O GLM-5.2 permite controlar o raciocínio interno do modelo.

Use thinking desabilitado para tarefas rápidas e baratas, como classificação, roteamento ou pequenas reescritas:

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

Para tarefas complexas de código ou matemática, habilite o raciocínio e use reasoning_effort: "max":

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",
    },
)

No SDK Python da OpenAI, campos específicos da Z.ai devem ser enviados via extra_body.

Em curl, coloque esses campos no mesmo nível de model:

{
  "model": "glm-5.2",
  "thinking": {"type": "enabled"},
  "reasoning_effort": "max",
  "messages": [
    {"role": "user", "content": "Optimize this SQL query."}
  ]
}

Use esforço máximo apenas quando a qualidade justificar o custo. Tokens de raciocínio contam como tokens de saída.

Passo 6: Transmita respostas com streaming

Para UIs de chat ou respostas longas, use streaming para renderizar tokens conforme chegam:

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)

Com curl, adicione "stream": true ao corpo da requisição. O servidor retorna Server-Sent Events:

data: {...}
data: {...}
data: [DONE]

Streaming não muda o preço. Você paga pelos mesmos tokens, apenas recebe a resposta incrementalmente.

Passo 7: Use chamada de função e ferramentas

Tool calling segue o padrão OpenAI em duas etapas:

1. Você descreve as ferramentas disponíveis.
2. O modelo retorna tool_calls.
3. Seu código executa a função real.
4. Você envia o resultado de volta ao modelo.
5. O modelo gera a resposta final.

Exemplo com uma ferramenta 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)

# Execute a função real aqui.
# Este retorno é apenas um stub para o exemplo.
def get_weather(city, unit="c"):
    return {"city": city, "temp": 12, "unit": unit}

result = get_weather(**args)

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)

Esse padrão também serve para múltiplas ferramentas, agentes e integrações com sistemas internos. O contrato não é específico da Z.ai; ele segue o formato OpenAI.

Para testar esse fluxo sem reescrever curl a cada tentativa, você pode usar o Apidog: configure o endpoint do GLM-5.2 uma vez, salve variações de corpo da requisição e inspecione respostas, inclusive chamadas de ferramentas e streaming.

Passo 8: Leia usage para calcular custos

Cada resposta não transmitida inclui usage:

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)
print(u.completion_tokens)
print(u.total_tokens)

Preços citados:

• Entrada: $1.40 por 1M tokens
• Saída: $4.40 por 1M tokens
• Entrada em cache: cerca de $0.26 por 1M tokens, segundo a VentureBeat

Exemplo de cálculo para 8.000 tokens de entrada e 1.500 tokens de saída:

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

Lembre-se: tokens de raciocínio com reasoning_effort: "max" entram na contagem de saída.

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”. Essa afirmação deve ser atribuída à VentureBeat.

Se você preferir planos fixos em vez de cobrança medida por API, a Z.ai também oferece planos de codificação GLM, incluindo Lite, Pro, Max e Team. Os preços podem mudar; verifique z.ai antes de decidir.

Para detalhes de precificação, veja a análise de preços do GLM-5.2. Para uso local, veja como usar o GLM-5.2 gratuitamente.

Usando GLM-5.2 dentro do Claude Code

O GLM-5.2 também oferece um caminho compatível com Anthropic para uso no Claude Code.

Configure a URL base de codificação como:

https://api.z.ai/api/coding/paas/v4

Algumas fontes mostram open.z.ai/api/paas/v4, então valide a URL atual antes de usar em produção.

Defina as 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 com contexto de 1M tokens. O API_TIMEOUT_MS alto evita que chamadas longas sejam encerradas antes da resposta.

Para mais detalhes, veja o guia sobre como executar GLM com Claude Code. Para comparar ferramentas, veja Claude Code vs Codex vs Cursor vs GLM Plan.

Referência rápida do GLM-5.2

Propriedade	GLM-5.2
ID do modelo na API	glm-5.2
Arquitetura	~753B MoE, BF16, atenção esparsa IndexShare
Janela de contexto	1M tokens ou 1.048.576
Saída máxima	até 128K pela documentação do z.ai, verificar ao vivo
Modos de pensamento	High / Max ou desabilitado
Preço de entrada	$1.40 / 1M tokens
Preço de saída	$4.40 / 1M tokens
Licença	MIT, pesos abertos

Resultados publicados pela Z.ai incluem:

• SWE-bench Pro: 62.1
• Humanity’s Last Exam com ferramentas: 54.7
• AIME 2026: 99.2
• MCP-Atlas: 77.0

Para uma análise mais detalhada, veja o resumo dos benchmarks do GLM-5.2 e a comparação GLM-5.2 vs GPT-5.5, Claude Opus e Gemini.

FAQ

A API GLM-5.2 é compatível com OpenAI?

Sim. Use o SDK da OpenAI com:

base_url="https://api.z.ai/api/paas/v4/"

E envie:

model="glm-5.2"

Chat, streaming e tool calling seguem o formato OpenAI.

Qual ID de modelo devo usar?

Depende do provedor:

Ambiente	ID
API da Z.ai	glm-5.2
OpenRouter	z-ai/glm-5.2
Ollama	glm-5.2
Claude Code	glm-5.2[1m]

Como desligar o raciocínio para reduzir latência?

Use:

extra_body={
    "thinking": {"type": "disabled"}
}

Para codificação complexa, use:

extra_body={
    "thinking": {"type": "enabled"},
    "reasoning_effort": "max"
}

Quanto custa uma chamada do GLM-5.2?

O preço citado é:

• $1.40 por 1M tokens de entrada
• $4.40 por 1M tokens de saída

Leia resp.usage para calcular o custo exato por chamada. Tokens de raciocínio em modo Max contam como saída.

O GLM-5.2 possui modelo de visão?

Não há variante de visão confirmada até junho de 2026. A API é texto-para-texto. Não dependa de entrada de imagem até que a Z.ai documente suporte.

Conclusão

A integração com a API GLM-5.2 é direta para qualquer base compatível com OpenAI:

1. Configure ZAI_API_KEY.
2. Use base_url="https://api.z.ai/api/paas/v4/".
3. Envie model="glm-5.2".
4. Adicione streaming, raciocínio e tool calling conforme necessário.
5. Leia usage para controlar custo.

Quando quiser testar endpoints, salvar variantes de requisição e inspecionar chamadas de ferramentas sem escrever curl manualmente, baixe o Apidog e configure o endpoint GLM-5.2 uma vez.

Para entender melhor o modelo, leia o que é o GLM-5.2 e a comparação GLM-5.2 vs GLM-5.1.