A maioria dos modelos de visão pede que você escolha. Você pode enviar uma imagem, ou pode enviar muito texto, mas o modelo que faz bem um raramente faz bem o outro.
GLM-5.3-Flash não te obriga a escolher. Ele aceita imagens como blocos de conteúdo dentro de uma janela de contexto de 1.048.576 tokens, na mesma solicitação que todo o resto. Essa combinação, entrada de imagem nativa mais um milhão de tokens de espaço, abre fluxos de trabalho que nenhuma das capacidades habilita por si só.
Este guia aborda o payload, os fluxos de trabalho que valem a pena construir e as partes que ainda não foram comprovadas.
Nativo, não baseado em adaptadores
Os trabalhos anteriores de visão da Z.ai eram enviados como modelos separados. GLM-5V-Turbo e GLM-4.6V eram endpoints distintos com IDs de modelo distintos, e usá-los significava rotear o tráfego de imagens para um lugar diferente do tráfego de texto. O GLM-5.3, o irmão maior deste modelo, roteia a visão através de adaptadores em vez de tratá-la nativamente.
GLM-5.3-Flash é o primeiro modelo da série GLM-5 onde as imagens são uma entrada de primeira classe para o mesmo modelo, na mesma chamada, compartilhando o mesmo contexto.
Na prática, isso significa um ID de modelo, uma linha de cobrança, um conjunto de limites de taxa e, o mais importante, uma janela de contexto que contém sua imagem e seu texto ao mesmo tempo. Se você está mantendo algo no caminho antigo, nosso guia da API GLM-5V-Turbo e o guia GLM-4.6V cobrem esses modelos.
O payload
A entrada de imagem funciona através de blocos de conteúdo tipados. Em vez de content ser uma string, ele se torna um array:
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": [
{"type": "text", "text": "What is wrong with this layout on mobile?"},
{
"type": "image_url",
"image_url": {"url": "https://example.com/mobile-view.png"},
},
],
}
],
)
print(response.choices[0].message.content)
Para imagens locais ou privadas, use uma URL de dados base64:
import base64
from pathlib import Path
def image_block(path: str) -> dict:
data = base64.b64encode(Path(path).read_bytes()).decode("utf-8")
suffix = Path(path).suffix.lstrip(".").replace("jpg", "jpeg")
return {
"type": "image_url",
"image_url": {"url": f"data:image/{suffix};base64,{data}"},
}
Múltiplas imagens significam múltiplos blocos. Não há um atalho de array de URLs:
content = [
{"type": "text", "text": "Image 1 is the design. Image 2 is what we built. List the differences."},
image_block("design.png"),
image_block("built.png"),
]
A ordem importa. O modelo lê o array em sequência, então coloque o texto de enquadramento antes das imagens a que ele se refere e rotule as imagens explicitamente ao enviar várias. “A Imagem 1 é o design” dá ao modelo algo para ancorar sua resposta.
A configuração básica e a autenticação são abordadas em nosso guia da API.
Fluxos de trabalho que valem a pena construir
Depuração de capturas de tela
O óbvio, e no qual a Z.ai se apoia. Seus próprios materiais descrevem o modelo observando “interfaces, resultados de renderização e feedback de interação”, o que é um enquadramento de agente de codificação em vez de uma descrição de foto.
Envie a renderização quebrada e a fonte que a produziu na mesma solicitação:
content = [
{"type": "text", "text": "This component renders incorrectly below 400px. Here is the screenshot and the source."},
image_block("bug-mobile.png"),
{"type": "text", "text": f"```jsx\n{component_source}\n```"},
]
O modelo raciocina sobre a renderização real, e não sobre sua descrição. Isso remove a etapa mais 'perdida' na maioria das conversas de depuração de front-end, que é um humano traduzindo um problema visual em palavras.
Comparação de design
Duas imagens e uma pergunta. Útil na CI como uma verificação suave de regressões visuais, onde uma ferramenta de diff informa que pixels mudaram e um modelo informa se a mudança importa.
Seja realista quanto à confiabilidade aqui. Um modelo que compara capturas de tela é um julgamento, não uma afirmação. Use-o para triar quais diferenças um humano deve examinar, não para bloquear um deploy por si só.
Documentos junto com suas especificações
É aqui que o contexto de 1M ganha seu lugar. Coloque uma longa especificação no prompt como texto e um artefato renderizado como imagem, então pergunte se eles concordam.
content = [
{"type": "text", "text": f"Specification:\n\n{spec_text}"},
{"type": "text", "text": "Below is the generated report. Does it satisfy every requirement above? List gaps."},
image_block("generated-report.png"),
]
Uma especificação de 40 páginas e uma imagem em um único prompt não é algo que você conseguiria fazer em um modelo com uma janela de 128K e visão baseada em adaptadores. Essa é a verdadeira nova capacidade.
As notas de lançamento da Z.ai também mencionam fluxos de trabalho de documentos de escritório e pesquisa financeira como alvos para o comportamento agentivo do modelo.
Gráficos e painéis
Ler uma imagem de gráfico e retornar dados estruturados é uma tarefa de extração padrão. Peça JSON e valide-o:
content = [
{"type": "text", "text": "Extract the series in this chart as JSON: [{label, values: [...]]. Return only JSON."},
image_block("quarterly.png"),
]
Valide a saída contra um esquema em vez de confiar nela. A leitura de gráficos é exatamente o tipo de tarefa em que um modelo produz números errados com confiança, e a validação estrutural detecta erros de formato mesmo quando não consegue detectar erros de valor.
Para extração dedicada de documentos, um especialista ainda pode superar um generalista. GLM-OCR para compreensão de documentos cobre esse caminho.
Vídeo e arquivos
A documentação da Z.ai lista entrada de vídeo e arquivo junto com imagens, usando o mesmo mecanismo de bloco de conteúdo.
Tenha cuidado com isso. O suporte a vídeo neste modelo é novo, pouco documentado e pouco exercitado em público em comparação com a entrada de imagem, que muitas pessoas já testaram. O suporte do provedor também varia: uma capacidade do modelo não é o mesmo que um recurso disponível em qualquer gateway que você usa.
Se o vídeo for importante para sua aplicação, teste-o diretamente com sua própria mídia e seu próprio provedor antes de projetar em torno dele. Não trate uma linha em uma tabela de capacidades como um recurso em funcionamento.
Onde ele falha
Multimodalidade nativa não é o mesmo que multimodalidade confiável. Quatro modos de falha valem a pena conhecer antes de lançar algo.
Números confiantes de gráficos. Ler valores de uma linha plotada é a tarefa com maior probabilidade de produzir uma resposta fluente, precisamente formatada, mas errada. A validação de esquema detecta saídas malformadas; ela não pode detectar um número plausível que é simplesmente incorreto. Se os números importam, obtenha-os dos dados subjacentes, em vez de uma imagem deles.
Texto pequeno. Capturas de tela de UI densas, tabelas em capturas de baixa resolução e código em imagens compactadas se degradam. Redimensionar para economizar tokens piora isso, então há uma tensão direta entre a alavanca de custo e a precisão. Corte para a região de interesse em vez de encolher o quadro inteiro.
Precisão espacial. Modelos descrevem bem o layout e o medem mal. “O botão se sobrepõe à entrada” geralmente está certo. “O botão está 12 pixels muito à esquerda” geralmente não está.
Confusão de ordem e referência. Com várias imagens em uma única solicitação, o modelo pode atribuir um detalhe à imagem errada. Rotule-as explicitamente nos blocos de texto e mantenha a contagem baixa quando a precisão for importante.
Nenhuma dessas limitações é exclusiva do GLM-5.3-Flash. Elas são os limites padrão dos modelos de linguagem de visão, e a pontuação de 57 no Índice de Inteligência não o isenta. Projete o fluxo de trabalho para que uma resposta errada seja detectada em vez de ser executada.
Custo
Imagens consomem tokens de contexto e são cobradas como entrada. Não há sobretaxa separada para imagens.
No preço de tabela, isso é $0,15 por milhão de tokens de entrada, ou $0,075 durante o desconto de lançamento que vai até 9 de setembro de 2026. Imagens de alta resolução consomem um número significativo de tokens, então a resolução é uma alavanca de custo: diminua a escala antes de enviar, a menos que o detalhe fino seja o objetivo da solicitação.
reasoning_effort assume o valor padrão max, que cobra o raciocínio como tokens de saída. Para extração direta de uma imagem, low geralmente é a configuração correta e materialmente mais barata. Nossa análise de preços aborda ambas as alavancas.
Mantendo os custos de imagem sob controle
Imagens são cobradas como tokens de entrada, então a resolução é uma alavanca de custo direta, e a otimização óbvia combate as notas de precisão acima.
Uma ordem de operações viável:
- Corte antes de escalar. Enviar a região relevante em resolução total é melhor do que enviar a tela inteira pela metade. Você perde o contexto que o modelo não precisava e mantém os detalhes que ele precisa.
- Combine a resolução com a pergunta. “O layout está quebrado?” sobrevive a uma redução agressiva. “O que diz esta mensagem de erro?” não.
- Não reenvie imagens inalteradas. Em uma conversa com várias interações, uma imagem enviada uma vez já está em contexto. Reanexá-la a cada interação gera um custo a cada interação.
- Defina
reasoning_effortdeliberadamente. Ele assume o valor padrãomax, e o raciocínio é cobrado como saída. Extração direta raramente precisa dele.
O objeto `usage` em cada resposta fornece a contagem real de tokens por chamada, que é a única maneira de descobrir o custo real de uma imagem, em vez de adivinhar pelo seu tamanho de arquivo.
Testando chamadas multimodais
Requisições multimodais são desagradáveis de testar manualmente. Uma URL de dados base64 tem milhares de caracteres, o que torna um comando curl ilegível e efetivamente impossível de reexecutar editando. As respostas são texto de forma livre, então regressões são fáceis de perder.
Dois hábitos ajudam. Mantenha um pequeno conjunto fixo de imagens de referência e respostas esperadas, para que você possa perceber quando o comportamento muda. E valide a extração estruturada contra um esquema, em vez de apenas inspecionar visualmente.
Apidog é um lar prático para isso. Armazene os payloads de imagem em uma requisição salva em vez de um comando shell, mantenha a chave da API como uma variável de ambiente e anexe asserções ao JSON que seus prompts de extração retornam. Ao mudar de modelos ou quando um provedor atualiza algo, reexecutar o conjunto de testes informa se o caminho de visão ainda se comporta como esperado, em vez de você descobrir por meio de um usuário.
FAQ
O GLM-5.3 também suporta imagens? Não nativamente. O GLM-5.3 roteia a visão através de adaptadores separados. O Flash é o multimodal nativo, o que é abordado em nossa comparação.
Quantas imagens por requisição? Múltiplas, cada uma como seu próprio bloco `image_url`. O limite prático é o seu orçamento de contexto.
URL ou base64? Ambos funcionam. Use uma URL pública quando a imagem já estiver hospedada e acessível; use base64 para imagens locais ou privadas.
Ele aceita vídeo? A Z.ai documenta a entrada de vídeo, mas é novo e pouco exercitado. Verifique primeiro com sua própria mídia e provedor.
As imagens são cobradas de forma diferente? Sem sobretaxa. Elas consomem tokens de entrada, então a resolução afeta o custo.