hunyuan-vision API

Especificações técnicas do hunyuan-vision

O que é o hunyuan-vision?

hunyuan-vision é o modelo multimodal de compreensão de imagens da Tencent Hunyuan exposto por meio de uma API compatível com a OpenAI. Nos exemplos oficiais da Tencent, ele é usado para tarefas do estilo "imagem para texto", em que o usuário envia um prompt junto com uma imagem e o modelo responde a perguntas sobre o que é mostrado na imagem.

Na prática, isso torna o hunyuan-vision adequado para aplicações que precisam de raciocínio visual em um fluxo de chat, como legendagem de imagens, descrição de cenas, interpretação de interfaces ou capturas de tela, análise de imagens de produto e perguntas e respostas visuais em geral. Seu padrão de integração é especialmente conveniente para equipes que já usam clientes no estilo OpenAI, pois a Tencent afirma que os desenvolvedores podem mudar substituindo apenas o endpoint e a configuração da chave de API.

Principais recursos do hunyuan-vision

• Multimodalidade para compreensão de imagens: o hunyuan-vision aceita conteúdo de texto e imagem na mesma solicitação, permitindo conversas com reconhecimento de imagem e respostas a perguntas sobre visuais enviados.
• Interface compatível com a OpenAI: a Tencent fornece o hunyuan-vision com a mesma estrutura geral de requisição do Chat Completions, o que reduz o esforço de migração para aplicações de IA existentes.
• Métodos flexíveis de entrada de imagem: exemplos oficiais mostram suporte a URLs de imagens remotas padrão, bem como URLs de dados codificados em base64, o que ajuda tanto com ativos públicos quanto com arquivos processados localmente.
• Integração compatível com SDKs: a Tencent documenta explicitamente o uso com SDKs da OpenAI em Python, Node.js, Go e requisições HTTP no estilo cURL, facilitando a incorporação em serviços de backend existentes.
• Fluxo baseado em chat: por ser exposto como um modelo de chat completion, o hunyuan-vision encaixa naturalmente em aplicativos conversacionais, assistentes e toolchains que já estruturam requisições em torno de messages.
• Contabilização de tokens de imagem baseada no uso: a Tencent observa que o custo de imagem depende do tamanho da imagem, com consumo de tokens por imagem documentado como uma faixa, e não um valor fixo.

Como acessar e integrar o hunyuan-vision

Etapa 1: Registre-se para obter uma chave de API

Para acessar o hunyuan-vision, primeiro crie e proteja sua chave de API por meio do console do fornecedor. A Tencent documenta acesso baseado em chave de API para sua API Hunyuan compatível com a OpenAI, e a chave é enviada como um token Bearer nas requisições. Mantenha a chave em uma variável de ambiente como HUNYUAN_API_KEY e evite expô-la em código client-side ou repositórios públicos.

Etapa 2: Envie solicitações para a API do hunyuan-vision

Use o endpoint compatível com a OpenAI e especifique hunyuan-vision como o nome do 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"
            }
          }
        ]
      }
    ]
  }'

Você também pode usar SDKs compatíveis com a OpenAI, apontando o cliente para a URL base do 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)

Essa estrutura de requisição segue os exemplos oficiais compatíveis com a OpenAI da Tencent para o hunyuan-vision.

Etapa 3: Recupere e verifique os resultados

Leia a resposta gerada a partir da primeira opção de completion, normalmente em response.choices[0].message.content ao usar um SDK compatível com a OpenAI. Para uso em produção, verifique se a URL da imagem é acessível ou se sua carga base64 é válida; em seguida, confira se a descrição retornada atende aos requisitos do seu aplicativo em termos de precisão, segurança e consistência de formatação. Os exemplos da Tencent mostram o tratamento padrão de respostas do chat-completions, de modo que pipelines existentes de validação e logging geralmente podem ser reutilizados com mudanças mínimas.