Como usar a API GLM-5.1: guia completo com exemplos de código

TL;DR

O GLM-5.1 está disponível através da API BigModel em https://open.bigmodel.cn/api/paas/v4/. A API é compatível com OpenAI: mesma estrutura de endpoint, mesmo formato de requisição, mesmo padrão de streaming. Você precisa de uma conta BigModel, uma chave de API e o nome do modelo glm-5.1. Este guia abrange autenticação, sua primeira requisição, streaming, chamada de ferramentas e teste de sua integração com o Apidog.

Introdução

GLM-5.1 é o modelo agente carro-chefe da Z.AI, lançado em abril de 2026. Ele ocupa o primeiro lugar no SWE-Bench Pro e supera o GLM-5 em todos os principais benchmarks de codificação. Se você está construindo um assistente de codificação de IA, um agente autônomo ou qualquer aplicação que se beneficie da execução de tarefas de longo prazo, vale a pena integrar o GLM-5.1.

A boa notícia para os desenvolvedores: a API é compatível com OpenAI. Se você já construiu com GPT-4 ou Claude, pode mudar para o GLM-5.1 alterando a URL base e o nome do modelo. Nenhum SDK novo para aprender. Nenhum formato de resposta diferente para lidar.

Pré-requisitos

Antes de fazer sua primeira chamada, você precisa:

1. Uma conta BigModel em bigmodel.cn. O registro é gratuito.
2. Uma chave de API no console BigModel em "API Keys".
3. Python 3.8+ ou Node.js 18+ (os exemplos cobrem ambos).
4. O SDK da OpenAI ou requests/fetch padrão (a API do GLM-5.1 é compatível com OpenAI).

Defina sua chave de API como uma variável de ambiente:

export BIGMODEL_API_KEY="sua_chave_api_aqui"

Nunca codifique chaves de API diretamente em seu código-fonte.

Autenticação

Cada requisição precisa de um token Bearer no cabeçalho Authorization:

Authorization: Bearer SUA_CHAVE_API

O formato da chave de API BigModel se parece com xxxxxxxx.xxxxxxxxxxxxxxxx, uma string de duas partes separadas por um ponto. Isso é diferente do formato `sk-` da OpenAI, mas funciona da mesma forma no cabeçalho.

URL Base

https://open.bigmodel.cn/api/paas/v4/

O endpoint de completions de chat é:

POST https://open.bigmodel.cn/api/paas/v4/chat/completions

Sua primeira requisição

Usando curl

curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.1",
    "messages": [
      {
        "role": "user",
        "content": "Escreva uma função Python que encontre todos os números primos até n usando o Crivo de Eratóstenes."
      }
    ],
    "max_tokens": 1024,
    "temperature": 0.7
  }'

Usando Python (requests)

import os
import requests

api_key = os.environ["BIGMODEL_API_KEY"]

response = requests.post(
    "https://open.bigmodel.cn/api/paas/v4/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "model": "glm-5.1",
        "messages": [
            {
                "role": "user",
                "content": "Escreva uma função Python que encontre todos os números primos até n usando o Crivo de Eratóstenes."
            }
        ],
        "max_tokens": 1024,
        "temperature": 0.7
    }
)

result = response.json()
print(result["choices"][0]["message"]["content"])

Usando o SDK da OpenAI (recomendado)

Como a API é compatível com OpenAI, você pode usar o SDK oficial do OpenAI para Python com uma URL base personalizada:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

response = client.chat.completions.create(
    model="glm-5.1",
    messages=[
        {
            "role": "user",
            "content": "Escreva uma função Python que encontre todos os números primos até n usando o Crivo de Eratóstenes."
        }
    ],
    max_tokens=1024,
    temperature=0.7
)

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

Esta é a abordagem mais limpa. O SDK da OpenAI lida com retentativas, gerenciamento de timeout e parsing de resposta. Você obtém tudo isso gratuitamente apenas apontando-o para a URL base do BigModel.

Formato da resposta

A estrutura da resposta é idêntica à da OpenAI:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1744000000,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "def sieve_of_eratosthenes(n):\n    ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 215,
    "total_tokens": 247
  }
}

Acesse o texto da resposta via result["choices"][0]["message"]["content"].

O campo usage mostra a contagem de tokens para a requisição. Monitore isso para acompanhar o consumo da sua cota, já que o GLM-5.1 cobra 3x a cota durante os horários de pico (14:00-18:00 UTC+8).

