hunyuan-vision API

Specifiche tecniche di hunyuan-vision

Che cos'è hunyuan-vision?

hunyuan-vision è il modello multimodale di comprensione delle immagini di Tencent Hunyuan esposto tramite un'API compatibile con OpenAI. Negli esempi ufficiali di Tencent, è utilizzato per attività in stile “image-to-text” in cui un utente invia un prompt insieme a un'immagine e il modello risponde a domande su ciò che è mostrato nell'immagine.

In pratica, ciò rende hunyuan-vision adatto ad applicazioni che necessitano di ragionamento visivo in un flusso di chat, come didascalie di immagini, descrizioni di scene, interpretazione di UI o screenshot, analisi di immagini di prodotto e risposta a domande visive generali. Il suo modello d’integrazione è particolarmente conveniente per i team che già utilizzano client in stile OpenAI, poiché Tencent afferma che gli sviluppatori possono effettuare lo switch sostituendo solo l’endpoint e la configurazione della chiave API.

Caratteristiche principali di hunyuan-vision

• Multimodalità nella comprensione delle immagini: hunyuan-vision accetta contenuti di testo e immagine nella stessa richiesta, abilitando conversazioni consapevoli dell’immagine e risposte a domande su contenuti visivi caricati.
• Interfaccia compatibile con OpenAI: Tencent fornisce hunyuan-vision con la stessa struttura generale delle richieste di Chat Completions, riducendo lo sforzo di migrazione per applicazioni IA esistenti.
• Metodi flessibili di input immagine: Gli esempi ufficiali mostrano il supporto per URL di immagini remoti standard e data URL codificati in base64, utile sia per asset pubblici sia per file elaborati localmente.
• Integrazione orientata agli SDK: Tencent documenta esplicitamente l’uso con gli SDK OpenAI in Python, Node.js, Go e richieste HTTP in stile cURL, rendendo semplice l’integrazione nei servizi backend esistenti.
• Flusso di lavoro basato su chat: Essendo esposto come modello di chat completion, hunyuan-vision si adatta naturalmente ad app conversazionali, assistenti e toolchain che strutturano le richieste attorno a messages.
• Calcolo dei token immagine basato sull’uso: Tencent osserva che il costo per immagine dipende dalla dimensione dell’immagine, con consumo di token per immagine documentato come un intervallo anziché un valore fisso.

Come accedere e integrare hunyuan-vision

Passaggio 1: Registrarsi per ottenere la chiave API

Per accedere a hunyuan-vision, crea e proteggi la tua chiave API tramite la console del provider. Tencent documenta l’accesso basato su chiave API per la sua API Hunyuan compatibile con OpenAI, e la chiave viene passata come token Bearer nelle richieste. Conserva la chiave in una variabile d’ambiente come HUNYUAN_API_KEY ed evita di esporla nel codice client-side o in repository pubblici.

Passaggio 2: Inviare richieste all’API hunyuan-vision

Usa l’endpoint compatibile con OpenAI e specifica hunyuan-vision come nome del modello.

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"
            }
          }
        ]
      }
    ]
  }'

Puoi anche usare gli SDK compatibili con OpenAI puntando il client all’URL di base 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)

Questa struttura di richiesta segue gli esempi ufficiali compatibili con OpenAI di Tencent per hunyuan-vision.

Passaggio 3: Recuperare e verificare i risultati

Leggi la risposta generata dalla prima scelta della completion, in genere response.choices[0].message.content quando utilizzi un SDK compatibile con OpenAI. Per l’uso in produzione, verifica che l’URL dell’immagine sia raggiungibile o che il payload base64 sia valido, quindi controlla che la descrizione restituita sia conforme ai requisiti della tua applicazione per accuratezza, sicurezza e coerenza della formattazione. Gli esempi di Tencent mostrano una gestione standard delle risposte di chat-completions, quindi le pipeline esistenti di validazione e logging possono di solito essere riutilizzate con modifiche minime.