Como Usar a API GLM-5V-Turbo? Guia Completo

Resumo

GLM-5V-Turbo é o modelo de codificação de visão multimodal da ZhipuAI com uma janela de contexto de 200K, saída máxima de 128K, e suporte nativo para entradas de imagens, vídeo, texto e arquivos. Ele obteve 94.8 no benchmark Design2Code (vs 77.3 do Claude Opus 4.6) e custa US$ 1.20/M tokens de entrada, US$ 4/M tokens de saída. Este guia aborda a configuração, integração da API e exemplos práticos para tarefas de codificação baseadas em visão.

Introdução

A ZhipuAI (operando como Z.ai) lançou o GLM-5V-Turbo em 1º de abril de 2026. É o primeiro modelo construído especificamente para tarefas de codificação baseadas em visão, onde a entrada é uma imagem, uma captura de tela ou um vídeo, e a saída é um código funcional.

O modelo faz parte de uma família que inclui o GLM-5 (somente texto, 744B parâmetros) e o GLM-5-Turbo (codificação de texto otimizada). O GLM-5V-Turbo adiciona compreensão multimodal nativa à variante Turbo, usando um codificador de visão CogViT e arquitetura de Previsão de Múltiplos Tokens (MTP).

O número de destaque: 94.8 no Design2Code, onde os modelos reproduzem mockups de UI como HTML/CSS. O Claude Opus 4.6 obteve 77.3 no mesmo teste. Isso representa uma diferença de 22% na tarefa específica de transformar designs visuais em código.

Este guia mostra como chamar a API GLM-5V-Turbo, enviar imagens e vídeo, ativar o modo de pensamento, transmitir respostas, usar a chamada de função e testar sua integração com o Apidog.

button

O que o GLM-5V-Turbo pode fazer

Especificações principais

Especificação	Valor
Janela de contexto	200K tokens (202,752)
Saída máxima	128K tokens (131,072)
Modalidades de entrada	Imagem, vídeo, texto, arquivo (PDF, Word)
Modalidade de saída	Texto
Preço de entrada	US$ 1.20 por milhão de tokens
Preço de saída	US$ 4.00 por milhão de tokens
Preço de leitura de cache	US$ 0.24 por milhão de tokens
Data de lançamento	1º de abril de 2026
Endpoint da API	`https://api.z.ai/api/paas/v4/chat/completions`

Capacidades suportadas

Modo de pensamento com tokens de raciocínio configuráveis (tags <think>)
Saída de streaming para respostas em tempo real
Chamada de função para integração de ferramentas
Cache de contexto para otimização de conversas longas
Saída estruturada via configuração de formato de resposta

Onde ele se destaca

O GLM-5V-Turbo é construído especificamente para uma categoria estreita, mas de alto valor: analisar conteúdo visual e escrever código a partir dele. Os principais casos de uso:

Recriação de frontend a partir de mockups de design. Forneça uma captura de tela do Figma ou um comp de design e ele gera HTML/CSS pixel a pixel. A pontuação de 94.8 no Design2Code comprova isso com números concretos.

Exploração autônoma de GUI. O modelo se integra ao OpenClaw (estrutura de agentes da ZhipuAI) para navegação autônoma em sites, preenchimento de formulários e testes de interação. Ele obteve boas pontuações nos benchmarks AndroidWorld e WebVoyager para operação de GUI.

Depuração de código a partir de capturas de tela. Envie uma captura de tela de uma UI quebrada e o modelo identifica problemas de renderização, bugs de layout e conflitos de CSS.

Extração de documentos. Processe PDFs, documentos Word e imagens digitalizadas para extrair dados estruturados, tabelas e texto.

Onde ele não se destaca

Na codificação de texto pura (sem entrada visual), Claude e GPT-5 ainda lideram em tarefas de backend, exploração de repositórios e arquitetura de sistemas. A força do GLM-5V-Turbo está especificamente quando a entrada visual impulsiona a tarefa de codificação.

Começando: Configuração da API

Obtenha sua chave de API

Inscreva-se em z.ai
Navegue até a seção Chaves de API no seu painel
Gere uma nova chave
Armazene-a com segurança; você a passará como um token Bearer

Configuração base

Todas as requisições vão para:

POST https://api.z.ai/api/paas/v4/chat/completions

Cabeçalhos obrigatórios:

Authorization: Bearer SUA_CHAVE_API
Content-Type: application/json