Streaming de respostas

Para tarefas longas de geração de código, o streaming fornece tokens à medida que chegam, em vez de esperar pela resposta completa. Isso é essencial para qualquer aplicação voltada para o usuário.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

stream = client.chat.completions.create(
    model="glm-5.1",
    messages=[
        {
            "role": "user",
            "content": "Explique como funciona um índice B-tree em um banco de dados, com um exemplo de código."
        }
    ],
    stream=True,
    max_tokens=2048
)

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

print()  # nova linha após o streaming ser concluído

Cada "chunk" no stream é um delta contendo apenas os novos tokens desde o último chunk. O chunk final tem finish_reason definido como "stop" (ou "length" se você atingir o limite de tokens).

Streaming com requisições diretas

Se você preferir não usar o SDK da OpenAI:

import os
import json
import requests

api_key = os.environ["BIGMODEL_API_KEY"]

response = requests.post(
    "https://open.bigmodel.cn/api/paas/v4/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "model": "glm-5.1",
        "messages": [{"role": "user", "content": "Escreva um merge sort em Python."}],
        "stream": True,
        "max_tokens": 1024
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        line = line.decode("utf-8")
        if line.startswith("data: "):
            data = line[6:]
            if data == "[DONE]":
                break
            chunk = json.loads(data)
            delta = chunk["choices"][0]["delta"]
            if "content" in delta:
                print(delta["content"], end="", flush=True)

Chamada de ferramentas

GLM-5.1 suporta chamada de ferramentas: a capacidade de solicitar a execução de funções no meio da conversa. Este é o mecanismo central para fluxos de trabalho de agente onde o modelo precisa executar código, pesquisar bancos de dados, chamar APIs externas ou realizar ações no mundo real.

Definindo ferramentas

import os
import json
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "run_python",
            "description": "Executa código Python e retorna a saída. Use isso para testar, perfilar ou benchmarkar código.",
            "parameters": {
                "type": "object",
                "properties": {
                    "code": {
                        "type": "string",
                        "description": "O código Python a ser executado"
                    }
                },
                "required": ["code"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Lê o conteúdo de um arquivo",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "description": "Caminho do arquivo a ser lido"
                    }
                },
                "required": ["path"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="glm-5.1",
    messages=[
        {
            "role": "user",
            "content": "Escreva uma função para calcular números de Fibonacci, teste-a para n=10 e me mostre a saída."
        }
    ],
    tools=tools,
    tool_choice="auto"
)

message = response.choices[0].message
print(f"Motivo do término: {response.choices[0].finish_reason}")

if message.tool_calls:
    for tool_call in message.tool_calls:
        print(f"\nFerramenta chamada: {tool_call.function.name}")
        print(f"Argumentos: {tool_call.function.arguments}")

Lidando com respostas de chamada de ferramentas

Quando o GLM-5.1 solicita uma chamada de ferramenta, você executa a função e então retorna o resultado na próxima mensagem:

import subprocess

def execute_tool(tool_call):
    """Executa a ferramenta e retorna o resultado."""
    name = tool_call.function.name
    args = json.loads(tool_call.function.arguments)

    if name == "run_python":
        result = subprocess.run(
            ["python3", "-c", args["code"]],
            capture_output=True,
            text=True,
            timeout=10
        )
        return result.stdout or result.stderr

    elif name == "read_file":
        try:
            with open(args["path"]) as f:
                return f.read()
        except FileNotFoundError:
            return f"Erro: arquivo {args['path']} não encontrado"

    return f"Ferramenta desconhecida: {name}"


def run_agent_loop(user_message, tools, max_iterations=20):
    """Executa um ciclo completo do agente com chamada de ferramentas."""
    messages = [{"role": "user", "content": user_message}]

    for i in range(max_iterations):
        response = client.chat.completions.create(
            model="glm-5.1",
            messages=messages,
            tools=tools,
            tool_choice="auto",
            max_tokens=4096
        )

        message = response.choices[0].message
        messages.append(message.model_dump())

        if response.choices[0].finish_reason == "stop":
            # O Modelo terminou
            return message.content

        if response.choices[0].finish_reason == "tool_calls":
            # Executa cada chamada de ferramenta e adiciona os resultados
            for tool_call in message.tool_calls:
                tool_result = execute_tool(tool_call)
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": tool_result
                })

    return "Máximo de iterações atingido"


