PixVerse V4.5는 Novita AI에서 두 개의 비동기 엔드포인트를 통해 사용할 수 있습니다: 텍스트-비디오(T2V)용 POST https://api.novita.ai/v3/async/pixverse-v4.5-t2v 및 이미지-비디오(I2V)용 POST https://api.novita.ai/v3/async/pixverse-v4.5-i2v. 두 엔드포인트 모두 동일한 2단계 비동기 패턴을 따릅니다. 생성 요청을 제출하고 task_id를 받은 다음, 상태가 TASK_STATUS_SUCCEED가 되고 비디오 URL을 사용할 수 있을 때까지 GET /v3/async/task-result를 폴링합니다. 이 가이드는 각 모드에 대해 작동하는 비디오 URL을 얻는 방법을 처음부터 알려줍니다.
이 빠른 시작을 사용해야 하는 경우
PixVerse V4.5를 둘러싼 프로덕션 로직을 작성하기 전에 검증된 작동 요청이 필요할 때 이 가이드를 사용하세요.
T2V는 입력이 전적으로 텍스트(장면 설명, 스토리보드 캡션, 제품 프롬프트)일 때 적합한 방법입니다. I2V는 참조 이미지가 있고 PixVerse가 해당 프레임에서 앞으로 애니메이션을 적용하려는 경우에 사용합니다.
시작하기 전에 알아두어야 할 사항:
- 클립은 최대 1080p에서 5초, 720p 이하에서는 최대 8초입니다.
fast_mode: true는 생성을 가속화하고 비용을 낮추지만 해상도를 720p로 제한합니다.style사전 설정 매개변수(anime,3d_animation,clay,comic,cyberpunk)는 v3.5 전용으로 문서화되어 있습니다. 프로덕션에서 사용하기 전에 V4.5에서 테스트하세요.- I2V 이미지 입력은 jpg, jpeg 또는 png 형식이어야 하며, 최대 10MB, 최소 300×300px, 종횡비는 1:2.5에서 2.5:1 사이여야 합니다.
이 가이드는 PixVerse 웹 인터페이스, 자체 호스팅 또는 미세 조정을 다루지 않습니다. Novita AI에서 호스팅하는 API 경로만 다룹니다.
1단계: Novita API 키 받기
Novita AI 계정을 만들고 API 키 관리로 이동합니다. 키를 생성하고 환경 변수로 내보냅니다:
export NOVITA_API_KEY="your_api_key_here"
키를 버전 관리, 클라이언트 측 번들 및 Docker 이미지 레이어에 포함하지 마세요.
2단계: 엔드포인트 확인
| T2V | I2V | |
|---|---|---|
| 제출 엔드포인트 | POST https://api.novita.ai/v3/async/pixverse-v4.5-t2v |
POST https://api.novita.ai/v3/async/pixverse-v4.5-i2v |
| 결과 엔드포인트 | GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
| API 참조 | T2V 문서 | I2V 문서 |
결과 엔드포인트는 모든 Novita AI 비동기 API에서 공유됩니다. 폴링 루프를 이해하면 모든 모델에 동일하게 작동합니다.
3단계: 첫 번째 T2V 요청 보내기
프롬프트와 원하는 종횡비로 생성을 제출합니다. 기본값(aspect_ratio: "16:9", resolution: "540p", fast_mode: false)은 합리적인 시작점입니다:
curl -s -X POST https://api.novita.ai/v3/async/pixverse-v4.5-t2v \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A time-lapse of cherry blossoms falling in slow motion, soft morning light, cinematic 4K",
"aspect_ratio": "16:9",
"resolution": "720p"
}'
성공적인 200 응답은 다음만 반환합니다:
{
"task_id": "abc123..."
}
task_id를 저장하세요. 이 단계에서는 다른 것은 반환되지 않습니다. 비디오 생성은 비동기적으로 실행됩니다.
4단계: 첫 번째 I2V 요청 보내기
I2V는 시작 이미지를 사용하고 프롬프트에 따라 애니메이션을 적용합니다. image_file 필드는 소스 이미지의 base64로 인코딩된 문자열을 예상합니다:
# 먼저 이미지를 인코딩합니다
IMAGE_B64=$(base64 -w 0 /path/to/your/image.jpg)
curl -s -X POST https://api.novita.ai/v3/async/pixverse-v4.5-i2v \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"prompt\": \"Camera slowly pushes forward, light wind moves through the scene\",
\"image_file\": \"$IMAGE_B64\",
\"resolution\": \"720p\"
}"
응답은 T2V와 동일한 형태입니다:
{
"task_id": "xyz789..."
}
보내기 전에 확인해야 할 주요 이미지 제약 조건:
- 형식: jpg, jpeg 또는 png만 가능
- 파일 크기: 최대 10MB (인코딩 전 확인 — base64는 크기를 약 33% 증가시킵니다)
- 최소 크기: 300×300px
- 종횡비: 1:2.5에서 2.5:1 사이 (세로에서 가로 극단까지)
5단계: 결과 폴링
제출 단계에서 반환된 task_id를 사용하여 작업 결과 엔드포인트를 폴링합니다:
curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
-H "Authorization: Bearer $NOVITA_API_KEY"
task.status 필드는 다음 상태를 순환합니다:
| 상태 | 의미 |
|---|---|
TASK_STATUS_QUEUED |
작업이 대기열에서 기다리고 있습니다 |
TASK_STATUS_PROCESSING |
생성이 실행 중입니다 |
TASK_STATUS_SUCCEED |
비디오가 준비되었습니다. URL이 응답에 있습니다 |
TASK_STATUS_FAILED |
생성 실패. task.reason 확인 |
5~10초마다 폴링합니다. TASK_STATUS_SUCCEED가 나타나면 비디오 URL이 응답 본문에 있습니다. task.eta 필드는 초 단위의 예상 완료 시간을 제공하며, 첫 번째 폴링 시간을 예약하는 데 사용할 수 있습니다.
6단계: 가격 및 제한 확인
Novita AI의 PixVerse V4.5 게시 가격은 5초 클립당 $0.7입니다(2026년 7월 기준 Novita AI의 PixVerse 제품 페이지에서 확인). 비용 추정을 하기 전에 Novita AI 가격 페이지에서 현재 요금을 확인하세요.
fast_mode: true는 더 빠르고 저렴하게 비디오를 생성하지만 해상도는 720p로 제한됩니다. 프로토타이핑이나 품질이 덜 중요한 배치 미리보기 생성에 유용합니다.
속도 제한은 계정 등급에 따라 다릅니다. 현재 등급 임계값은 Novita AI 속도 제한 문서를 확인하세요.
주요 매개변수
T2V 매개변수
| 매개변수 | 유형 | 기본값 | 참고 |
|---|---|---|---|
prompt |
string | — | 필수. 최대 2048자. |
aspect_ratio |
string | 16:9 |
16:9, 4:3, 1:1, 3:4, 9:16 |
resolution |
string | 540p |
360p, 540p, 720p, 1080p. 1080p는 fast_mode: false가 필요합니다. |
negative_prompt |
string | — | 최대 2048자. 피해야 할 사항을 설명합니다. |
fast_mode |
boolean | false |
더 빠르고 저렴하며 720p로 제한됩니다. |
style |
string | — | anime, 3d_animation, clay, comic, cyberpunk. v3.5 전용으로 표시됨 — 프로덕션 사용 전에 테스트하세요. |
seed |
integer | — | 재현성을 위해 설정합니다. 모델 업데이트 후에도 출력이 달라질 수 있습니다. |
I2V 매개변수
| 매개변수 | 유형 | 기본값 | 참고 |
|---|---|---|---|
prompt |
string | — | 필수. 최대 2048자. |
image_file |
string | — | 필수. Base64로 인코딩된 jpg/jpeg/png. 최대 10MB, 최소 300×300px, 종횡비 1:2.5 ~ 2.5:1. |
resolution |
string | 540p |
T2V와 동일한 옵션. |
negative_prompt |
string | — | 최대 2048자. |
fast_mode |
boolean | false |
T2V와 동일. |
style |
string | — | T2V와 동일. |
seed |
integer | — | T2V와 동일. |
참고: I2V에는 aspect_ratio 매개변수가 없습니다. 출력 종횡비는 입력 이미지에서 파생됩니다.
Python 예제 — 전체 비동기 워크플로우
이 예제는 T2V 및 I2V 제출과 폴링 루프를 하나의 스크립트로 다룹니다:
import os
import time
import base64
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai/v3/async"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_t2v(prompt: str, aspect_ratio: str = "16:9", resolution: str = "720p") -> str:
resp = requests.post(
f"{BASE_URL}/pixverse-v4.5-t2v",
headers=HEADERS,
json={
"prompt": prompt,
"aspect_ratio": aspect_ratio,
"resolution": resolution,
},
)
resp.raise_for_status()
return resp.json()["task_id"]
def submit_i2v(prompt: str, image_path: str, resolution: str = "720p") -> str:
with open(image_path, "rb") as f:
image_b64 = base64.b64encode(f.read()).decode("utf-8")
resp = requests.post(
f"{BASE_URL}/pixverse-v4.5-i2v",
headers=HEADERS,
json={
"prompt": prompt,
"image_file": image_b64,
"resolution": resolution,
},
)
resp.raise_for_status()
return resp.json()["task_id"]
def poll_result(task_id: str, interval: int = 8, timeout: int = 300) -> dict:
deadline = time.time() + timeout
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}/task-result",
headers=HEADERS,
params={"task_id": task_id},
)
resp.raise_for_status()
data = resp.json()
status = data.get("task", {}).get("status")
if status == "TASK_STATUS_SUCCEED":
return data
if status == "TASK_STATUS_FAILED":
reason = data.get("task", {}).get("reason", "unknown")
raise RuntimeError(f"Task {task_id} failed: {reason}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")
if __name__ == "__main__":
# 텍스트-비디오
t2v_task = submit_t2v(
prompt="A lone lighthouse on a rocky coast at dusk, waves crashing, golden sky",
aspect_ratio="16:9",
resolution="720p",
)
print(f"T2V task submitted: {t2v_task}")
t2v_result = poll_result(t2v_task)
print("T2V result:", t2v_result)
# 이미지-비디오 — 실제 이미지 경로로 바꾸세요
# i2v_task = submit_i2v(
# prompt="Gentle wind moves through the scene, slow camera pull-back",
# image_path="./reference.jpg",
# resolution="720p",
# )
# print(f"I2V task submitted: {i2v_task}")
# i2v_result = poll_result(i2v_task)
# print("I2V result:", i2v_result)
cURL 예제
빠른 모드 T2V:
curl -s -X POST https://api.novita.ai/v3/async/pixverse-v4.5-t2v \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A hyperrealistic ocean wave cresting and breaking on shore, slow motion, golden hour",
"aspect_ratio": "9:16",
"resolution": "720p",
"fast_mode": true,
"negative_prompt": "blurry, low quality, watermark"
}'
재현성을 위한 시드 설정 T2V:
curl -s -X POST https://api.novita.ai/v3/async/pixverse-v4.5-t2v \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Neon-lit cyberpunk street at night, rain reflections, hovering vehicles",
"aspect_ratio": "16:9",
"resolution": "1080p",
"seed": 42
}'
결과 폴링:
curl -s "https://api.novita.ai/v3/async/task-result?task_id=YOUR_TASK_ID" \
-H "Authorization: Bearer $NOVITA_API_KEY"
문제 해결
I2V 제출 시 400 Bad Request
먼저 이미지 제약 조건을 확인하세요: 형식은 jpg/jpeg/png여야 하며, base64 인코딩 전 크기는 10MB 미만이어야 하고(인코딩된 페이로드는 약 33% 더 큼), 최소 300×300px, 종횡비는 1:2.5에서 2.5:1 사이여야 합니다. 가로 극단(매우 넓거나 매우 긴 이미지)은 거부됩니다.
작업이 오랫동안 TASK_STATUS_QUEUED 상태로 유지됨
플랫폼 부하가 높을 때 정상입니다. task.eta 필드가 추정치를 제공합니다. 엔드포인트를 과도하게 호출하지 말고 이에 따라 폴링하세요. 10분 후에도 작업이 진행되지 않으면 Novita AI의 상태 페이지를 확인하거나 제출을 다시 시도하세요.
TASK_STATUS_FAILED 상태이고 이유가 유용하지 않은 경우
더 짧고 간단한 프롬프트로 다시 시도하세요. 모호한 동작 지침, 모순되는 장면 설명 또는 물리적으로 불가능한 동작을 수행하는 캐릭터가 포함된 프롬프트는 실패하는 경향이 있습니다. 부정 프롬프트가 너무 광범위하면 기본 프롬프트와 충돌할 수도 있습니다.
빠른 모드에서 1080p를 사용할 수 없음
fast_mode: true는 해상도를 720p로 제한합니다. 1080p가 필요한 경우 fast_mode를 제거하거나 false로 설정하세요.
style 매개변수가 눈에 띄는 효과가 없음
style 매개변수는 v3.5 전용으로 문서화되어 있습니다. V4.5 요청에서는 자동으로 무시되거나 일관성 없는 결과를 생성할 수 있습니다. 특정 사용 사례를 테스트하지 않고는 이 매개변수에 의존하지 마세요.
FAQ
PixVerse V4.5에서 T2V와 I2V의 차이점은 무엇인가요?
T2V는 텍스트 프롬프트에서만 비디오 클립을 생성합니다. 이미지 입력이 필요하지 않습니다. I2V는 시작 이미지를 사용하고 텍스트 프롬프트에 따라 앞으로 애니메이션을 적용하며 이미지를 첫 번째 프레임으로 사용합니다. 완전히 생성된 장면에는 T2V를 사용하고, 애니메이션을 적용할 특정 시각적 시작점이 있을 때는 I2V를 사용하세요.
PixVerse V4.5는 어떤 비디오 길이를 생성하나요?
클립은 1080p에서 5초, 720p 이하 해상도에서 최대 8초입니다. API에 duration 매개변수는 없습니다. 클립 길이는 선택한 해상도에 따라 결정됩니다.
I2V 엔드포인트는 이미지에서 종횡비를 추론하나요?
예. I2V에는 aspect_ratio 매개변수가 없습니다. 출력 종횡비는 입력 이미지와 일치합니다. 제출하기 전에 이미지를 의도한 출력 비율로 자르세요.
T2V 및 I2V 요청을 병렬로 제출할 수 있나요?
예. 각 요청은 자체 독립적인 task_id를 반환합니다. 여러 요청을 동시에 제출하고 병렬로 폴링할 수 있습니다. 하나가 완료될 때까지 기다렸다가 다음 요청을 제출할 필요가 없습니다.
실행 간에 일관된 출력을 얻으려면 어떻게 해야 하나요?
seed 매개변수를 동일한 정수로 설정하세요. 시드 기반 재현성은 모델 버전 업데이트 시 보장되지 않습니다. 나중에 결과를 감사해야 하는 경우 비디오 URL과 생성 매개변수를 함께 저장하세요.
fast_mode는 프로덕션 사용에 적합한가요?
품질 기준에 따라 다릅니다. fast_mode: true는 비디오를 더 빠르게 생성하고 비용을 절감하지만 해상도는 720p로 제한되고 품질이 표준 모드보다 낮습니다. 미리보기 생성, 배치 평가 및 프로토타이핑에 적합합니다. 출력 품질이 결정적인 요소인 경우 표준 모드를 사용하세요.
