Como Usar a API GLM-5.3-Flash (Com Entrada de Imagem)

Como usar o GLM-5.3-Flash pela API compatível com OpenAI

O GLM-5.3-Flash é compatível com OpenAI. O caminho mais rápido para fazer uma chamada funcional é apontar um cliente existente para outra URL base e alterar uma única string. A novidade principal é a entrada de imagem: este é o primeiro modelo GLM-5 que aceita imagens na mesma requisição que o texto, mas o formato do payload ainda confunde muitas pessoas.

Experimente o Apidog hoje

Este guia mostra como obter uma chave, fazer chamadas de texto, enviar imagens, controlar o esforço de raciocínio, usar streaming e chamar ferramentas. Todos os exemplos usam o ID de modelo glm-5.3-flash.

Para entender o modelo antes de configurá-lo, leia o explicador do GLM-5.3-Flash. Se você já usa o irmão maior, consulte o guia da API GLM-5.3. As diferenças são reais: ID e preço diferentes, além de um caminho nativo para imagens que o GLM-5.3 não possui.

Obtenha uma chave de API

Crie uma conta na z.ai, abra a seção de chaves de API no painel e gere uma chave. Armazene-a no ambiente, não no código-fonte:

export ZAI_API_KEY="your-key-here"

A URL base da API padrão é:

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

Existe uma URL base separada para os endpoints do plano de codificação. Isso é importante ao configurar o Claude Code ou o Cline, em vez de chamar a API diretamente. Consulte o guia de Claude Code e Cline.

Faça sua primeira chamada

Como o endpoint é compatível com OpenAI, o SDK oficial funciona sem modificações:

from openai import OpenAI
import os

client = OpenAI(
    [REDACTED CREDENTIAL],
    base_url="https://api.z.ai/api/paas/v4/",
)

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {"role": "user", "content": "Explain what a KV cache is in two sentences."}
    ],
)

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

A mesma chamada usando curl:

curl https://api.z.ai/api/paas/v4/chat/completions \
  -H "[REDACTED CREDENTIAL] $ZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "messages": [
      {"role": "user", "content": "Explain what a KV cache is in two sentences."}
    ]
  }'

E em Node.js:

import OpenAI from "openai";

const client = new OpenAI({
  [REDACTED CREDENTIAL],
  baseURL: "https://api.z.ai/api/paas/v4/",
});

const response = await client.chat.completions.create({
  model: "glm-5.3-flash",
  messages: [
    { role: "user", content: "Explain what a KV cache is in two sentences." },
  ],
});

console.log(response.choices[0].message.content);

Nada aqui é específico do GLM, exceto a URL base e a string do modelo. Essa é a vantagem de uma superfície compatível com OpenAI: trocar de modelo exige pouco esforço e facilita testar o desempenho na sua própria carga de trabalho.

Envie imagens

A entrada de imagem funciona com blocos de conteúdo. Em vez de content ser uma string, ele se torna um array de blocos tipados:

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "This screenshot shows a rendering bug. What is wrong with the layout?",
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/screenshots/broken-layout.png"
                    },
                },
            ],
        }
    ],
)

Três regras são importantes:

1. Use uma URL pública ou uma URL base64

Se a imagem for local ou privada, codifique-a como base64:

import base64

with open("broken-layout.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

image_block = {
    "type": "image_url",
    "image_url": {"url": f"data:image/png;base64,{encoded}"},
}

2. Envie cada imagem em um bloco separado

Não existe um atalho com um array de URLs. Para comparar um design com sua implementação, envie dois blocos image_url no mesmo array:

content = [
    {"type": "text", "text": "Does the second image match the design in the first?"},
    {"type": "image_url", "image_url": {"url": design_data_url}},
    {"type": "image_url", "image_url": {"url": built_data_url}},
]

3. Preserve a ordem do conteúdo

O modelo lê o array em sequência. Coloque a instrução antes das imagens às quais ela se refere. “Compare estas duas imagens”, seguido das duas imagens, tende a ser mais claro do que enviar as imagens antes da pergunta.

A documentação da Z.ai também lista entrada de vídeo e arquivo usando o mesmo mecanismo de blocos. O vídeo é mais recente e menos utilizado na prática, portanto valide-o com sua própria mídia antes de criar um recurso baseado nele.

Para fluxos de captura de tela para código e uso de imagens junto a documentos longos na mesma janela de 1 milhão de tokens, consulte o guia de visão do GLM-5.3-Flash.

Controle o esforço de raciocínio

O GLM-5.3-Flash oferece três modos por meio de reasoning_effort:

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Refactor this function for clarity."}],
    extra_body={"reasoning_effort": "low"},
)

Os valores aceitos são:

• low
• high
• max

O padrão é max, que também é o modo mais caro. Para classificação ou extração em alto volume, quando a resposta não exige muita deliberação, defina explicitamente low para reduzir a quantidade de tokens de saída.

Essa é uma mudança em relação ao GLM-5.2, que oferecia apenas high e max. O nível low é novo e pode ser o parâmetro mais útil para trabalhos em lote sensíveis a custo.

Ao usar o SDK Python da OpenAI, reasoning_effort deve ser enviado em extra_body, pois não faz parte do esquema padrão da OpenAI. Em curl, ele é um campo de nível superior.

Parâmetros de amostragem recomendados

A Z.ai publica configurações diferentes conforme o caso de uso:

Caso de uso	temperature	top_p
Geral	1.0	0.95
Codificação	0.95	1.0

A diferença costuma ser marginal, mas, se o código gerado estiver inconsistente, experimente primeiro o perfil de codificação.

Use streaming