result = run_agent_loop(
    "Escreva uma implementação de quicksort, teste-a com uma lista aleatória de 1000 inteiros e reporte o tempo.",
    tools
)
print(result)

Este padrão se adapta diretamente à força do GLM-5.1 como um modelo de agente. Você permite que o modelo decida quando chamar ferramentas, processar os resultados e continuar até atingir uma solução ou decidir que terminou.

Parâmetros chave

Configurações recomendadas para tarefas de codificação:

{
    "model": "glm-5.1",
    "temperature": 1.0,
    "top_p": 0.95,
    "max_tokens": 163840  # contexto completo para execuções de agente longas
}

A Z.AI usa essas configurações em suas próprias avaliações de benchmark. Para geração de código determinística, reduza a temperatura para 0.2-0.4.

Usando GLM-5.1 com assistentes de codificação

O Plano de Codificação Z.AI permite que você roteie Claude Code, Cline, Kilo Code e outros assistentes de codificação de IA através do GLM-5.1 via API BigModel. Isso é útil se você deseja um modelo de codificação forte com custo menor do que rodar Claude Opus ou GPT-5.4 diretamente.

Configuração do Claude Code

No seu arquivo de configuração do Claude Code (~/.claude/settings.json ou equivalente):

{
  "model": "glm-5.1",
  "baseURL": "https://open.bigmodel.cn/api/paas/v4/",
  "apiKey": "sua_chave_api_bigmodel"
}

Configuração do Cline / Roo Code

Nas suas configurações do VS Code ou na configuração da extensão Cline:

{
  "cline.apiProvider": "openai",
  "cline.openAIBaseURL": "https://open.bigmodel.cn/api/paas/v4/",
  "cline.openAIApiKey": "sua_chave_api_bigmodel",
  "cline.openAIModelId": "glm-5.1"
}

Consumo de cota

O GLM-5.1 usa o sistema de cotas Z.AI em vez de faturamento por token: - Horários de pico (14:00-18:00 UTC+8): 3x cota por requisição - Fora de pico: 2x cota por requisição - Tarifa promocional até abril de 2026: 1x durante o fora de pico

Para cargas de trabalho de agente intensivas, agende tarefas de longa duração para horários fora de pico. Uma execução de otimização de 600 iterações, como a demonstrada pela Z.AI, custa significativamente mais cota no pico.

Testando a API GLM-5.1 com Apidog

Testar uma integração de API de agente requer lidar corretamente com múltiplos tipos de resposta: completições normais, chunks de streaming, requisições de chamada de ferramenta, mensagens de resultado de ferramenta e estados de erro. Testar tudo isso contra a API real consome cota e exige uma conexão ao vivo.

O Smart Mock do Apidog permite que você defina todos esses estados de resposta e os teste sem acessar a API real.

Configurando o endpoint mock

1. No Apidog, crie um novo endpoint: POST https://open.bigmodel.cn/api/paas/v4/chat/completions
2. Adicione uma Expectativa de Mock para uma resposta de sucesso padrão:

{
  "id": "chatcmpl-test123",
  "object": "chat.completion",
  "created": 1744000000,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "def sieve(n): ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 120,
    "total_tokens": 152
  }
}

1. Adicione uma segunda expectativa para uma resposta de chamada de ferramenta:

{
  "id": "chatcmpl-tool456",
  "object": "chat.completion",
  "created": 1744000001,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc",
            "type": "function",
            "function": {
              "name": "run_python",
              "arguments": "{\"code\": \"print(2+2)\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 35,
    "total_tokens": 83
  }
}

1. Adicione uma resposta de limite de taxa (HTTP 429):

