튜토리얼
HiAPI API로 happyhorse-1.1/text-to-video를 호출하는 방법: 사용 가능한 curl 및 Python 예제
사용 가능한 통합의 요청 구조, 비동기 폴링 및 기본 오디오 처리
이 페이지에서
이 통합 가이드에서 다루는 내용
이 가이드는 HiAPI 통합 API를 통해 happyhorse-1.1/text-to-video를 호출하는 전 과정을 안내합니다. 다 읽고 나면 텍스트 프롬프트를 제출하고, 완료될 때까지 폴링하며, 생성된 비디오와 그 기본 오디오 트랙을 저장하는 작동하는 요청을 갖게 됩니다. 먼저 요청 구조를 소개하여 코드를 작성하기 전에 요청 페이로드를 이해할 수 있게 하고, 그다음 바로 복사할 수 있는 curl 호출을 제시합니다. 이어서 비디오 생성에 필요한 비동기 폴링 패턴을 설명하고, 마지막으로 모든 내용을 Python으로 옮기면서 기본적인 오류 처리를 추가합니다. 비디오 API 경험이 필요하지 않으며, HiAPI API 키와 터미널 또는 Python 환경만 있으면 됩니다. 목표는 최소하지만 완전한 통합 예제를 제공하여 이를 자신의 파이프라인에 맞게 변형할 수 있도록 하는 것입니다.
happyhorse-1.1/text-to-video의 요청 구조
호출을 시작하기 전에 텍스트-비디오 요청을 구성하는 필드를 이해하면 도움이 됩니다. 이 엔드포인트는 최소한 모델 식별자와 텍스트 프롬프트를 포함하는 JSON 요청 페이로드를 받습니다. 출력 크기와 길이를 제어하는 다른 일반적인 필드도 있지만, 정확한 매개변수 이름과 허용 가능한 값은 HiAPI에서 해당 모델의 문서를 기준으로 해야 합니다. 유효한 요청 페이로드는 일반적으로 다음과 같습니다:
{
"model": "happyhorse-1.1/text-to-video",
"prompt": "일출 무렵, 카메라가 안개 낀 숲을 천천히 가로질러 팬하며 지나간다"
}
페이로드는 평평하게 유지하고 모델 문서에 설명된 필드만 사용하세요. 인식할 수 없는 필드나 형식이 잘못된 타입은 요청이 거부되는 가장 흔한 원인입니다. 확실하지 않다면 model과 prompt만 포함한 최소 페이로드로 시작한 다음 선택적 매개변수를 하나씩 추가하여 문제를 파악하세요.
curl로 첫 요청 보내기
페이로드가 준비되면 curl로 작업을 제출할 수 있습니다. JSON 본문과 Authorization 헤더의 API 키를 포함한 POST 요청을 보냅니다. 응답에는 일반적으로 나중에 상태를 폴링하는 데 사용할 작업 식별자가 포함됩니다. 다음은 작동하는 예제입니다:
curl -X POST https://api.hiapi.ai/v1/video/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "happyhorse-1.1/text-to-video",
"prompt": "일출 무렵, 카메라가 안개 낀 숲을 천천히 가로질러 팬하며 지나간다"
}'
$HIAPI_API_KEY를 실제 키로 바꾸거나 셸에서 내보내세요. 응답은 id 필드(또는 유사한 이름의 식별자)와 작업이 수락되었음을 나타내는 상태를 포함한 JSON입니다. 응답을 주의 깊게 읽으세요: 상태가 수락 상태가 아니라면 계속하기 전에 오류 메시지를 먼저 확인하세요. 이 시점에서 비디오가 이미 준비되었다고 가정하지 마세요. 작업은 방금 대기열에 들어간 것일 뿐입니다.
비동기 폴링 처리
비디오 생성은 즉시 완료되지 않으므로 HiAPI는 최종 비디오 대신 초기 응답에 작업 식별자를 반환합니다. 작업이 종료 상태에 도달할 때까지 상태 엔드포인트를 폴링해야 합니다. 일반적인 패턴은 작업을 제출하고 ID를 얻은 다음 짧은 간격으로 작업 상태를 반복 요청하는 것입니다. 상태가 성공 또는 실패를 나타내면 중지합니다. 다음은 의사 코드 형태의 로직입니다:
- 작업을 제출하고 작업
id를 읽습니다. - 몇 초 기다립니다.
- 해당
id로 작업 상태를 요청합니다. - 상태가 "completed" 또는 "succeeded"이면 출력 URL을 가져오고 루프를 종료합니다.
- 상태가 "failed"이면 오류를 기록하고 종료합니다.
- 그렇지 않으면 다시 기다렸다가 합리적인 최대 시도 횟수에 도달할 때까지 반복합니다.
너무 자주 폴링하지 마세요. 비디오 작업의 경우 각 시도 사이에 몇 초 간격을 두는 것이 일반적으로 충분합니다. 또한 단일 블로킹 응답에 최종 비디오가 포함될 것이라고 기대하지 마세요. 비동기 모델은 의도적으로 설계되었으며 모든 장시간 실행 생성 작업에서 일관되게 적용됩니다.
출력의 기본 오디오
happyhorse-1.1/text-to-video로 생성된 비디오는 출력에 기본 오디오가 포함되어 있습니다. 작업이 완료되면 응답은 이미 오디오 트랙을 포함한 생성된 비디오 파일을 가리킵니다. 오디오를 별도로 생성하거나 가져올 필요가 없습니다. 결과를 저장하고 검증하려면 제공된 URL에서 비디오 파일을 다운로드하고 컨테이너 형식을 유지하세요. 파일을 프로그래밍 방식으로 처리하는 경우 미디어 도구를 사용하여 파일을 검사하는 등 오디오 스트림이 존재하는지 확인하세요. 다운스트림 파이프라인에서 요구하지 않는 한 오디오를 제거하거나 다시 인코딩하지 마세요. 그렇게 하면 품질이 저하되거나 오디오 트랙이 완전히 제거될 수 있습니다. 반환된 파일을 완전한 시청각 자산으로 취급하세요.
Python으로 동일한 요청 보내기
curl 호출을 Python으로 옮기는 것은 간단합니다. 동일한 JSON 페이로드를 재사용하고 폴링 루프를 추가하면 됩니다. 다음 예제는 requests를 사용하며, 각 시도 사이에 대기하고 실패 시 예외를 발생시킵니다. 엔드포인트 경로와 상태 필드 이름은 HiAPI의 happyhorse-1.1/text-to-video 문서에 설명된 내용으로 바꾸세요.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "happyhorse-1.1/text-to-video",
"prompt": "일출 무렵, 카메라가 안개 낀 숲을 천천히 가로질러 팬하며 지나간다",
}
resp = requests.post(f"{BASE}/video/generations", headers=HEADERS, json=payload)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
for attempt in range(60):
status_resp = requests.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS)
status_resp.raise_for_status()
status = status_resp.json()
state = status.get("status")
if state in ("completed", "succeeded"):
video_url = status["output"]["url"]
print("비디오 준비 완료: ", video_url)
break
if state == "failed":
raise RuntimeError(status.get("error", "생성 실패"))
time.sleep(5)
else:
raise TimeoutError("폴링 시간 초과")
이것은 앞서 설명한 "완료될 때까지 폴링" 로직을 따릅니다. raise_for_status()를 사용하여 HTTP 오류를 조기에 노출하고, 합리적인 대기 간격을 유지하여 불필요한 요청을 피하세요.
일반적인 문제 해결
대부분의 통합 문제는 몇 가지 범주로 나눌 수 있습니다. model 필드 누락이나 잘못된 JSON 타입 사용과 같은 페이로드 형식 오류는 즉시 거부됩니다. JSON을 모델 문서와 주의 깊게 대조하세요. 너무 자주 폴링하면 속도 제한이나 불필요한 부하가 발생할 수 있으니 대기 간격을 늘리세요. 초기 응답을 최종 비디오로 착각하는 것도 또 다른 흔한 실수입니다. 반드시 종료 상태에 도달할 때까지 폴링하세요. 인증 오류는 일반적으로 Authorization 헤더가 없거나 형식이 잘못되었음을 의미하므로 API 키가 올바르게 내보내졌는지 확인하세요. 마지막으로 폴링 후 작업이 실패하면 상태 응답의 오류 메시지를 확인하세요. 대개 유효하지 않은 프롬프트나 지원되지 않는 매개변수를 가리킵니다. 이러한 문제를 해결한 후 최소 유효 페이로드로 다시 시도하세요.