Hunyuan Video Fast는 Novita AI에서 POST https://api.novita.ai/v3/async/hunyuan-video-fast 엔드포인트로 사용할 수 있습니다. 이는 Tencent의 오픈소스 Hunyuan Video 기반 모델의 속도 최적화 변형으로, 표준 버전에 비해 생성 시간을 단축하지만 모션 충실도가 일부 희생됩니다. 이를 통해 처리량이 중요한 파이프라인, 프롬프트 반복, 그리고 최고의 시네마틱 품질보다 전환 속도가 더 중요한 검증 워크플로우에 실용적입니다.
모든 Novita 비동기 비디오 API와 마찬가지로 요청 시 task_id를 반환하고 작업이 완료되면 비디오 URL을 제공합니다. 이 가이드에서는 엔드포인트, 요청 형식, 작동하는 Python 및 cURL 예제, 그리고 표준 모델과 비교하여 빠른 변형이 적합한 상황을 다룹니다.
Hunyuan Video Fast vs 표준: 언제 사용해야 할까
빠른 변형은 생성 전환 속도와 요청 볼륨이 최고의 시각적 품질보다 더 중요할 때 적합합니다. 표준 Hunyuan Video는 생성당 더 높은 충실도의 모션과 더 나은 프롬프트 준수를 제공합니다. 빠른 변형은 이 시간을 크게 단축하며, 다음과 같은 경우에 유용합니다:
- 프롬프트 반복 — 최종 품질 렌더링에 투자하기 전에 다양한 변형을 저렴하게 테스트
- 고처리량 파이프라인 — 클립당 지연 시간이 처리량에 직접 영향을 미치는 배치 콘텐츠 생성
- 스테이징 및 내부 검토 — 공유 가능한 출력물을 빠르게 얻은 후 최종 제공 시 표준으로 전환
- 저지연 애플리케이션 — 응답 시간 예산이 빡빡한 프로덕션 워크플로우
출력 품질이 주요 제약 조건인 경우(방송, 최종 제공, 사실적인 모션)에는 표준 Hunyuan Video 엔드포인트를 대신 사용하세요.
1단계: Novita AI API 키 얻기
novita.ai에 가입하고 키 관리 페이지에서 API 키를 생성하세요. 신규 계정에는 무료 크레딧이 제공됩니다. 키를 환경 변수로 저장하고 소스 파일에 하드코딩하지 마세요.
export NOVITA_API_KEY="your_api_key_here"
2단계: 엔드포인트 및 모델 ID
| 필드 | 값 |
|---|---|
| 제출 엔드포인트 | POST https://api.novita.ai/v3/async/hunyuan-video-fast |
| 결과 조회 | GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
| 인증 헤더 | Authorization: Bearer $NOVITA_API_KEY |
| 콘텐츠 유형 | application/json |
공식 API 참조: novita.ai/docs/api-reference/model-apis-hunyuan-video-fast
3단계: 첫 번째 요청 보내기
프롬프트와 출력 설정을 포함한 생성 요청을 제출하세요:
curl -s -X POST https://api.novita.ai/v3/async/hunyuan-video-fast \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A red fox running through a snowy forest at dawn, slow motion, cinematic wide shot",
"negative_prompt": "blurry, low quality, distorted, watermark",
"width": 1280,
"height": 720,
"seed": -1
}'
API는 즉시 task_id를 반환합니다:
{
"task_id": "hunyuan-fast-abc123"
}
이 응답에는 비디오가 포함되어 있지 않습니다. task_id를 저장하고 다음 단계에서 사용하세요.
4단계: 비디오 결과를 위해 폴링
curl -s "https://api.novita.ai/v3/async/task-result?task_id=hunyuan-fast-abc123" \
-H "Authorization: Bearer $NOVITA_API_KEY"
task_status가 TASK_STATUS_SUCCEED가 될 때까지 폴링하세요:
{
"task_status": "TASK_STATUS_SUCCEED",
"videos": [
{
"video_url": "https://cdn.novitai.com/output/...",
"video_url_ttl": 3600,
"video_type": "mp4"
}
]
}
video_url을 신속하게 다운로드하거나 저장하세요. video_url_ttl초 후에 만료됩니다.
작업 상태 값
| 상태 | 의미 |
|---|---|
TASK_STATUS_QUEUED |
요청이 접수되었으며 실행 대기 중 |
TASK_STATUS_PROCESSING |
생성 진행 중 |
TASK_STATUS_SUCCEED |
완료 — videos[0].video_url에서 비디오 URL 사용 가능 |
TASK_STATUS_FAILED |
생성 실패 — 응답에서 실패 이유 확인 |
Python 예제
import os
import time
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_video(
prompt: str,
negative_prompt: str = "",
width: int = 1280,
height: int = 720,
seed: int = -1,
) -> str:
payload = {
"prompt": prompt,
"negative_prompt": negative_prompt,
"width": width,
"height": height,
"seed": seed,
}
resp = requests.post(
f"{BASE_URL}/v3/async/hunyuan-video-fast",
headers=HEADERS,
json=payload,
)
resp.raise_for_status()
return resp.json()["task_id"]
def poll_result(task_id: str, interval: int = 5, timeout: int = 300) -> dict:
deadline = time.time() + timeout
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}/v3/async/task-result",
headers=HEADERS,
params={"task_id": task_id},
)
resp.raise_for_status()
data = resp.json()
status = data.get("task_status", "")
if status == "TASK_STATUS_SUCCEED":
return data
if status == "TASK_STATUS_FAILED":
raise RuntimeError(f"Task failed: {data}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")
if __name__ == "__main__":
task_id = submit_video(
prompt="A red fox running through a snowy forest at dawn, slow motion, cinematic wide shot",
negative_prompt="blurry, low quality, distorted, watermark",
width=1280,
height=720,
)
print(f"Task submitted: {task_id}")
result = poll_result(task_id)
for video in result.get("videos", []):
print(f"Video URL (expires in {video['video_url_ttl']}s): {video['video_url']}")
cURL 예제
# Step 1: Submit the generation request
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/hunyuan-video-fast \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A timelapse of a city skyline transitioning from dusk to night, cinematic",
"negative_prompt": "blurry, low quality, distorted",
"width": 1280,
"height": 720,
"seed": 42
}' | jq -r '.task_id')
echo "Task ID: $TASK_ID"
# Step 2: Poll until complete
while true; do
RESULT=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
-H "Authorization: Bearer $NOVITA_API_KEY")
STATUS=$(echo "$RESULT" | jq -r '.task_status')
if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
echo "$RESULT" | jq -r '.videos[0].video_url'
break
elif [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
echo "Failed: $RESULT"
break
fi
echo "Status: $STATUS — waiting..."
sleep 5
done
주요 매개변수
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
prompt |
문자열 | 예 | 비디오 장면, 주제, 동작 및 스타일에 대한 텍스트 설명 |
negative_prompt |
문자열 | 아니요 | 출력에서 피해야 할 요소 (예: “blurry, low quality”) |
width |
정수 | 아니요 | 출력 너비(픽셀) — 지원되는 값은 API 문서 확인 |
height |
정수 | 아니요 | 출력 높이(픽셀) — width와 함께 해상도 설정 |
seed |
정수 | 아니요 | 고정 정수를 설정하여 동일한 출력 재현; -1은 무작위 |
지속 시간 옵션, 최대 해상도 제약 조건 및 모델별 필드를 포함한 전체 매개변수 목록은 Hunyuan Video Fast API 참조를 참조하세요.
가격 및 제한 사항
현재 비디오당 가격은 Novita AI 모델 페이지에서 확인하세요. 비디오 생성 가격은 일반적으로 생성된 클립당이며 해상도와 지속 시간에 따라 다릅니다. 프로덕션 워크로드에 대한 비용 모델을 구축하기 전에 가격 페이지를 확인하세요.
배포 전에 공식 문서에서 다음 제한 사항을 확인하세요:
- 최대 프롬프트 문자 길이
- 지원되는 해상도 값(너비 × 높이 조합)
- 최대 비디오 지속 시간(초)
- API 키당 속도 제한 및 동시 작업 제한
빠른 변형은 일반적으로 계산 시간이 줄어들기 때문에 표준 모델보다 클립당 비용이 낮습니다. Novita 가격 페이지에서 현재 차이를 확인하세요.
문제 해결
401 Unauthorized — API 키가 없거나, 유효하지 않거나, 만료되었습니다. NOVITA_API_KEY가 설정되어 있고 키가 Novita AI 대시보드에서 활성 상태인지 확인하세요.
422 Unprocessable Entity — 필수 매개변수가 누락되었거나 값이 범위를 벗어났습니다. prompt가 비어 있지 않은지, width/height 값이 API 문서의 지원 세트에 있는지 확인하세요.
작업이 TASK_STATUS_PROCESSING 상태로 유지됨 — 생성이 아직 실행 중입니다. 빠른 변형은 표준보다 빠르게 완료되지만, 더 높은 해상도와 더 긴 지속 시간은 더 많은 시간이 소요됩니다. 큰 출력의 경우 폴링 제한 시간을 늘리세요.
video_url이 403 또는 404 반환 — URL이 만료되었습니다(video_url_ttl 경과). 프로덕션에서는 TASK_STATUS_SUCCEED 직후에 비디오를 다운로드하거나 전송하세요. 호스팅된 URL을 영구 저장소로 의존하지 마세요.
특정 프롬프트 유형에서 일관된 품질 문제 — prompt 개선 접근 방식으로 전환: 주제, 동작, 카메라 각도 및 스타일을 명시적으로 설명하세요. 일반적인 아티팩트에 대해 negative_prompt 항목을 추가하세요. 사용 사례에 여전히 품질이 충분하지 않다면 표준 Hunyuan Video 엔드포인트를 평가하세요.
FAQ
Novita AI에서 Hunyuan Video Fast의 엔드포인트는 무엇인가요?
POST https://api.novita.ai/v3/async/hunyuan-video-fast. API는 비동기식입니다: 요청을 제출하고 task_id를 받은 다음, GET https://api.novita.ai/v3/async/task-result?task_id=<id>를 task_status가 TASK_STATUS_SUCCEED가 될 때까지 폴링합니다.
Hunyuan Video Fast는 표준 Hunyuan Video와 어떻게 다른가요?
빠른 변형은 생성 속도에 최적화되어 작업 제출부터 완료된 비디오까지의 시간을 줄입니다. 단점은 모션 충실도와 세밀한 프롬프트 준수가 표준 모델보다 낮다는 것입니다. 프롬프트 반복, 고처리량 배치 작업 또는 스테이징에는 빠른 변형을 사용하고, 최종 품질 출력에는 표준을 사용하세요.
특정 비디오 지속 시간을 설정할 수 있나요?
지원되는 지속 시간 매개변수는 API 참조를 확인하세요. 일부 Novita 비디오 API는 명시적인 duration 필드를 제공하고, 다른 API는 모델 기본값을 사용합니다. 기본 클립 길이를 가정하기 전에 확인하세요.
특정 비디오 출력을 재현하려면 어떻게 해야 하나요?
seed를 고정 정수로 설정하세요. 동일한 seed, prompt, width, height 조합은 실행 간에 일관된 출력을 생성해야 합니다.
Hunyuan Video Fast는 이미지-투-비디오를 지원하나요?
Novita AI의 Hunyuan Video Fast는 텍스트-투-비디오 모델입니다. Novita에서 이미지-투-비디오 생성을 위해서는 Novita 모델 페이지에서 Kling, Vidu 또는 Wan과 같은 사용 가능한 I2V 모델을 확인하세요.
Novita AI에서 Hunyuan Video Fast의 비용은 얼마인가요?
현재 가격은 novita.ai/models에서 확인하세요. 비디오 모델의 클립당 가격은 변경될 수 있으므로 프로덕션 비용 추정을 구축하기 전에 항상 가격 페이지를 확인하세요.
Hunyuan Video Fast는 프로덕션 비디오 파이프라인에 적합한가요?
적절한 처리를 통해 그렇습니다. 비동기 작업 제출을 중심으로 파이프라인을 설계하고, 상태 추적을 위해 task_id를 저장하고, 완료 직후(video_url_ttl 만료 전) 비디오를 다운로드하고, TASK_STATUS_FAILED를 재시도 또는 폴백 전략으로 처리하세요.