A API segue as convenções compatíveis com OpenAI, então se você já trabalhou com as APIs OpenAI ou Anthropic, o formato da requisição parecerá familiar.

Enviando sua primeira requisição com cURL

Análise básica de imagem

curl -X POST https://api.z.ai/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $ZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5v-turbo",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/dashboard-mockup.png"
            }
          },
          {
            "type": "text",
            "text": "Recreate this dashboard UI as responsive HTML and CSS. Use Tailwind CSS classes."
          }
        ]
      }
    ]
  }'

Com o modo de pensamento ativado

O modo de pensamento adiciona uma etapa de raciocínio antes que o modelo gere sua resposta. Isso melhora a precisão em tarefas complexas de codificação ao custo de tokens de saída adicionais.

curl -X POST https://api.z.ai/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $ZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5v-turbo",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/login-form-screenshot.png"
            }
          },
          {
            "type": "text",
            "text": "This login form has a layout bug on mobile. Identify the issue and provide fixed CSS."
          }
        ]
      }
    ],
    "thinking": {
      "type": "enabled"
    }
  }'

Quando o modo de pensamento está ativado, a resposta inclui reasoning_content junto com o campo content padrão. Os tokens de raciocínio mostram a análise passo a passo do modelo antes de produzir a resposta final.

Integração do SDK Python

Instalação

pip install zai-sdk

Ou fixe uma versão específica:

pip install zai-sdk==0.0.4

Básico: Imagem para código

from zai import ZaiClient

client = ZaiClient(api_key="your-api-key")

response = client.chat.completions.create(
    model="glm-5v-turbo",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/pricing-page.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Convert this pricing page design into a React component using Tailwind CSS. Include responsive breakpoints for mobile, tablet, and desktop."
                }
            ]
        }
    ],
    thinking={"type": "enabled"}
)

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

Streaming de respostas

Para tarefas longas de geração de código (layouts de página inteiros, UIs de múltiplos componentes), o streaming oferece saída em tempo real em vez de esperar pela resposta completa:

from zai import ZaiClient

client = ZaiClient(api_key="your-api-key")

response = client.chat.completions.create(
    model="glm-5v-turbo",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/full-page-design.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Build this entire landing page as a single HTML file with embedded CSS and JavaScript. Include smooth scroll, a sticky navbar, and a working contact form."
                }
            ]
        }
    ],
    stream=True
)

for chunk in response:
    delta = chunk.choices[0].delta
    # Imprime tokens de raciocínio (modo de pensamento)
    if delta.reasoning_content:
        print(f"[pensando] {delta.reasoning_content}", end="", flush=True)
    # Imprime o código gerado
    if delta.content:
        print(delta.content, end="", flush=True)

Entrada de múltiplas imagens

Envie várias imagens em uma única requisição. Isso é útil para comparar designs, fornecer referências de estilo junto com mockups, ou enviar capturas de tela antes/depois para depuração:

response = client.chat.completions.create(
    model="glm-5v-turbo",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/design-mockup.png"}
                },
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/current-implementation.png"}
                },
                {
                    "type": "text",
                    "text": "A primeira imagem é o mockup de design. A segunda é a implementação atual. Identifique todas as diferenças visuais e forneça correções CSS para corresponder ao mockup."
                }
            ]
        }
    ]
)

Chamada de função

O GLM-5V-Turbo suporta chamada de função, permitindo integrá-lo em fluxos de trabalho agênticos onde o modelo pode solicitar ações externas:

