Cómo Usar la API GLM-5.3-Flash (Con Entrada de Imagen)

Cómo usar la API de GLM-5.3-Flash con Python, curl y Node

GLM-5.3-Flash es compatible con OpenAI: puedes reutilizar un cliente existente cambiando la URL base y el ID del modelo. Su principal novedad es la entrada de imágenes, ya que es el primer modelo GLM-5 que acepta imágenes y texto en la misma solicitud. Esta guía muestra cómo obtener una clave, realizar llamadas de texto, enviar imágenes, controlar el razonamiento, usar streaming y configurar llamadas a herramientas. Todos los ejemplos utilizan glm-5.3-flash.

Prueba Apidog hoy

Si necesitas contexto antes de empezar, consulta qué es GLM-5.3-Flash. Para su hermano mayor, revisa la guía de la API de GLM-5.3. Las diferencias son importantes: cambia el ID del modelo, la tarjeta de tarifas y la compatibilidad nativa con imágenes.

Obtener una clave de API

Crea una cuenta en z.ai, abre la sección de claves de API y genera una clave. Guárdala como variable de entorno, no en el código fuente:

export ZAI_API_KEY="your-key-here"

La URL base de la API estándar es:

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

Los endpoints del plan de codificación utilizan una URL base independiente. Es relevante si configuras Claude Code o Cline en lugar de llamar directamente a la API. Consulta nuestra guía de Claude Code y Cline.

Primera llamada

Como el endpoint es compatible con OpenAI, el SDK oficial funciona sin modificaciones:

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)

La misma llamada con 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."}
    ]
  }'

Y con Node:

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 de esto es específico de GLM, salvo la URL base y el ID del modelo. Esa compatibilidad facilita comparar el modelo con tu carga de trabajo actual.

Enviar imágenes

A diferencia de GLM-5.3, GLM-5.3-Flash admite imágenes mediante bloques de contenido. content deja de ser una cadena y pasa a ser un array de bloques 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"
                    },
                },
            ],
        }
    ],
)

Ten en cuenta estas reglas:

1. Usa una URL pública o una URL de datos

Si la imagen es local o privada, conviértela a 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. Cada imagen requiere su propio bloque

No existe un atajo con un array de URLs. Para comparar un diseño con su implementación, envía dos bloques image_url en el mismo 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. El orden importa

El modelo procesa el array secuencialmente. Coloca primero la instrucción y después las imágenes a las que hace referencia. Por ejemplo, “Compara estas dos imágenes” seguido de las dos imágenes funciona mejor que colocar las imágenes antes de la pregunta.

La documentación de Z.ai también enumera entradas de vídeo y archivos con el mismo mecanismo. El vídeo es más reciente y está menos probado, así que valida su comportamiento antes de usarlo en producción.

Para flujos de captura de pantalla a código y para combinar imágenes con documentos largos dentro de la ventana de 1 millón de tokens, consulta nuestra guía de visión de GLM-5.3-Flash.

Controlar el esfuerzo de razonamiento

GLM-5.3-Flash ofrece tres niveles mediante 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"},
)

Los valores admitidos son:

• low
• high
• max

El valor predeterminado es max, que también es el más caro. Para clasificación o extracción de alto volumen, establece low explícitamente si la tarea no requiere mucha deliberación. Este nivel es nuevo respecto a GLM-5.2, que solo exponía High y Max.

Con el SDK de Python de OpenAI, reasoning_effort debe ir dentro de extra_body porque no forma parte del esquema estándar. En curl es un campo de nivel superior.

Parámetros de muestreo recomendados

Z.ai publica estos valores según el caso de uso:

Caso de uso	temperature	top_p
General	1.0	0.95
Codificación	0.95	1.0

La diferencia suele ser marginal, pero si la salida de código es inconsistente, prueba primero el perfil de codificación.

Streaming

El streaming utiliza la semántica estándar de OpenAI:

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)

Según Artificial Analysis, GLM-5.3-Flash genera aproximadamente 49 tokens por segundo, frente a los 86 de GLM-5.3. Su tiempo hasta el primer token es de alrededor de 1,52 segundos: empieza rápido y mantiene una velocidad constante. Para interfaces de usuario, este perfil suele ser adecuado; para documentos largos generados por lotes, inclúyelo en tu estimación de tiempo.

