Tutorial de visión de Kimi K3: imágenes, vídeo y del diseño al código

Una de las mejoras más prácticas de Kimi K3 es que la visión pasa a ser una capacidad nativa: sin OCR adosado ni una segunda modelo de visión. Metes imágenes y vídeo directamente en messages y dejas que el modelo «mire la imagen» para escribir código, leer gráficos y entender interfaces. Pero al construir una petición multimodal hay unos cuantos detalles que debes acertar con exactitud, o falla sin más. Esta guía deja claro el enfoque correcto.

Primero, dos reglas de oro

La entrada de visión de Kimi K3 tiene dos requisitos estrictos; grábatelos antes que nada:

1. El contenido de imagen y texto debe ser un «array de objetos», nunca aplanado en una cadena serializada. Es decir, content se escribe como una lista del tipo [{type:"text",...}, {type:"image_url",...}].
2. No se admiten URL públicas de imagen. Inserta las imágenes locales en línea como base64, y para el vídeo súbelo con la files API y refiérete a él como ms://<file-id>. Pasar https://example.com/a.png directamente fallará.

Ten claras estas dos y esquivarás la mayoría de los «errores de petición de visión».

Entrada de imagen: base64 en línea

import base64, os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
)

with open("design.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "¿Qué componentes de UI hay en esta imagen? Hazme una lista."},
            {"type": "image_url",
             "image_url": {"url": f"data:image/png;base64,{b64}"}},
        ],
    }],
)
print(resp.choices[0].message.content)

Fíjate en que image_url.url usa un data URI (data:image/png;base64,...). Esto es «base64 en línea», no un «enlace público»: y lo que K3 admite es precisamente esto.

Entrada de vídeo: files API + referencia ms://

Sube primero el archivo de vídeo con la files API y, una vez tengas el file id, refiérete a él en el mensaje con ms://<file-id>:

# 1) Sube el vídeo y obtén un file id
f = client.files.create(file=open("demo.mp4", "rb"), purpose="assistants")

# 2) Refiérete a él en el mensaje con ms://<file-id>
resp = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "En esta grabación de pantalla, ¿qué pasos completó el usuario?"},
            {"type": "image_url", "image_url": {"url": f"ms://{f.id}"}},
        ],
    }],
)

Los parámetros del endpoint de subida, como purpose, se rigen por la documentación oficial; comprueba la versión vigente antes de integrar.

En la práctica: convertir un diseño en un frontend

K3 está pensado para escenarios que «combinan ingeniería de software y análisis visual», y el más típico es escribir el frontend directamente a partir de un diseño:

with open("mockup.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text":
                "Escribe estrictamente a partir de este diseño el HTML + Tailwind CSS correspondiente. "
                "Reproduce la maquetación, el espaciado y los colores lo más fielmente posible y devuelve un único archivo completo y ejecutable."},
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
        ],
    }],
)
print(resp.choices[0].message.content)

El mismo planteamiento sirve para leer los datos de un gráfico y analizarlos, localizar un problema a partir de una captura de error o editar código según una captura de un juego o de CAD. Como K3 tiene un contexto de 1M, incluso puedes meter juntos «el diseño + tu base de código existente» y que edite dentro del contexto completo del proyecto en lugar de generar desde cero (para el uso de contexto largo, consulta la guía del contexto de 1M).

Errores frecuentes

• La petición de visión falla sin más: casi siempre pasaste una URL pública o aplanaste content en una cadena. Cambia a base64 / ms:// más un array de objetos.
• Imagen demasiado grande / fuera de presupuesto: tanto las imágenes como el vídeo cuentan como tokens, y una imagen grande o un vídeo largo se comen mucho contexto. Comprime las dimensiones o extrae fotogramas cuando haga falta.
• Se pierde el estado entre turnos: en una conversación multiturno con imágenes, acuérdate de reenviar el mensaje completo de assistant tal cual; no dejes solo content.

Conclusión

La visión nativa de K3 convierte «mirar una imagen + escribir código» en algo que una sola modelo resuelve en una sola petición. Ten presentes las dos reglas de oro (array de objetos, nada de URL públicas) y prácticamente no tropezarás. Para la integración completa, los precios y la migración, consulta el tutorial de la API de Kimi K3. Para llamar a K3 junto a otras modelos multimodales con una sola clave y comparar resultados por tarea, consigue una clave en el panel de GetModel y empieza.