tools = [
    {
        "type": "function",
        "function": {
            "name": "save_component",
            "description": "Salva um componente React gerado em um arquivo",
            "parameters": {
                "type": "object",
                "properties": {
                    "filename": {
                        "type": "string",
                        "description": "Nome do arquivo do componente, ex: 'PricingCard.tsx'"
                    },
                    "code": {
                        "type": "string",
                        "description": "O código-fonte completo do componente"
                    },
                    "dependencies": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Pacotes npm que este componente requer"
                    }
                },
                "required": ["filename", "code"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "take_screenshot",
            "description": "Tira uma captura de tela de uma URL para verificar a saída renderizada",
            "parameters": {
                "type": "object",
                "properties": {
                    "url": {
                        "type": "string",
                        "description": "URL para tirar a captura de tela"
                    },
                    "viewport": {
                        "type": "string",
                        "description": "Tamanho da viewport: 'mobile', 'tablet' ou 'desktop'"
                    }
                },
                "required": ["url"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="glm-5v-turbo",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/card-design.png"}
                },
                {
                    "type": "text",
                    "text": "Gere um componente React a partir deste design de cartão e salve-o. Em seguida, tire uma captura de tela para verificar."
                }
            ]
        }
    ],
    tools=tools,
    tool_choice="auto"
)

Integração do SDK Java

Dependência Maven

<dependency>
    <groupId>ai.z.openapi</groupId>
    <artifactId>zai-sdk</artifactId>
    <version>0.3.0</version>
</dependency>

Gradle

implementation 'ai.z.openapi:zai-sdk:0.3.0'

Requisição básica

import ai.z.openapi.ZaiClient;
import ai.z.openapi.model.*;
import java.util.Arrays;

public class GLM5VTurboExample {
    public static void main(String[] args) {
        String apiKey = System.getenv("ZAI_API_KEY");

        ZaiClient client = ZaiClient.builder().ofZAI()
            .apiKey(apiKey)
            .build();

        ChatCompletionCreateParams request =
            ChatCompletionCreateParams.builder()
                .model("glm-5v-turbo")
                .messages(Arrays.asList(
                    ChatMessage.builder()
                        .role(ChatMessageRole.USER.value())
                        .content(Arrays.asList(
                            MessageContent.builder()
                                .type("image_url")
                                .imageUrl(ImageUrl.builder()
                                    .url("https://example.com/mockup.png")
                                    .build())
                                .build(),
                            MessageContent.builder()
                                .type("text")
                                .text("Converta este design para HTML com Tailwind CSS.")
                                .build()
                        ))
                        .build()
                ))
                .build();

        ChatCompletionResponse response =
            client.chat().createChatCompletion(request);

        System.out.println(response.getChoices()
            .get(0).getMessage().getContent());
    }
}

Streaming em Java

ChatCompletionCreateParams streamRequest =
    ChatCompletionCreateParams.builder()
        .model("glm-5v-turbo")
        .stream(true)
        .messages(Arrays.asList(
            ChatMessage.builder()
                .role(ChatMessageRole.USER.value())
                .content(Arrays.asList(
                    MessageContent.builder()
                        .type("image_url")
                        .imageUrl(ImageUrl.builder()
                            .url("https://example.com/dashboard.png")
                            .build())
                        .build(),
                    MessageContent.builder()
                        .type("text")
                        .text("Construa este painel como um componente React.")
                        .build()
                ))
                .build()
        ))
        .build();

ChatCompletionResponse streamResponse =
    client.chat().createChatCompletionStream(streamRequest);

streamResponse.getFlowable().subscribe(
    data -> System.out.print(data),
    error -> System.err.println("Erro: " + error.getMessage()),
    () -> System.out.println("\n[Concluído]")
);

Usando o endpoint compatível com OpenAI

A API Z.ai segue as convenções da OpenAI, então você pode usar o cliente Python da OpenAI com uma URL base personalizada:

from openai import OpenAI

client = OpenAI(
    api_key="sua-zai-api-key",
    base_url="https://api.z.ai/api/paas/v4"
)

response = client.chat.completions.create(
    model="glm-5v-turbo",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/wireframe.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Transforme este wireframe em um componente Vue 3 funcional com Composition API."
                }
            ]
        }
    ]
)

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

Isso significa que qualquer ferramenta que suporte APIs compatíveis com OpenAI, incluindo Apidog, pode se conectar ao GLM-5V-Turbo apontando para a URL base de Z.ai.

Testando chamadas de API do GLM-5V-Turbo com Apidog

Antes de integrar o GLM-5V-Turbo à sua aplicação, teste suas chamadas de API interativamente com o Apidog. Isso evita que você depure payloads JSON brutos no código.

Configurar o endpoint

Abra o Apidog e crie uma nova requisição
Defina o método como POST e a URL como https://api.z.ai/api/paas/v4/chat/completions
Adicione o cabeçalho Authorization: Bearer SUA_CHAVE
Defina Content-Type: application/json

Construir corpos de requisição multimodal visualmente

O editor JSON do Apidog permite que você construa o array messages aninhado com blocos de conteúdo image_url e text sem precisar escrever JSON manualmente. Você pode:

Alternar entre JSON bruto e entrada baseada em formulário
Salvar modelos de requisição para padrões comuns (imagem única, múltiplas imagens, entrada de vídeo)
Usar variáveis de ambiente para a chave da API para não precisar colá-la em cada requisição

Comparar respostas do modelo

Ao avaliar o GLM-5V-Turbo contra outros modelos de visão (Claude, GPT-4o, Gemini), use o executor de coleção do Apidog para enviar a mesma imagem para múltiplos endpoints e comparar as saídas lado a lado. Isso é particularmente útil para tarefas de Design2Code, onde você deseja verificar qual modelo produz o HTML/CSS mais preciso.

Validar esquemas de resposta

As respostas de streaming do GLM-5V-Turbo incluem os campos reasoning_content e content. O validador de resposta do Apidog pode verificar se sua aplicação lida corretamente com ambos os campos, incluindo casos extremos onde um campo é nulo.

Baixe o Apidog para começar a testar sua integração GLM-5V-Turbo.

Comparação de preços com outros modelos de visão

Modelo	Entrada (por 1M tokens)	Saída (por 1M tokens)	Janela de contexto	Pontuação Design2Code
GLM-5V-Turbo	US$ 1.20	US$ 4.00	200K	94.8
Claude Opus 4.6	US$ 15.00	US$ 75.00	200K	77.3
Claude Sonnet 4.6	US$ 3.00	US$ 15.00	200K	N/A
GPT-4o	US$ 2.50	US$ 10.00	128K	N/A
Gemini 3 Pro	US$ 1.25	US$ 5.00	1M	N/A

O GLM-5V-Turbo é a opção mais barata para tarefas de codificação baseadas em visão. Ele custa 92% menos que o Claude Opus 4.6 em tokens de entrada e 94.7% menos em tokens de saída, enquanto pontua 22% mais alto no Design2Code.

A contrapartida: Claude e GPT-5 lidam melhor com tarefas de codificação mais amplas. Se o seu fluxo de trabalho é especificamente "imagem dentro, código fora", o GLM-5V-Turbo oferece a melhor relação preço-desempenho.

Arquitetura: como funciona por baixo do capô

Codificador de visão CogViT

O GLM-5V-Turbo usa o CogViT, um transformador de visão projetado para preservar hierarquias espaciais e detalhes visuais finos. Codificadores de visão padrão comprimem imagens em vetores de características planos, perdendo relações espaciais. O CogViT mantém as informações posicionais que importam para tarefas sensíveis ao layout, como posicionamento de grade CSS, alinhamento flexbox e espaçamento pixel a pixel.

Previsão de Múltiplos Tokens (MTP)

A arquitetura MTP prevê múltiplos tokens por passagem de avanço em vez de um por vez. Para a geração de código, isso significa inferência mais rápida ao gerar longas sequências de HTML, CSS ou JavaScript. O modelo não gera token por token; ele prevê blocos, reduzindo a latência na janela de saída máxima de 128K.

Aprendizado por reforço conjunto em mais de 30 tarefas

A ZhipuAI treinou o GLM-5V-Turbo com aprendizado por reforço em mais de 30 tarefas simultaneamente: raciocínio STEM, fundamentação visual, análise de vídeo, operação de GUI e codificação. Essa otimização conjunta evita que o modelo sofra overfitting para um tipo de tarefa, mantendo um forte desempenho em toda a gama de fluxos de trabalho de visão-codificação.

Sistema de dados agêntico

O pipeline de treinamento inclui o que a ZhipuAI chama de sistema de "construção de dados verificáveis de múltiplos níveis" com pré-treinamento de previsão de ações. Na prática, isso significa que o modelo foi treinado em sequências de "ver captura de tela, prever próxima ação, executar, verificar resultado", tornando-o eficaz para tarefas de GUI autônomas além da conversão estática de imagem para código.

Exemplos práticos

Mockup de design para componente React

from zai import ZaiClient

client = ZaiClient(api_key="sua-chave-api")

response = client.chat.completions.create(
    model="glm-5v-turbo",
    messages=[
        {
            "role": "system",
            "content": "Você é um desenvolvedor frontend sênior. Gere componentes React prontos para produção com TypeScript e Tailwind CSS. Inclua tipos apropriados, atributos de acessibilidade e design responsivo."
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/hero-section.png"}
                },
                {
                    "type": "text",
                    "text": "Crie esta seção de herói como um componente React TypeScript. Deve ser totalmente responsivo com uma abordagem mobile-first. Inclua o fundo gradiente, o botão CTA com estado de hover e o posicionamento da ilustração."
                }
            ]
        }
    ],
    thinking={"type": "enabled"}
)