Llamadas a herramientas

Las herramientas utilizan el esquema estándar de 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)

En el lanzamiento, Z.ai publicó un resultado de 48,8 en AutomationBench para GLM-5.3-Flash, frente a 26,2 para GLM-5.2. Son cifras del proveedor, pero apuntan a un modelo optimizado para bucles de llamadas a herramientas, no solo para chat de un turno.

Si ya tienes una API y necesitas generar sus definiciones de herramientas, esta guía sobre cómo convertir una especificación OpenAPI en herramientas de agente muestra el proceso sin escribir todos los esquemas manualmente.

Manejo de errores

Tres problemas suelen concentrar la mayoría de los fallos en producción.

Límites de tasa

Reintenta con retroceso exponencial y jitter. Los intervalos fijos sincronizan a muchos trabajadores y pueden convertir un límite temporal en uno sostenido:

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())

Desbordamiento de contexto

Una ventana de 1 millón de tokens puede parecer ilimitada, pero un documento extenso combinado con imágenes de alta resolución puede superarla. Las imágenes también consumen contexto y el error aparece al enviar la solicitud. Controla tu presupuesto de tokens antes de llamar a la API.

Salida truncada

Si la respuesta termina a mitad de una frase, comprueba finish_reason. El valor length indica que se alcanzó el límite de salida; no significa que el modelo haya abandonado la tarea. Las fuentes no coinciden sobre el máximo exacto, así que verifica este campo explícitamente.

Leer el uso de tokens

Cada respuesta incluye un objeto usage, que es la fuente más fiable del coste real:

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

Presta especial atención a completion_tokens. Con reasoning_effort en max, los tokens de razonamiento se facturan como salida. Una respuesta visible corta puede ocultar un volumen mucho mayor de tokens de finalización. Compara este valor con distintos niveles de esfuerzo y tus propios prompts.

Precio

El precio de lista es:

• Entrada: 0,15 USD por millón de tokens
• Salida: 0,50 USD por millón de tokens
• Entrada en caché: 0,03 USD por millón de tokens

El descuento de lanzamiento del 50 % está vigente hasta el 9 de septiembre de 2026, con precios de 0,075 USD, 0,25 USD y 0,015 USD, respectivamente.

Los precios varían según el revendedor. OpenRouter, Cloudflare Workers AI, Vercel AI Gateway, DeepInfra y otros ofrecen el modelo con sus propias tarifas. Nuestro desglose de precios explica el cálculo y qué ocurre cuando termina el descuento. Confirma siempre las cifras con el proveedor que vayas a utilizar.

Probar la integración

Hay dos aspectos difíciles de verificar manualmente:

1. El payload multimodal es verboso, especialmente cuando incluye imágenes base64.
2. Cambiar de modelo puede modificar silenciosamente la forma de la respuesta.

Con Apidog, guarda las llamadas de texto, imagen y herramientas en una colección. Añade aserciones sobre los campos que realmente consume tu aplicación y almacena la clave como variable de entorno, en lugar de pegarla en una terminal.

Cuando termine el descuento y decidas si continuar con Flash o pasar a GLM-5.3, cambia el ID del modelo en un solo lugar y ejecuta la misma suite contra ambos. Así conviertes la migración en una diferencia verificable, no en una suposición.

Preguntas frecuentes

¿Cuál es el ID exacto del modelo?

En la API de Z.ai es glm-5.3-flash. En OpenRouter es z-ai/glm-5.3-flash.

¿El SDK de OpenAI funciona sin cambios?

Sí, para completaciones de chat, streaming y llamadas a herramientas. Los parámetros no estándar, como reasoning_effort, requieren extra_body en el SDK de Python.

¿Cuántas imágenes puedo enviar en una solicitud?

Puedes enviar varias, cada una en su propio bloque image_url. El límite práctico depende del presupuesto de contexto, no de un número fijo de imágenes.

¿Por qué las respuestas son tan verbosas y lentas?

reasoning_effort vale max de forma predeterminada. Usa low en tareas que no requieran deliberación.

¿Cuál es la longitud máxima de salida?

Las fuentes no coinciden: OpenRouter indica 131.072 tokens y la tarjeta de Hugging Face indica 163.840. Consulta a tu proveedor antes de depender de generaciones muy largas.