요약: 이 글에서는 OpenAI Python SDK로 비스트리밍 방식으로 Tencent Hunyuan Hy4 API를 호출해 첫 텍스트 전용 요청을 끝까지 실행해 보고, 결과 검증, 비용 추정, 청구서 대조, 흔한 오류 처리 방법을 설명합니다.
바로 답: Tencent Hunyuan Hy4 API는 APIYI의 OpenAI 호환 인터페이스를 통해 연결할 수 있어요. 설정 세 가지만 준비하면 첫 요청을 보낼 수 있습니다.
- 키:
api.apiyi.com/token에서 만들고 환경 변수APIYI_API_KEY에 넣어 두세요. - SDK Base URL:
https://api.apiyi.com/v1 - 모델 ID:
hy4
해당 HTTP 엔드포인트는 POST https://api.apiyi.com/v1/chat/completions입니다. 2026-11-21 기준 가격표에서 Hy4의 100만 토큰당 가격은 캐시 미적중 입력 $0.85, 출력 $2.55, 캐시 읽기 $0.045입니다. 실제 과금은 APIYI 가격표를 기준으로 하며, 주소는 docs.apiyi.com/models(Tencent 카테고리)입니다.
타임라인은 이렇습니다. Tencent는 11월 4일 Hy4 정식 버전을 발표했고, 11월 20일 가중치를 공개했어요. APIYI는 가중치 공개 이전에 이미 이 모델을 등록했으며, 등록 공지는 docs.apiyi.com/news/hy4-launch에서 볼 수 있습니다. 공지에 이미 스트리밍 예제가 있으니, 이 글에서는 나머지 네 가지, 즉 비스트리밍 호출, 결과 검증, 청구서 대조, 실패 트러블슈팅만 다룹니다. 공지에서는 Hy4가 이미지 입력을 지원한다고 언급했지만, 이 글에서는 텍스트만 시연합니다. 동영상, Responses 인터페이스, Computer Use는 이 글의 범위가 아니며, 본문에는 실측 데이터도 없습니다.

텐센트 훈위안 Hy4 API 연동 지식 지도와 읽기 순서
전체 흐름은 네 단계로 나뉘고, 앞 단계의 결과물이 다음 단계의 입력이 돼요. 번호 순서대로 읽는 걸 권장하고, 4번 섹션은 오류가 났을 때 따로 찾아봐도 괜찮아요.
| 단계 | 해당 본문 | 이 위치에 둔 이유 | 검수 기준 |
|---|---|---|---|
| 요청 준비 | 1.1, 1.2 | 엔드포인트, 모델명, Key를 잘못 쓰면 뒤 단계가 전부 실패해요 | SDK 임포트가 되고, 환경 변수에서 Key를 읽을 수 있고, 코드에 평문 Key가 없음 |
| 첫 호출 | 2.1, 2.2 | 고객 데이터가 들어가지 않은 짧은 텍스트로 먼저 연결이 뚫렸는지 확인해요 | 반환 내용이 “产品=混元、版本=Hy4″이고 잘림이 없으며, usage와 request ID를 저장해 둠 |
| 청구서 확인 | 3.1, 3.2 | 연결이 뚫린 다음 비용을 추정해서 호출량을 키울 수 있을지 판단해요 | 추정값이 콘솔 사용 로그와 항목별로 맞아떨어짐 |
| 실패 트러블슈팅 | 4 | 어느 단계든 실패하면 오류 코드와 오류 본문으로 원인을 찾아요 | 설정 오류, 권한 문제, 레이트 리밋, 타임아웃을 구분하고 재시도 가능 여부를 판단할 수 있음 |