{
  "error": {
    "message": "Limite de taxa excedido. Por favor, tente novamente após 60 segundos.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Testando o ciclo completo do agente

Use os Cenários de Teste do Apidog para encadear múltiplas requisições. Para um teste de ciclo de agente:

1. Passo 1: POST para /chat/completions com sua mensagem inicial, afirme 200 e finish_reason == "tool_calls"
2. Passo 2: POST novamente com o resultado da ferramenta na matriz de mensagens, afirme 200 e finish_reason == "stop"
3. Passo 3: Extraia o conteúdo final e afirme que ele contém o código esperado

Isso testa o ciclo completo do agente sem gastar nenhuma cota. Você também pode testar o tratamento de erros mudando o mock para retornar 429, e então verificar se sua lógica de retentativa é ativada corretamente.

Para fluxos de trabalho de agente com múltiplos passos, os Cenários de Teste do Apidog permitem passar dados entre os passos usando variáveis, de modo que os valores de request_id ou tool_call_id do passo 1 fluam automaticamente para o passo 2. Isso espelha como um ciclo de agente real funciona e detecta bugs de integração antes da produção.

Tratamento de erros

A API retorna códigos de status HTTP padrão:

import time
import requests

def call_with_retry(payload, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                "https://open.bigmodel.cn/api/paas/v4/chat/completions",
                headers={"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}",
                         "Content-Type": "application/json"},
                json=payload,
                timeout=120
            )

            if response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", 60))
                print(f"Limite de taxa atingido. Aguardando {retry_after}s...")
                time.sleep(retry_after)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.Timeout:
            wait = 2 ** attempt
            print(f"Timeout na tentativa {attempt + 1}. Tentando novamente em {wait}s...")
            time.sleep(wait)

    raise Exception("Máximo de tentativas excedido")

Para execuções de agente longas, onde passos individuais podem levar 30-60 segundos, sempre defina um timeout generoso (120-300 segundos). O modelo pode precisar de tempo para gerar um arquivo de código completo ou analisar um resultado de benchmark complexo.

Conclusão

A API compatível com OpenAI do GLM-5.1 significa que você pode integrá-lo em minutos se já trabalhou com GPT ou Claude. A principal diferença é o endpoint (open.bigmodel.cn) e o sistema de cota em vez do faturamento por token.

Para aplicações de agente onde o modelo executa centenas de chamadas de ferramentas em uma sessão longa, a capacidade de otimização de longo prazo do GLM-5.1 é uma verdadeira vantagem. Combine-o com testes adequados via Smart Mock e Cenários de Teste do Apidog para garantir que sua integração lide com todos os casos extremos antes de rodar sem supervisão.

Para obter informações sobre o que é o GLM-5.1 e como seus benchmarks se comparam, consulte a visão geral do modelo GLM-5.1. Para saber mais sobre a construção e o teste de fluxos de trabalho de agente de IA com Apidog, consulte como funciona a memória de agente de IA.

FAQ

A API GLM-5.1 é compatível com OpenAI?Sim. O formato da requisição, a estrutura da resposta, o protocolo de streaming e o formato de chamada de ferramentas são todos idênticos à API de completions de chat da OpenAI. Você pode usar o SDK oficial do OpenAI para Python ou qualquer cliente compatível com OpenAI definindo a URL base para https://open.bigmodel.cn/api/paas/v4/.

Qual é o nome do modelo a ser usado nas requisições da API?Use "glm-5.1" como o nome do modelo. Não use um nome versionado completo; apenas glm-5.1 funciona.

Como funciona o preço da API GLM-5.1?A API BigModel usa um sistema de cota. O GLM-5.1 consome 3x a cota durante os horários de pico (14:00-18:00 UTC+8) e 2x durante o período fora de pico. Até o final de abril de 2026, o uso fora de pico é cobrado com 1x a cota como uma tarifa promocional.

Qual é o comprimento máximo do contexto?Contexto de entrada de 200.000 tokens. A saída máxima é de 163.840 tokens. Para execuções de agente longas, defina max_tokens para um valor grande (32.768 ou superior) para evitar truncar a saída do modelo no meio da tarefa.

Posso usar GLM-5.1 para chamada de funções / uso de ferramentas?Sim. O GLM-5.1 suporta o mesmo formato de chamada de ferramentas que a API da OpenAI. Defina ferramentas com um esquema type: "function", passe-as na matriz tools e lide com as respostas finish_reason: "tool_calls" em seu ciclo de agente.

Como posso testar as chamadas da API GLM-5.1 sem gastar cota?Use o Smart Mock do Apidog para definir respostas mock para cada estado da API: sucesso, chamadas de ferramentas, limites de taxa, erros. Execute sua suíte de testes contra o mock durante o desenvolvimento e use a API real apenas para validação final.

Onde posso encontrar os pesos do modelo GLM-5.1?Os pesos de código aberto estão no HuggingFace em zai-org/GLM-5.1. Eles são lançados sob a Licença MIT e suportam vLLM e SGLang para inferência local.