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 cobre autenticação, primeira requisição, streaming, chamada de ferramentas e teste de integração com o Apidog.

Experimente o Apidog hoje

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: a API é compatível com OpenAI. Se você já usa GPT-4 ou Claude, basta mudar a URL base e o nome do modelo para usar o GLM-5.1. Sem SDK ou novo formato de resposta.

💡 Dica: Testar APIs de agente é difícil porque modelos podem executar centenas de chamadas de ferramentas em minutos, o que consome muita cota. Os Cenários de Teste do Apidog resolvem isso: defina a sequência completa de requisições, simule as respostas e valide sua integração (streaming, chamadas de ferramenta, erros) antes de ir para produção.

Pré-requisitos

Antes de começar, garanta que você tenha:

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

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

export BIGMODEL_API_KEY="sua_chave_api_aqui"

Nunca deixe chaves de API hardcoded no código.

Autenticação

Cada requisição deve incluir:

Authorization: Bearer SUA_CHAVE_API

A chave BigModel tem formato xxxxxxxx.xxxxxxxxxxxxxxxx. Use normalmente 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)

A API é compatível com OpenAI, então use o SDK oficial com URL base customizada:

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)

O SDK gerencia retentativas, timeout e parsing de resposta. Basta apontar a base URL.

Formato da resposta

A resposta segue o padrão 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 via result["choices"][0]["message"]["content"].

O campo usage mostra o consumo de tokens. Monitore para não ultrapassar cotas, pois GLM-5.1 cobra 3x durante o pico (14:00-18:00 UTC+8).

Streaming de respostas

Para tarefas longas, ative o streaming para receber tokens conforme são gerados:

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 streaming

Cada "chunk" traz apenas o delta de novos tokens. O chunk final terá finish_reason como "stop" ou "length".

Streaming com requests diretas

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 funções ("tools") no meio da conversa. Útil para agentes que executam código, acessam bancos de dados ou chamam APIs externas.

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

Execute a função solicitada e retorne o resultado para o modelo continuar:

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":
            return message.content

        if response.choices[0].finish_reason == "tool_calls":
            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)

Esse padrão permite que o modelo decida quando usar ferramentas e continue até finalizar a tarefa.

Parâmetros chave

Parâmetro	Tipo	Padrão	Descrição
model	string	obrigatório	Use "glm-5.1"
messages	array	obrigatório	Histórico da conversa
max_tokens	integer	1024	Máximo de tokens para gerar (até 163.840)
temperature	float	0.95	Aleatoriedade. Menor = determinístico. Intervalo: 0.0-1.0
top_p	float	0.7	Amostragem de núcleo. Z.AI recomenda 0.7 para codificação.
stream	boolean	false	Habilita streaming de respostas
tools	array	null	Definições de funções para chamada de ferramentas
tool_choice	string/object	"auto"	"auto", "none", ou ferramenta específica
stop	string/array	null	Sequências de parada personalizadas

Configuração recomendada para tarefas de codificação:

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

Para geração determinística, use temperature: 0.2-0.4.

Usando GLM-5.1 com assistentes de codificação

O Plano de Codificação Z.AI permite rotear Claude Code, Cline, Kilo Code e outros via GLM-5.1. Útil para economizar cota em modelos premium.

Configuração do Claude Code

Em ~/.claude/settings.json:

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

Configuração do Cline / Roo Code

No VS Code ou config da extensão:

{
  "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

• Pico (14:00-18:00 UTC+8): 3x cota por requisição
• Fora de pico: 2x cota
• Promoção até abril de 2026: 1x fora de pico

Para execuções longas, agende fora do pico!

Testando a API GLM-5.1 com Apidog

Testes de API de agente devem cobrir: respostas normais, streaming, chamadas de ferramenta, mensagens de resultado e erros. Testar direto na API consome cota e exige conexão.

O Smart Mock do Apidog permite simular todos esses estados localmente.

Configurando o endpoint mock

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

{
  "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 mock para 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 mock para 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 Cenários de Teste do Apidog para simular múltiplos passos:

1. Passo 1: POST para /chat/completions com mensagem inicial, afirme 200 e finish_reason == "tool_calls"
2. Passo 2: POST novamente com o resultado da ferramenta, afirme 200 e finish_reason == "stop"
3. Passo 3: Extraia o conteúdo final e valide o código retornado

Teste sem gastar cota real! Para erros, faça o mock retornar 429 e valide se sua lógica de retry funciona.

Em fluxos de múltiplos passos, use variáveis do Apidog para passar IDs entre requisições, simulando um ciclo de agente real.

Tratamento de erros

A API retorna HTTP status convencionais:

Status	Significado	Ação
200	Sucesso	Processar normalmente
400	Requisição inválida	Verifique o formato
401	Não autorizado	Verifique a chave de API
429	Limite de taxa	Aguarde o valor do cabeçalho Retry-After
500	Erro do servidor	Backoff exponencial e tente novamente
503	Serviço indisponível	Backoff exponencial e tente novamente

Exemplo de retry em Python:

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 longas, defina timeout generoso (120-300s).

Conclusão

A API GLM-5.1 é plug-and-play para quem já usa OpenAI: só muda o endpoint (open.bigmodel.cn) e o sistema de cota. Em aplicações de agente, a capacidade do GLM-5.1 de otimizar em sessões longas é diferencial. Use Smart Mock e Cenários de Teste do Apidog para garantir robustez antes do deploy.

Para detalhes sobre o GLM-5.1 e benchmarks, veja a visão geral do modelo GLM-5.1. Para saber mais sobre desenvolvimento e teste de agentes IA, confira como funciona a memória de agente de IA.

FAQ

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

Sim. Formato de requisição, resposta, streaming e chamada de ferramentas idênticos à API OpenAI. Use qualquer cliente OpenAI definindo a base URL para https://open.bigmodel.cn/api/paas/v4/.

Qual nome de modelo usar?

"glm-5.1". Não use versões completas.

Como funciona o preço?

Sistema de cota: 3x no pico (14:00-18:00 UTC+8), 2x fora do pico. Até abril/2026, 1x fora do pico.

Qual o contexto máximo?

Entrada: 200.000 tokens. Saída: até 163.840 tokens. Para execuções longas, use max_tokens grande (32.768+).

GLM-5.1 suporta chamada de função?

Sim. Mesmo formato da OpenAI. Defina tools, use "tool_calls" no ciclo.

Como testar sem gastar cota?

Use o Smart Mock do Apidog para simular todos os estados da API e valide sua lógica antes de usar a API real.

Onde baixar os pesos do modelo?

No HuggingFace: zai-org/GLM-5.1 (Licença MIT, suporta vLLM e SGLang para inferência local).