GLM-5.3-Flash é compatível com OpenAI, o que significa que o caminho mais rápido para uma chamada funcional é apontar um cliente que você já possui para uma URL base diferente e mudar uma única string. A parte realmente nova é a entrada de imagem: este é o primeiro modelo GLM-5 que aceita imagens na mesma requisição que seu texto, e o formato do payload confunde as pessoas.
Este guia abrange como obter uma chave, fazer uma chamada de texto, enviar imagens, controlar o esforço de raciocínio, streaming e chamada de ferramentas. Todos os exemplos usam o ID do modelo glm-5.3-flash.
Se você deseja o contexto sobre o que é este modelo antes de configurá-lo, comece com nosso explicador do GLM-5.3-Flash. Se você já está executando o irmão maior, o guia da API GLM-5.3 cobre esse modelo, e as diferenças abaixo são reais: ID de modelo diferente, tabela de preços diferente e um caminho de imagem que o GLM-5.3 não possui nativamente.
Obtenha uma chave de API
Crie uma conta em z.ai, abra a seção de chaves de API do painel e gere uma chave. Coloque-a em seu ambiente, e não em seu código-fonte:
export ZAI_API_KEY="your-key-here"
A URL base para a API padrão é:
https://api.z.ai/api/paas/v4/
Existe uma URL base separada usada pelos endpoints do plano de codificação, o que é importante se você estiver configurando o Claude Code ou Cline em vez de chamar a API diretamente. Essa configuração é abordada em nosso guia Claude Code e Cline.
Sua primeira chamada
Como o endpoint é compatível com OpenAI, o SDK oficial do OpenAI funciona sem modificações:
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["ZAI_API_KEY"],
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 coisa em curl:
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.3-flash",
"messages": [
{"role": "user", "content": "Explain what a KV cache is in two sentences."}
]
}'
E em Node:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.ZAI_API_KEY,
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. Esse é o objetivo de uma superfície compatível com OpenAI, e é por isso que trocar modelos é barato o suficiente para valer a pena testar em sua própria carga de trabalho.
Enviando imagens
Esta é a seção que não existe para o GLM-5.3. A entrada de imagem funciona através de blocos de conteúdo: em vez de content ser uma string simples, 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 governam este payload:
O campo URL aceita tanto uma URL pública quanto uma URL de dados base64. Se sua imagem for local ou privada, codifique-a:
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}"},
}
Múltiplas imagens significam múltiplos blocos. Não há atalho de array de URLs. Para comparar um design com sua implementação, envie dois blocos image_url no mesmo array de conteúdo:
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}},
]
A ordem tem significado. O modelo lê o array de conteúdo em sequência, então coloque o texto que define a tarefa antes das imagens às quais ele se refere. “Compare estes dois” seguido por duas imagens é lido melhor do que duas imagens seguidas por uma pergunta.
A documentação da Z.ai também lista entrada de vídeo e arquivo usando o mesmo mecanismo de bloco de conteúdo. O vídeo é mais recente e muito menos utilizado na prática do que a entrada de imagem, então valide-o com sua própria mídia antes de construir um recurso com ele.
Para um tratamento mais aprofundado do lado da visão, incluindo fluxos de trabalho de captura de tela para código e colocação de imagens junto a um documento longo na mesma janela de 1M tokens, consulte nosso guia de visão do GLM-5.3-Flash.
Controlando o esforço de raciocínio
GLM-5.3-Flash expõe três modos de pensamento através 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 e max. O padrão é max, o que vale a pena saber porque é o mais caro. Se você estiver executando classificação ou extração de alto volume onde a resposta não precisa de deliberação, definir explicitamente low reduzirá substancialmente a contagem de tokens de saída.
Esta é uma mudança em relação ao GLM-5.2, que expunha apenas High e Max. O nível low é novo e, para trabalhos em lote sensíveis ao custo, é provavelmente o parâmetro mais útil do modelo.
Observe que reasoning_effort vai em extra_body ao usar o SDK Python da OpenAI, porque não faz parte do esquema padrão da OpenAI. Em curl puro, é apenas um campo de nível superior.
Parâmetros de amostragem recomendados
A Z.ai publica padrões diferentes dependendo do que você está fazendo:
| Caso de uso | temperatura | top_p |
|---|---|---|
| Geral | 1.0 | 0.95 |
| Codificação | 0.95 | 1.0 |
Estes são próximos o suficiente para que a diferença seja marginal para a maioria das aplicações, mas se você estiver obtendo saída de código inconsistente, o perfil de codificação é o que deve ser tentado.
Streaming
Semânticas de streaming padrão da OpenAI se aplicam:
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)
Defina as expectativas aqui. O GLM-5.3-Flash gera aproximadamente 49 tokens por segundo de acordo com a Artificial Analysis, o que é mais lento que seu irmão maior, o GLM-5.3, com cerca de 86. O tempo para o primeiro token é bom, em 1,52 segundos, então a resposta começa rapidamente e depois chega de forma constante, e não rapidamente. Se você estiver fazendo streaming para uma interface de usuário, esse perfil está bom. Se você estiver gerando documentos longos em um trabalho em lote, planeje para isso.
Chamada 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 que a Z.ai publicou no lançamento dependem fortemente do uso de ferramentas, com AutomationBench em 48.8 contra 26.2 do GLM-5.2. Esses são números do fornecedor, mas a direção é consistente com o modelo sendo ajustado para loops de chamada de ferramentas em vez de conversas de turno único.
Se você estiver gerando definições de ferramentas a partir de uma API que já possui, nossa postagem sobre transformar uma especificação OpenAPI em ferramentas de agente aborda como fazer isso sem escrever esquemas manualmente.
Tratamento de erros que vale a pena implementar
Três modos de falha são responsáveis pela maioria dos problemas de produção neste endpoint.
Limites de taxa. Tente novamente com backoff exponencial e jitter. Um intervalo de nova tentativa fixo em muitos workers produz novas tentativas sincronizadas, que é a maneira clássica de transformar um limite breve em um duradouro.
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. Uma janela de 1M tokens é grande o suficiente para que as pessoas parem de contar, e então um documento longo mais algumas imagens de alta resolução a ultrapassam. As imagens consomem contexto, e o erro chega no momento da requisição, e não quando você monta o prompt. Monitore seu orçamento de tokens na entrada.
Saída truncada. Se uma resposta parar no meio da frase, verifique o finish_reason na escolha. Um valor de length significa que você atingiu o limite de saída, não que o modelo desistiu. Dado que o valor máximo de saída é contestado entre as fontes, vale a pena verificar isso explicitamente em vez de assumir.
Lendo o uso de tokens
Cada resposta contém um objeto usage, e é a única fonte confiável para o custo real de uma chamada:
print(response.usage.prompt_tokens, response.usage.completion_tokens)
Preste atenção especial à contagem de conclusão. Com reasoning_effort no seu padrão max, os tokens de raciocínio são cobrados como saída, então uma resposta visível curta pode ter uma grande contagem de conclusão por trás dela. Comparar esse número em diferentes níveis de esforço em seus próprios prompts é a maneira mais rápida de decidir qual configuração você realmente precisa.
Quanto custa
O preço de tabela é de $0.15 por milhão de tokens de entrada, $0.50 por milhão de tokens de saída e $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 esses valores para $0.075, $0.25 e $0.015.
Os preços diferem entre os revendedores. OpenRouter, Cloudflare Workers AI, Vercel AI Gateway, DeepInfra e outros todos oferecem o modelo com suas próprias taxas. Nossa análise de preços detalha o cálculo de custos e o que muda quando o desconto expira. Verifique qualquer valor com o provedor que você realmente usa antes de fazer o orçamento.
Testando a integração
Duas coisas sobre esta API são irritantes de verificar manualmente. O payload multimodal é verboso, então um bloco de imagem base64 em um comando curl é desagradável de escrever e pior de executar novamente. E as trocas de modelo são exatamente o tipo de mudança que altera silenciosamente o formato da resposta.
O Apidog lida com ambos. Salve a chamada de texto, a chamada de imagem e a chamada de ferramenta como uma coleção, anexe asserções aos campos de resposta que sua aplicação realmente lê e armazene a chave de API como uma variável de ambiente em vez de colá-la em um shell. Quando o desconto de lançamento terminar e você estiver decidindo se permanece no Flash ou muda para o GLM-5.3, você pode alternar o ID do modelo em um só lugar e executar novamente a suíte contra ambos.
Isso transforma uma migração de modelo em uma diferença que você pode analisar, em vez de algo que você espera que funcione.
FAQ
Qual é o ID exato do modelo? glm-5.3-flash na API da Z.ai. No OpenRouter é z-ai/glm-5.3-flash.
O SDK da OpenAI realmente funciona sem alterações? Sim, para conclusões de chat, streaming e chamada de ferramentas. Parâmetros não padrão como reasoning_effort precisam de extra_body no SDK Python.
Quantas imagens posso enviar em uma única requisição? Múltiplas, cada uma como seu próprio bloco image_url. Os limites práticos vêm do seu orçamento de contexto, e não de uma contagem fixa.
Por que minhas respostas são tão prolixas e lentas? reasoning_effort tem como padrão max. Defina-o como low para trabalhos que não exigem deliberação.
Qual é o comprimento máximo da saída? As fontes divergem: OpenRouter lista 131.072 tokens e o cartão Hugging Face indica 163.840. Verifique com seu provedor antes de depender de gerações muito longas.