# O modelo primeiro raciocina sobre a estrutura do layout (reasoning_content)
# então gera o componente React completo (content)
print(response.choices[0].message.content)

Fluxo de trabalho de depuração de captura de tela

def debug_ui_from_screenshot(screenshot_url: str, description: str) -> str:
    """Envia uma captura de tela de uma UI quebrada e obtém correções CSS."""
    response = client.chat.completions.create(
        model="glm-5v-turbo",
        messages=[
            {
                "role": "system",
                "content": "Você é um especialista em depuração de CSS. Analise capturas de tela de UIs quebradas e forneça correções CSS específicas. Sempre explique o que está errado antes de fornecer a correção."
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "image_url",
                        "image_url": {"url": screenshot_url}
                    },
                    {
                        "type": "text",
                        "text": f"Relatório de bug: {description}. Identifique os problemas de CSS e forneça correções."
                    }
                ]
            }
        ],
        thinking={"type": "enabled"}
    )

    return response.choices[0].message.content


# Uso
fix = debug_ui_from_screenshot(
    "https://example.com/broken-modal.png",
    "A caixa de diálogo modal está transbordando em telas de celular e o botão de fechar está inacessível"
)
print(fix)

Extração de documentos para dados estruturados

response = client.chat.completions.create(
    model="glm-5v-turbo",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/api-spec-page.png"}
                },
                {
                    "type": "text",
                    "text": "Extraia as definições de endpoint da API desta captura de tela de documentação. Retorne-as como uma especificação OpenAPI 3.1 YAML."
                }
            ]
        }
    ]
)

Este é um caso de uso forte para equipes de desenvolvimento de API: fotografe designs de API em quadro branco ou digitalize documentação legada, e então gere especificações OpenAPI diretamente. Você pode então importar a especificação gerada para o Apidog para obter documentação interativa, servidores simulados e casos de teste a partir de uma única captura de tela.

Dicas para tirar o máximo proveito do GLM-5V-Turbo

A qualidade da imagem importa

O codificador CogViT preserva detalhes espaciais, mas não pode recuperar informações que não estão na imagem original. Para tarefas de Design2Code:

Use capturas de tela com resolução 2x (Retina) para texto nítido e detalhes de ícones
Corte para o componente específico que você deseja recriar, não a página inteira
Remova o cromo do navegador e as decorações da janela do SO das capturas de tela
Para precisão de cores, use PNG em vez de JPEG para evitar artefatos de compressão

Use o modo de pensamento para layouts complexos

Ative o modo de pensamento ("thinking": {"type": "enabled"}) para:

Layouts de página com múltiplos componentes
Designs responsivos com lógica de breakpoint
Designs com CSS complexo (grid, aninhamento flexbox, animações)
Tarefas de depuração onde a análise da causa raiz é importante

Ignore o modo de pensamento para tarefas simples (extração de componente único, legendas de imagem básicas) para economizar custos de token e latência.

Gerencie sua janela de contexto

Com 200K tokens, a janela de contexto é grande, mas não ilimitada. Uma única imagem de alta resolução pode consumir de 1.000 a 5.000 tokens. Para fluxos de trabalho com múltiplas imagens:

Redimensione as imagens para a resolução mínima que a tarefa exige
Use cache de contexto para conversas iterativas onde o design base permanece o mesmo
Divida designs de página inteira em capturas de tela de nível de componente para geração individual

Otimização de custos com cache

O cache de contexto custa US$ 0.24/M tokens (80% de desconto sobre o preço de entrada padrão). Para fluxos de trabalho iterativos de design para código onde você está refinando o mesmo componente:

Envie a imagem do design na primeira requisição
As requisições subsequentes referenciam o contexto em cache
Cada iteração custa uma fração de reenviar a imagem completa

Lidando com erros e casos de borda

Limites de taxa e novas tentativas

A API Z.ai retorna códigos de status HTTP padrão. Lide com eles em sua integração:

import time
from zai import ZaiClient

client = ZaiClient(api_key="sua-chave-api")

