hunyuan-vision API

Especificaciones técnicas de hunyuan-vision

¿Qué es hunyuan-vision?

hunyuan-vision es el modelo multimodal de comprensión de imágenes de Tencent Hunyuan expuesto a través de una API compatible con OpenAI. En los ejemplos oficiales de Tencent, se usa para tareas de tipo "imagen a texto", donde el usuario envía un prompt junto con una imagen y el modelo responde preguntas como qué se muestra en la imagen.

En la práctica, esto hace que hunyuan-vision sea adecuado para aplicaciones que necesitan razonamiento visual en un flujo de chat, como subtitulado de imágenes, descripción de escenas, interpretación de UI o capturas de pantalla, análisis de imágenes de productos y preguntas y respuestas visuales en general. Su patrón de integración es especialmente conveniente para equipos que ya usan clientes estilo OpenAI, porque Tencent indica que los desarrolladores pueden cambiar simplemente reemplazando el endpoint y la configuración de la clave de API.

Características principales de hunyuan-vision

• Comprensión multimodal de imágenes: hunyuan-vision acepta contenido de texto e imagen en la misma solicitud, habilitando conversaciones y respuestas a preguntas sobre elementos visuales subidos.
• Interfaz compatible con OpenAI: Tencent ofrece hunyuan-vision con la misma estructura general de solicitudes que Chat Completions, lo que reduce el esfuerzo de migración para aplicaciones de IA existentes.
• Métodos flexibles de entrada de imágenes: Los ejemplos oficiales muestran soporte tanto para URLs remotas estándar de imágenes como para URLs de datos codificados en base64, lo que ayuda al trabajar con recursos públicos o archivos procesados localmente.
• Integración amigable con SDK: Tencent documenta explícitamente su uso con los SDK de OpenAI en Python, Node.js, Go y solicitudes HTTP estilo cURL, facilitando su incorporación en servicios backend existentes.
• Flujo de trabajo basado en chat: Al exponerse como un modelo de chat completions, hunyuan-vision encaja de forma natural en apps conversacionales, asistentes y toolchains que ya estructuran solicitudes alrededor de messages.
• Contabilización de tokens de imagen basada en el uso: Tencent señala que el costo de imagen depende del tamaño de la imagen, con consumo de tokens por imagen documentado como un rango en lugar de un monto fijo.

Cómo acceder e integrar hunyuan-vision

Paso 1: Regístrate para obtener una clave de API

Para acceder a hunyuan-vision, primero crea y protege tu clave de API a través de la consola del proveedor. Tencent documenta el acceso basado en clave de API para su API de Hunyuan compatible con OpenAI, y la clave se pasa como un token Bearer en las solicitudes. Guarda la clave en una variable de entorno como HUNYUAN_API_KEY y evita exponerla en código del lado del cliente o repositorios públicos.

Paso 2: Envía solicitudes a la API de hunyuan-vision

Usa el endpoint compatible con OpenAI y especifica hunyuan-vision como nombre del modelo.

curl --location 'https://api.hunyuan.cloud.tencent.com/v1/chat/completions' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HUNYUAN_API_KEY" \
  --data '{
    "model": "hunyuan-vision",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What is in this image?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/image.jpg"
            }
          }
        ]
      }
    ]
  }'

También puedes usar SDK compatibles con OpenAI apuntando el cliente a la URL base de Hunyuan:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("HUNYUAN_API_KEY"),
    base_url="https://api.hunyuan.cloud.tencent.com/v1",
)

response = client.chat.completions.create(
    model="hunyuan-vision",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this image."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg"
                    },
                },
            ],
        }
    ],
)

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

Esta estructura de solicitud sigue los ejemplos oficiales de Tencent compatibles con OpenAI para hunyuan-vision.

Paso 3: Recupera y verifica los resultados

Lee la respuesta generada de la primera opción en la respuesta de Chat Completions, normalmente response.choices[0].message.content cuando uses un SDK compatible con OpenAI. Para uso en producción, verifica que la URL de la imagen sea accesible o que tu carga útil en base64 sea válida; luego contrasta la descripción devuelta con los requisitos de tu aplicación en cuanto a precisión, seguridad y consistencia de formato. Los ejemplos de Tencent muestran un manejo estándar de respuestas de chat-completions, por lo que los pipelines existentes de validación y registro suelen poder reutilizarse con cambios mínimos.