As semânticas de streaming da OpenAI se aplicam normalmente:

stream = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Write a bash script that rotates logs."}],
    stream=True,
)

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

Segundo a Artificial Analysis, o GLM-5.3-Flash gera aproximadamente 49 tokens por segundo, abaixo dos cerca de 86 tokens por segundo do GLM-5.3. O tempo até o primeiro token é bom: aproximadamente 1,52 segundo. Isso significa que a resposta começa rapidamente, mas continua em uma velocidade constante, não instantânea.

Esse perfil funciona bem para interfaces de usuário. Para gerar documentos longos em trabalhos em lote, planeje o tempo de execução.

Faça chamadas de ferramentas

As ferramentas usam o esquema padrão da OpenAI:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_deployment_status",
            "description": "Returns the current status of a named deployment.",
            "parameters": {
                "type": "object",
                "properties": {
                    "service": {
                        "type": "string",
                        "description": "The service name, for example 'checkout-api'.",
                    }
                },
                "required": ["service"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Is checkout-api healthy?"}],
    tools=tools,
)

call = response.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)

Os benchmarks agênticos publicados pela Z.ai no lançamento dependem bastante do uso de ferramentas: o AutomationBench marcou 48,8, contra 26,2 do GLM-5.2. São números do fornecedor, mas a direção é compatível com um modelo ajustado para loops de chamadas de ferramentas, e não apenas para conversas de turno único.

Se você gera definições de ferramentas a partir de uma API existente, o artigo sobre transformar uma especificação OpenAPI em ferramentas de agente mostra como fazer isso sem escrever os esquemas manualmente.

Implemente tratamento de erros

Três falhas representam a maior parte dos problemas de produção nesse endpoint.

Limites de taxa

Use novas tentativas com backoff exponencial e jitter. Um intervalo fixo em vários workers sincroniza as tentativas e pode transformar um limite temporário em um problema prolongado:

import time, random
from openai import RateLimitError

def call_with_retry(**kwargs):
    for attempt in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            if attempt == 4:
                raise
            time.sleep((2 ** attempt) + random.random())

Estouro de contexto

A janela de 1 milhão de tokens é grande, mas um documento extenso combinado com imagens de alta resolução ainda pode ultrapassá-la. Imagens também consomem contexto, e o erro aparece no momento da requisição, não quando o prompt é montado.

Monitore o orçamento de tokens de entrada.

Saída truncada

Se a resposta terminar no meio de uma frase, verifique finish_reason:

print(response.choices[0].finish_reason)

O valor length indica que o limite de saída foi atingido; não significa que o modelo desistiu. Como as fontes divergem sobre o limite máximo de saída, verifique esse campo explicitamente.

Leia o uso de tokens

Cada resposta contém um objeto usage, que é a fonte mais confiável para calcular o custo real:

print(response.usage.prompt_tokens, response.usage.completion_tokens)

Observe especialmente completion_tokens. Com reasoning_effort no padrão max, os tokens de raciocínio são cobrados como saída. Assim, uma resposta visível curta ainda pode ter uma contagem de conclusão alta.

Compare essa métrica em diferentes níveis de esforço usando seus próprios prompts para decidir qual configuração atende ao caso de uso.

Quanto custa?

O preço de tabela é:

• US$ 0,15 por milhão de tokens de entrada;
• US$ 0,50 por milhão de tokens de saída;
• US$ 0,03 por milhão de tokens de entrada em cache.

Um desconto de lançamento de 50% vai até 9 de setembro de 2026, reduzindo os valores para US$ 0,075, US$ 0,25 e US$ 0,015, respectivamente.

Os preços variam entre os revendedores. OpenRouter, Cloudflare Workers AI, Vercel AI Gateway, DeepInfra e outros oferecem o modelo com suas próprias tarifas. Consulte a análise de preços e confirme os valores com o provedor que você pretende usar antes de definir o orçamento.

Teste a integração com o Apidog

Há duas partes dessa API que são difíceis de verificar manualmente:

1. O payload multimodal é verboso, e escrever um bloco de imagem base64 em curl é trabalhoso.
2. Trocar de modelo pode alterar silenciosamente o formato da resposta.

No Apidog, salve as chamadas de texto, imagem e ferramenta em uma coleção. Adicione asserções aos campos de resposta que sua aplicação realmente utiliza e armazene a chave como variável de ambiente, em vez de colá-la no shell.

Quando o desconto de lançamento terminar e você precisar decidir entre permanecer no Flash ou migrar para o GLM-5.3, altere o ID do modelo em um único lugar e execute a mesma suíte contra os dois modelos.

Assim, a migração vira uma diferença mensurável, não uma aposta.

FAQ

Qual é o ID exato do modelo?

Na API da Z.ai, use glm-5.3-flash. No OpenRouter, o ID é z-ai/glm-5.3-flash.

O SDK da OpenAI funciona sem alterações?

Sim, para conclusões de chat, streaming e chamadas de ferramentas. Parâmetros não padrão, como reasoning_effort, precisam ser enviados em extra_body no SDK Python.

Quantas imagens posso enviar em uma requisição?

Você pode enviar múltiplas imagens, cada uma em seu próprio bloco image_url. Os limites práticos dependem do orçamento de contexto, não de uma quantidade fixa de imagens.

Por que minhas respostas estão prolixas e lentas?

reasoning_effort usa max por padrão. Para tarefas que não exigem muita deliberação, defina-o como low.

Qual é o comprimento máximo da saída?

As fontes divergem: o OpenRouter lista 131.072 tokens, enquanto o cartão do Hugging Face indica 163.840. Verifique o limite com o provedor antes de depender de gerações muito longas.