def call_with_retry(messages, max_retries=3):
    """Chama o GLM-5V-Turbo com backoff exponencial em limites de taxa."""
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="glm-5v-turbo",
                messages=messages,
                thinking={"type": "enabled"}
            )
            return response
        except Exception as e:
            error_str = str(e)
            if "429" in error_str:
                # Limite de taxa atingido - espere e tente novamente
                wait_time = 2 ** attempt
                print(f"Limite de taxa atingido. Tentando novamente em {wait_time}s...")
                time.sleep(wait_time)
                continue
            elif "400" in error_str:
                # Requisição inválida - não tente novamente, corrija a entrada
                print(f"Requisição inválida: {error_str}")
                raise
            else:
                # Erro do servidor - tente novamente
                if attempt < max_retries - 1:
                    time.sleep(1)
                    continue
                raise

    raise Exception("Número máximo de tentativas excedido")

Lidando com grandes saídas

Com uma janela de saída máxima de 128K, o GLM-5V-Turbo pode gerar aplicações inteiras com vários arquivos em uma única resposta. Sua aplicação precisa lidar com isso:

response = client.chat.completions.create(
    model="glm-5v-turbo",
    messages=messages,
    max_tokens=131072  # Saída completa de 128K
)

content = response.choices[0].message.content

# Analisa múltiplos arquivos da saída
# O modelo tipicamente separa arquivos com cercas de código markdown
import re

file_blocks = re.findall(
    r'```(\w+)?\s*\n// file: (.+?)\n(.*?)```',
    content,
    re.DOTALL
)

for lang, filename, code in file_blocks:
    print(f"Escrevendo {filename} ({lang})")
    with open(filename, "w") as f:
        f.write(code.strip())

Acessibilidade de URL de imagem

O modelo busca imagens das URLs que você fornece. Falhas comuns:

URLs assinadas expiradas de armazenamento em nuvem (S3, GCS). Gere URLs com validade de pelo menos 1 hora.
Imagens com restrição CORS que bloqueiam a busca pelo lado do servidor. Hospede imagens em uma CDN sem restrições CORS.
Imagens grandes que esgotam o tempo limite durante o download. Redimensione para menos de 5MB antes de enviar.

Se você controla a hospedagem da imagem, uma CDN pública sem autenticação é a opção mais confiável para chamadas de API.

GLM-5V-Turbo vs. usando-o através do OpenRouter

Você pode acessar o GLM-5V-Turbo através do OpenRouter como uma alternativa à API direta da Z.ai. O OpenRouter processou mais de 44.000 requisições com mais de 769 milhões de tokens de prompt nos dois primeiros dias de disponibilidade do modelo.

Benefícios do OpenRouter:

Uma única chave de API para múltiplos provedores de modelos
Fallback automático se Z.ai tiver tempo de inatividade
Análise de uso em todos os seus modelos
Mesmo formato compatível com OpenAI

Desvantagem: O OpenRouter adiciona uma pequena margem aos preços dos tokens. Para uso de produção de alto volume, a API direta da Z.ai é mais barata.

Construindo um pipeline de design para código com GLM-5V-Turbo

Aqui está um fluxo de trabalho completo que pega um mockup de design, gera código e valida a saída:

from zai import ZaiClient
import os
import subprocess

client = ZaiClient(api_key=os.environ["ZAI_API_KEY"])


def design_to_code_pipeline(image_url: str, output_dir: str, framework: str = "react"):
    """Pipeline completo: captura de tela do design -> código funcional -> validação."""

    os.makedirs(output_dir, exist_ok=True)

    # Passo 1: Analisar o design
    analysis = client.chat.completions.create(
        model="glm-5v-turbo",
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "image_url", "image_url": {"url": image_url}},
                    {
                        "type": "text",
                        "text": "Analise este design. Liste: 1) Todos os componentes de UI visíveis, 2) A paleta de cores (valores hexadecimais), 3) Tipografia (tamanhos de fonte, pesos), 4) Estrutura do layout (grid/flexbox), 5) Elementos interativos (botões, inputs, dropdowns)."
                    }
                ]
            }
        ],
        thinking={"type": "enabled"}
    )

    design_analysis = analysis.choices[0].message.content
    print(f"Análise de design completa: {len(design_analysis)} caracteres")

    # Passo 2: Gerar o componente
    generation = client.chat.completions.create(
        model="glm-5v-turbo",
        messages=[
            {
                "role": "system",
                "content": f"Você é um desenvolvedor {framework}. Gere componentes prontos para produção, acessíveis e responsivos. Use TypeScript e Tailwind CSS."
            },
            {
                "role": "user",
                "content": [
                    {"type": "image_url", "image_url": {"url": image_url}},
                    {
                        "type": "text",
                        "text": f"Com base neste design, gere o componente {framework} completo. Inclua toda a estilização, estados de hover e breakpoints responsivos. O componente deve corresponder ao design pixel a pixel."
                    }
                ]
            }
        ],
        thinking={"type": "enabled"},
        max_tokens=16384
    )

    code = generation.choices[0].message.content

    # Passo 3: Salvar a saída
    output_file = os.path.join(output_dir, "Component.tsx")
    with open(output_file, "w") as f:
        # Extrai código de cercas markdown, se presentes
        if "```" in code:
            import re
            match = re.search(r'```(?:tsx?|jsx?)\n(.*?)```', code, re.DOTALL)
            if match:
                f.write(match.group(1).strip())
            else:
                f.write(code)
        else:
            f.write(code)

    print(f"Componente salvo em {output_file}")
    return output_file