To Know: Hy4 API 관련 용어
| 용어 | 간단한 설명 |
|---|---|
| 비스트리밍(stream=False) | 모델이 생성을 마친 뒤 결과 전체를 한 번에 반환해서 내용과 사용량을 통째로 확인하기 좋아요 |
| finish_reason | 이번 생성이 끝난 이유. stop은 정상 종료, length는 길이 상한에 걸려 잘렸다는 뜻이에요 |
| usage | 응답에 담기는 토큰 사용량 필드로, 대표적으로 prompt_tokens(입력)와 completion_tokens(출력)가 있어요 |
| request ID | 단일 요청의 식별자로, 로그에서 이번 호출을 찾을 때 써요. 모든 응답에 반드시 붙는 건 아니에요 |
| 캐시 읽기 | 입력 중 캐시에 적중한 부분은 별도의 캐시 읽기 단가로 과금돼요 |
| 그룹(Default/SVIP) | 토큰이 속한 그룹으로, 이 토큰이 어떤 모델을 호출할 수 있는지 결정해요 |
1. 텐센트 훈위안 Hy4 API 요청 준비
1.1 Hy4 모델과 엔드포인트 구성
먼저 설정 항목을 하나씩 꼼꼼히 확인해 주세요. 첫 호출이 실패하는 경우 대부분이 이 단계에서 갈려요.
| 설정 항목 | 값 | 설명 |
|---|---|---|
| SDK base_url | https://api.apiyi.com/v1 |
/v1까지만 적어요. SDK가 자동으로 /chat/completions를 붙여 줘요 |
| HTTP 엔드포인트 | POST https://api.apiyi.com/v1/chat/completions |
SDK를 쓰지 않고 HTTP 요청을 직접 보낼 때 쓰는 주소예요 |
| 모델 ID | hy4 |
정식 버전의 모델명이고, 소문자 그대로 입력해요 |
| 사용 가능 그룹 | Default, SVIP | 토큰이 속한 그룹에 Hy4가 포함되어 있어야 해요 |
| 출력 방식 | stream=False |
이 글에서는 전부 비스트리밍 방식을 사용해요 |
가장 흔한 실수는 전체 엔드포인트를 base_url에 넣는 거예요. SDK가 이 주소 뒤에 /chat/completions를 한 번 더 붙이기 때문에 경로가 중복되고, 결국 404가 돌아와요. 호환 인터페이스의 전체 설명은 docs.apiyi.com/api-capabilities/openai/compatible에서 확인할 수 있어요.
1.2 OpenAI SDK 설치와 Key 안전하게 보관하기
공식 Python SDK 프로젝트 주소는 github.com/openai/openai-python이에요. 시스템에 이미 설치된 패키지와 버전이 충돌하지 않도록 가상 환경에 설치하는 걸 권장해요:
python -m venv .venv
source .venv/bin/activate # Windows에서는: .venv\Scripts\activate
python -m pip install openai
Key는 api.apiyi.com/token에서 만들어요. 만들 때 토큰이 속한 그룹에서 Hy4를 호출할 수 있는지 꼭 확인해 주세요. Key를 받으면 코드 파일이 아니라 현재 터미널의 환경 변수에 넣어요:
export APIYI_API_KEY="你的令牌" # Windows PowerShell: $env:APIYI_API_KEY="你的令牌"
Key를 관리할 때는 다음 몇 가지에 신경 써 주세요:
- 코드는
os.environ['APIYI_API_KEY']로만 Key를 읽어요. 환경 변수가 설정되어 있지 않으면getpass로 직접 입력받는데, 입력 내용은 화면에 표시되지 않아요. .env파일에 Key를 저장한다면.gitignore에 추가해서 저장소에 커밋되지 않도록 해요.- 스크린샷, 로그, 티켓 등에 Key가 보이면 먼저
sk-***같은 마스크로 바꿔 주세요.
검증: 터미널에서 python -c "import openai, os; print(openai.__version__, bool(os.environ.get('APIYI_API_KEY')))"를 실행해 보세요. 버전 번호와 True가 출력되면 이 단계는 완료된 거예요.
2. OpenAI SDK로 첫 번째 Hy4 요청 보내기
2.1 전체 비스트리밍 Python 예제
이 첫 요청은 아주 단순한 작업 하나만 해요. 공개된 문장 하나에서 제품명과 버전 번호를 뽑아내는 일이죠. 고객 데이터는 전혀 들어가지 않아요. 이렇게 설계한 데는 두 가지 이유가 있어요. 첫째, 출력이 짧아서 비용이 적게 들어요. 둘째, 정답이 하나뿐이라 맞고 틀림을 판단하기 쉬워요.
import os
import re
from getpass import getpass
from openai import OpenAI
key = os.environ.get("APIYI_API_KEY") or getpass("输入 APIYI_API_KEY:")
PROMPT = "仅从这句话提取产品和版本:腾讯混元 Hy4 正式版已上线。请只写一行:产品=…;版本=…"
with OpenAI(
base_url="https://api.apiyi.com/v1", # APIYI OpenAI 호환 인터페이스
api_key=key,
timeout=60.0,
max_retries=0, # 자동 재시도를 끄고, 실패하면 사람이 재전송 여부를 판단
) as client:
result = client.chat.completions.create(
model="hy4",
messages=[{"role": "user", "content": PROMPT}],
stream=False,
)
request_id = getattr(result, "_request_id", None)
print("request_id:", request_id if request_id else "响应未提供")
if not result.choices:
raise SystemExit("未通过:choices 为空,没有返回正文")
choice = result.choices[0]
content = (choice.message.content or "").strip()
print("finish_reason:", choice.finish_reason)
print("content:", content)
usage = getattr(result, "usage", None)
prompt_tokens = getattr(usage, "prompt_tokens", None) if usage else None
completion_tokens = getattr(usage, "completion_tokens", None) if usage else None
print("prompt_tokens:", prompt_tokens if prompt_tokens is not None else "缺失(不按 0 处理)")
print("completion_tokens:", completion_tokens if completion_tokens is not None else "缺失(不按 0 处理)")
def accept(text: str, finish_reason) -> tuple[bool, str]:
if not text:
return False, "正文为空"
if finish_reason == "length":
return False, "输出被截断"
t = re.sub(r"\s+", "", text)
t = t.replace(":", "=").replace(":", "=").replace(";", ";")
prod = re.search(r"产品=([^;\n]+)", t)
ver = re.search(r"版本=([^;\n]+)", t)
if not prod or not ver:
return False, "缺少产品或版本字段"
strip_punct = lambda s: re.sub(r"[。..,,、!!??\"“”'‘’]", "", s)
if "混元" not in strip_punct(prod.group(1)):
return False, f"产品值错误:{prod.group(1)}"
if strip_punct(ver.group(1)) != "Hy4":
return False, f"版本值错误:{ver.group(1)}"
return True, "通过"
ok, reason = accept(content, choice.finish_reason)
print("验收:", reason)
예제에 쓰인 몇 가지 설정은 짚고 넘어갈 만해요.
max_retries=0은 SDK의 자동 재시도를 꺼요. 4절에서 다루겠지만, 타임아웃이 나도 서버 쪽에서는 이미 요청 수행이 끝났을 수 있어요. 자동으로 다시 보내면 중복 과금이 생길 수 있으니, 재시도 여부는 사람이 판단해야 해요.with문은 호출이 끝난 뒤 연결을 닫아 줘요.- usage 필드가 없을 때 코드는 “缺失”이라고 분명히 출력해요. 0으로 처리하지 않기 때문에 나중에 비용을 계산할 때 빠뜨리는 일이 없어요.
응답 구조에 대한 더 자세한 설명은 docs.apiyi.com/api-capabilities/openai/response-handling에서 볼 수 있어요.
2.2 첫 Hy4 요청의 검수 기준
검수 시에는 message.content 안의 두 필드만 확인해요. 제품 값에 “混元”이 포함되어 있고, 버전 값이 “Hy4″여야 하죠. 전각·반각 콜론과 세미콜론, 문말 구두점의 차이는 허용돼요. 아래는 요구 사항을 충족하는 한 줄 출력인데, 이건 예시 형식일 뿐 실제 응답이 아니에요:
产品=腾讯混元;版本=Hy4
다음 경우는 일률적으로 불합격으로 판정하고, “비슷해 보인다”는 이유로 통과시켜선 안 돼요:
| 상황 | 판정 | 원인 |
|---|---|---|
| choices가 비었거나 content가 빈 문자열 | 불합격 | 본문을 받지 못했다는 뜻이니, 연결 경로가 실제로 제대로 동작하지 않은 거예요 |
finish_reason이 length |
불합격 | 출력이 잘렸으니 결과가 불완전해요 |
| 버전이 Hy3, Hunyuan 등 다른 값으로 표기됨 | 불합격 | 필드 값이 틀렸어요 |
| 구두점·공백·콜론의 전각/반각만 다름 | 합격 | 허용되는 형식 차이예요 |
검수에 통과하면 request ID(응답에 있으면), 요청 시간, 모델명, prompt_tokens, completion_tokens를 기록해 두세요. 3.2절에서 청구서를 대조할 때 이 정보들이 쓰여요.
3. Hy4 API 비용 추정 및 확인
3.1 가격표로 배치 작업 비용 추정하기
첫 요청의 입력은 매우 짧아서 비용이 거의 무시할 수 있는 수준이므로, 이를 가지고 비용을 추정하는 것은 큰 의미가 없어요. 아래에서는 예시의 짧은 요청과 무관한 가상 시나리오로 바꿔 볼게요: 어떤 작업의 입력이 10만 token이고 모두 캐시 미스이며, 출력이 2만 token인 경우예요. 입력과 출력을 각각의 단가로 계산하면 다음과 같아요:
| 과금 항목 | 가정 사용량 | 단가(백만 token당) | 비용 |
|---|---|---|---|
| 캐시 미스 입력 | 100,000 | $0.85 | $0.085 |
| 출력 | 20,000 | $2.55 | $0.051 |
| 합계 | — | — | $0.136 |
계산 과정은 0.1 × 0.85 + 0.02 × 2.55 = 0.136이에요. 추정할 때 두 가지에 주의해야 해요:
- 출력 단가는 캐시 미스 입력 단가의 3배예요. 출력량이 큰 작업은 비용이 주로 출력에서 결정돼요.
- completion_tokens에 이미 모델의 사고(thinking) 부분이 포함되어 있다면, 사고 비용을 따로 한 번 더 더하지 마세요. 그렇지 않으면 중복 계산이 돼요.
3.2 캐시 버킷과 실제 사용 로그 구분하기
‘캐시 읽기’는 별도로 과금되는 부분이지만, 응답마다 필드를 나누는 방식이 같지 않을 수 있어서, 결과를 정확히 보장해 주는 보편적인 필드명은 없어요. 신뢰할 수 있는 방법은 먼저 청구서에서 캐시에 히트한 token이 총 입력에 이미 포함되어 있는지 확인하는 거예요.
청구서에서 캐시 부분이 이미 총 입력에 포함되어 있다고 확인되면, 총 입력에서 캐시 부분을 한 번 빼고 나서 각각 단가를 적용하세요. 아래에서는 3.1의 가정을 그대로 이어가면서, 추가로 10만 입력 중 4만이 캐시에 히트했다고 가정해 볼게요:
| 과금 항목 | 가정 사용량 | 단가(백만 token당) | 비용 |
|---|---|---|---|
| 캐시 미스 입력 | 60,000 | $0.85 | $0.051 |
| 캐시 읽기 | 40,000 | $0.045 | $0.0018 |
| 출력 | 20,000 | $2.55 | $0.051 |
| 합계 | — | — | $0.1038 |

