hunyuan-vision API

hunyuan-vision의 기술 사양

hunyuan-vision란?

hunyuan-vision은 OpenAI 호환 API를 통해 제공되는 Tencent Hunyuan의 멀티모달 이미지 이해 모델입니다. Tencent의 공식 예시에서는 사용자가 이미지와 함께 프롬프트를 전송하면 모델이 이미지에 무엇이 보이는지 등과 같은 질문에 답하는 “이미지-텍스트” 스타일 작업에 사용됩니다.

실무적으로, 이는 이미지 캡셔닝, 장면 설명, UI 또는 스크린샷 해석, 제품 이미지 분석, 일반적인 시각적 질의응답처럼 채팅 워크플로에서 시각적 추론이 필요한 애플리케이션에 적합합니다. 특히 OpenAI 스타일 클라이언트를 이미 사용하는 팀에게 통합 패턴이 편리한데, Tencent가 끝점과 API 키 설정만 교체하면 전환할 수 있다고 명시하고 있기 때문입니다.

hunyuan-vision의 주요 기능

• 멀티모달 이미지 이해: hunyuan-vision은 동일한 요청에서 텍스트와 이미지를 함께 받아, 업로드된 시각 자료에 대한 이미지 인지 기반 대화 및 질의응답을 수행합니다.
• OpenAI 호환 인터페이스: Chat Completions와 동일한 일반 요청 구조로 제공되어, 기존 AI 애플리케이션의 마이그레이션 노력을 줄여 줍니다.
• 유연한 이미지 입력 방식: 공식 예시는 표준 원격 이미지 URL과 base64 인코딩 데이터 URL을 모두 지원하여, 공개 에셋이나 로컬로 처리한 파일 모두에 유용합니다.
• SDK 친화적 통합: Python, Node.js, Go 및 cURL 스타일 HTTP 요청의 OpenAI SDK 사용 방법을 Tencent가 명확히 문서화하고 있어, 기존 백엔드 서비스에 쉽게 내장할 수 있습니다.
• 채팅 기반 워크플로: 채팅 완성 모델로 제공되기 때문에, 이미 messages 중심 구조를 사용하는 대화형 앱, 도우미, 툴체인에 자연스럽게 맞습니다.
• 사용량 기반 이미지 토큰 산정: 이미지 비용은 크기에 따라 달라지며, 이미지당 토큰 소비가 고정값이 아닌 범위로 문서화되어 있습니다.

hunyuan-vision에 접근하고 통합하는 방법

1단계: API 키 발급

hunyuan-vision에 접근하려면 먼저 제공자의 콘솔에서 API 키를 생성하고 안전하게 보관합니다. Tencent는 OpenAI 호환 Hunyuan API에 대한 API 키 기반 접근을 문서화하고 있으며, 요청 시 키는 Bearer 토큰으로 전달됩니다. HUNYUAN_API_KEY와 같은 환경 변수에 보관하고, 클라이언트 사이드 코드나 공개 저장소에 노출하지 마십시오.

2단계: hunyuan-vision API로 요청 보내기

OpenAI 호환 엔드포인트를 사용하고, 모델 이름으로 hunyuan-vision을 지정합니다.

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": "이 이미지에는 무엇이 있습니까?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/image.jpg"
            }
          }
        ]
      }
    ]
  }'

OpenAI 호환 SDK를 사용하려면 클라이언트를 Hunyuan 기본 URL로 지정할 수도 있습니다:

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": "이 이미지를 설명해 주세요."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg"
                    },
                },
            ],
        }
    ],
)

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

이 요청 구조는 hunyuan-vision에 대한 Tencent의 공식 OpenAI 호환 예시를 따릅니다.

3단계: 결과 수신 및 검증

OpenAI 호환 SDK를 사용할 때 보통 response.choices[0].message.content에서 첫 번째 completion choice의 생성된 답변을 읽습니다. 프로덕션 환경에서는 이미지 URL이 접근 가능한지 혹은 base64 페이로드가 유효한지 확인하고, 반환된 설명이 애플리케이션의 정확성, 안전성, 형식 일관성 요구사항을 충족하는지 검토하십시오. Tencent의 예시는 표준 채팅 완성 응답 처리를 보여 주므로, 기존 검증 및 로깅 파이프라인을 최소한의 변경으로 재사용할 수 있는 경우가 많습니다.