# Uso
design_to_code_pipeline(
    image_url="https://example.com/dashboard-card.png",
    output_dir="./generated-components",
    framework="react"
)

Este pipeline separa a análise da geração. A primeira chamada mapeia a estrutura, cores e tipografia do design. A segunda chamada gera o código com essa compreensão como contexto. Dividir o trabalho em duas chamadas produz uma saída mais precisa do que uma única requisição "converter isso para código", porque o modelo já raciocinou sobre o layout antes de escrever o código.

Você pode testar cada etapa independentemente no Apidog, salvando a requisição de análise e a requisição de geração como endpoints separados em uma coleção, e então executando-os em sequência com o executor de coleção.

button

FAQ

O GLM-5V-Turbo é gratuito?

Não. O preço da API é de US$ 1.20/M tokens de entrada e US$ 4.00/M tokens de saída. A ZhipuAI oferece uma interface web gratuita em chat.z.ai para testes, mas o uso da API requer pagamento.

Posso enviar imagens codificadas em base64?

A documentação mostra entrada de imagem baseada em URL (image_url com um campo url). Para suporte a base64, codifique sua imagem como uma URI de dados: data:image/png;base64,{dados_codificados} e passe-a como o valor da URL. Isso segue a mesma convenção da API de Visão da OpenAI.

Como o GLM-5V-Turbo lida com entrada de vídeo?

Vídeo está listado como uma modalidade de entrada suportada. O modelo pode processar quadros de vídeo para tarefas como analisar gravações de interação de UI, identificar bugs de animação ou entender fluxos de usuário. Os requisitos específicos de codec e formato ainda não foram documentados.

Qual a diferença entre GLM-5-Turbo e GLM-5V-Turbo?

GLM-5-Turbo é um modelo de codificação somente texto. GLM-5V-Turbo adiciona o codificador de visão CogViT para entrada multimodal (imagens, vídeo, arquivos). Escolha GLM-5-Turbo para tarefas de codificação de texto puro e GLM-5V-Turbo quando seu fluxo de trabalho envolve entrada visual.

Posso usar o GLM-5V-Turbo com o cliente Python da OpenAI?

Sim. Defina a base_url para https://api.z.ai/api/paas/v4 e use sua chave de API Z.ai. O endpoint segue as convenções compatíveis com OpenAI para conclusões de chat, incluindo formatos de mensagem multimodais.

Como ele se compara ao Claude para codificação?

O GLM-5V-Turbo domina em tarefas de visão para código (94.8 vs 77.3 no Design2Code). O Claude lidera em codificação de texto puro, arquitetura de backend e compreensão em nível de repositório. Eles atendem a diferentes casos de uso. Para equipes que fazem ambos, a diferença de custo é significativa: o GLM-5V-Turbo é 92% mais barato em tokens de entrada do que o Claude Opus 4.6.

Qual o tamanho máximo da imagem?

A documentação não especifica um limite de pixels. A janela de contexto de 200K é a restrição prática; imagens maiores consomem mais tokens. Para tarefas de Design2Code, capturas de tela de 1920x1080 com resolução 2x funcionam bem sem atingir os limites.

A ZhipuAI retém meus dados de API?

Não. A política de dados da Z.ai afirma que não há uso para treinamento e nenhuma retenção de prompt para chamadas de API. Suas imagens e saídas de código não são usadas para treinar modelos futuros.