추정값은 참고용일 뿐이며, 최종적으로는 사용 로그를 기준으로 해요. 확인 방법은 콘솔 api.apiyi.com/log에서 해당 기록을 필터링하는 거예요:
- 요청 시간으로 범위를 좁혀요.
- 응답에 request ID가 제공되었다면, 그것으로 이번 요청을 정확히 찾아요.
- 모델이
hy4인지, 토큰이 코드에서 실제로 사용한 토큰과 일치하는지 확인해요. - 로그의 입력, 캐시, 출력 사용량과 청구 금액을 추정값과 비교해 일치하는지 확인해요.
로그 필드의 구체적인 의미는 docs.apiyi.com/faq/log-billing-explained에서 확인할 수 있어요.
4. Hy4 API 실패 트러블슈팅
문제를 해결할 때는 먼저 HTTP 상태 코드를 확인하고, 그다음 오류 본문에 담긴 구체적인 정보를 읽어야 해요. 상태 코드만 보면 판단을 잘못하기 쉬운데, 예를 들어 같은 429라도 원인은 전혀 다를 수 있거든요. 2.1절의 원래 요청 부분에서 SDK 예외를 캐치하세요. 연결 타임아웃은 APITimeoutError로, 그 외 연결 실패는 APIConnectionError로 확인하고, 오류 응답을 받으면 APIStatusError에서 status_code, request_id, 오류 본문을 기록하세요. 먼저 현재 요청의 결과를 판단한 뒤 재시도 여부를 결정하고, 피드백 전에는 오류 본문을 마스킹하세요. 처리 순서는 다음과 같아요.
| 오류 | 우선 확인 | 재시도 여부 |
|---|---|---|
| 401 | Key가 올바른지, 만료되지는 않았는지, 그리고 base_url이 https://api.apiyi.com/v1인지 |
설정을 수정하기 전에는 재시도하지 않음 |
| 403 | 오류 본문을 보고 그룹 권한 문제인지 판단하고, 토큰이 속한 그룹에 Hy4가 포함되어 있는지 확인 | 권한을 수정하기 전에는 재시도하지 않음 |
| 404 | 경로에 /chat/completions가 중복으로 붙지 않았는지, 모델명이 hy4인지 |
설정을 수정하기 전에는 재시도하지 않음 |
| 429 | 오류 본문을 보고 일시적 속도 제한인지 할당량 부족인지 판단 | 일시적 속도 제한은 제한된 횟수만큼 백오프 재시도 가능, 할당량 부족은 먼저 충전하거나 할당량을 조정해야 함 |
| 연결 오류 | 네트워크, 프록시, DNS가 정상인지, base_url의 프로토콜과 도메인이 올바른지 | 네트워크가 복구되면 재시도 가능 |
| 타임아웃 | 먼저 api.apiyi.com/log에서 시간 기준으로 조회해 요청이 이미 실행되었는지 확인 |
이미 실행되었다면 재전송하지 말고, 실행되지 않았을 때만 재시도 |
429와 타임아웃, 이 두 가지 경우는 특별히 짚고 넘어갈게요.
- 429의 백오프 재시도: 일시적 속도 제한에만 적용돼요. 재시도 횟수에는 상한을 두고, 간격은 매번 점점 늘려야 해요. 할당량이 부족할 때는 아무리 재시도해도 성공하지 못해요.
- 타임아웃: 클라이언트가 60초 안에 응답을 받지 못했다고 해서 서버가 이 요청을 처리하지 않았다는 뜻은 아니에요. 서버가 이미 처리를 마쳤다면 그대로 재전송할 경우 한 번 더 실행되어 비용도 한 번 더 청구돼요. 그래서 먼저 로그를 확인해 요청이 실행되지 않았음을 확인한 뒤 다시 보내야 해요.
기술 지원에 문의해야 할 경우, 제출 전에 오류 본문과 로그에 있는 Key, 고객 데이터 등 민감한 정보를 먼저 마스킹하고, 상태 코드, 요청 시간, 모델명, request ID를 함께 첨부하세요. 오류 정보의 보관 및 제출 방법은 docs.apiyi.com/api-manual/error-reporting에서 확인할 수 있어요.
트러블슈팅을 모두 마친 뒤 2.1의 예제로 다시 한 번 실행해 보세요. 전체 흐름이 아래 세 가지 조건을 동시에 만족해야 통과예요.
- 검수 함수가 “통과”를 출력한다.
- finish_reason이
length가 아니다. - 콘솔 로그에서 같은 시간대에 모델이
hy4인 기록을 찾을 수 있고, 사용량이 로컬에 기록된 usage와 일치한다.
