hunyuan-vision API

Spesifikasi Teknis hunyuan-vision

Apa itu hunyuan-vision?

hunyuan-vision adalah model pemahaman gambar multimodal milik Tencent Hunyuan yang diekspos melalui API yang kompatibel dengan OpenAI. Dalam contoh resmi Tencent, model ini digunakan untuk tugas bergaya “image-to-text” di mana pengguna mengirim prompt bersama gambar dan model menjawab pertanyaan seperti apa yang ditampilkan dalam gambar.

Secara praktis, ini membuat hunyuan-vision cocok untuk aplikasi yang memerlukan penalaran visual dalam alur kerja chat, seperti pembuatan keterangan gambar, deskripsi adegan, interpretasi UI atau tangkapan layar, analisis gambar produk, dan tanya jawab visual umum. Pola integrasinya sangat nyaman bagi tim yang sudah menggunakan klien bergaya OpenAI, karena Tencent menyatakan bahwa pengembang dapat beralih hanya dengan mengganti endpoint dan konfigurasi kunci API.

Fitur utama hunyuan-vision

• Multimodal image understanding: hunyuan-vision menerima konten teks dan gambar dalam satu permintaan, memungkinkan percakapan yang menyadari konteks gambar serta tanya jawab tentang visual yang diunggah.
• Antarmuka yang kompatibel dengan OpenAI: Tencent menyediakan hunyuan-vision melalui struktur permintaan yang sama seperti Chat Completions, yang mengurangi upaya migrasi untuk aplikasi AI yang sudah ada.
• Metode input gambar yang fleksibel: Contoh resmi menunjukkan dukungan untuk URL gambar jarak jauh standar serta URL data yang dikodekan base64, yang membantu saat bekerja dengan aset publik atau file yang diproses secara lokal.
• Integrasi ramah SDK: Tencent secara eksplisit mendokumentasikan penggunaan dengan SDK OpenAI di Python, Node.js, Go, dan permintaan HTTP gaya cURL, sehingga mudah ditanamkan ke layanan backend yang ada.
• Alur kerja berbasis chat: Karena diekspos sebagai model chat completion, hunyuan-vision secara alami cocok untuk aplikasi percakapan, asisten, dan toolchain yang sudah menyusun permintaan di sekitar messages.
• Perhitungan token gambar berbasis penggunaan: Tencent mencatat bahwa biaya gambar bergantung pada ukuran gambar, dengan konsumsi token per gambar didokumentasikan sebagai rentang alih-alih jumlah tetap.

Cara mengakses dan mengintegrasikan hunyuan-vision

Langkah 1: Dapatkan Kunci API

Untuk mengakses hunyuan-vision, pertama buat dan amankan kunci API Anda melalui konsol penyedia. Tencent mendokumentasikan akses berbasis kunci API untuk Hunyuan API yang kompatibel dengan OpenAI, dan kunci tersebut dikirim sebagai token Bearer dalam permintaan. Simpan kunci tersebut dalam variabel lingkungan seperti HUNYUAN_API_KEY, dan hindari mengeksposnya di kode sisi klien atau repositori publik.

Langkah 2: Kirim Permintaan ke API hunyuan-vision

Gunakan endpoint yang kompatibel dengan OpenAI dan tentukan hunyuan-vision sebagai nama model.

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

Anda juga dapat menggunakan SDK yang kompatibel dengan OpenAI dengan mengarahkan klien ke URL dasar 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)

Struktur permintaan ini mengikuti contoh resmi Tencent yang kompatibel dengan OpenAI untuk hunyuan-vision.

Langkah 3: Ambil dan Verifikasi Hasil

Baca jawaban yang dihasilkan dari pilihan completion pertama, biasanya response.choices[0].message.content saat menggunakan SDK yang kompatibel dengan OpenAI. Untuk penggunaan produksi, verifikasi bahwa URL gambar dapat dijangkau atau payload base64 Anda valid, lalu periksa deskripsi yang dikembalikan terhadap persyaratan aplikasi Anda terkait akurasi, keamanan, dan konsistensi pemformatan. Contoh Tencent menunjukkan penanganan respons Chat Completions yang standar, sehingga pipeline validasi dan pencatatan yang ada biasanya dapat digunakan kembali dengan perubahan minimal.