메인 콘텐츠로 건너뛰기
비디오 생성은 비동기입니다. 작업을 제출하고, queue_id를 저장한 다음, 응답이 video/mp4가 될 때까지 /video/retrieve로 폴링하세요.

​
Endpoint

EndpointPurposeRequired
POST /video/quote생성 전 USD 가격 조회아니오
POST /video/queue생성 요청 제출예
POST /video/retrieve상태 폴링 또는 비디오 다운로드예
POST /video/complete스토리지에서 비디오 삭제아니오

​
1단계: 생성 큐에 등록

요청: 
POST https://api.venice.ai/api/v1/video/queue
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "wan-2.5-preview-text-to-video",
  "prompt": "A gondola gliding through Venice canals at sunset",
  "duration": "5s",
  "resolution": "720p",
  "aspect_ratio": "16:9"
}
응답(200): 
{
  "model": "wan-2.5-preview-text-to-video",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000"
}
Grok Imagine Private 모델의 경우 큐 응답에 추가 download_url 필드가 포함됩니다: 
{
  "model": "grok-imagine-text-to-video-private",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000",
  "download_url": "https://private-share.venice.ai/v1/share/read/..."
}
download_url은 retrieve 응답에서 비디오를 읽는 대신 완성된 비디오를 다운로드하는 데 사용하는 사전 서명된 URL입니다. 큐 응답에서 한 번만 반환되므로 queue_id와 함께 저장하세요. 이는 4가지 Grok Imagine Private 변형 모두에 적용됩니다:
  • grok-imagine-text-to-video-private
  • grok-imagine-image-to-video-private
  • grok-imagine-reference-to-video-private
  • grok-imagine-video-to-video-private
공개 grok-imagine-*-video 변형과 달리, Grok Imagine Private 모델은 콘텐츠 모더레이션 거부에 대해 과금되지 않으므로 성공한 생성에 대해서만 지불합니다. 이후 모든 호출을 위해 model, queue_id, download_url(있는 경우)을 저장하세요.

​
Private 다운로드 링크

private 모델의 경우 download_url은 작업이 완료되면 완성된 파일을 가져오는 방법입니다. 이 링크는 짧은 수명, 단일 목적입니다: MP4를 전달하기 위한 것이지, 장기간 또는 광범위하게 공유되는 URL이 아닙니다. 다운로드가 중단되면 같은 환경에서 같은 GET을 몇 번 재시도해 파일을 완성할 수 있습니다. 그런 재시도는 네트워크 일시 장애에서 복구하기 위한 것이지, 같은 링크를 무기한 폴링하거나 많은 클라이언트에 걸쳐 공유하거나 영구 미디어 URL처럼 임베드하기 위한 것이 아닙니다. 그런 패턴은 종종 429 또는 **410**으로 나타나며, 링크가 일반 파일 호스팅처럼 동작할 것이라 기대했다면 놀라울 수 있습니다. 안정성을 위해 GET 요청은 하나의 클라이언트 네트워크에서 발생해야 합니다. IP가 한 번 바뀌는 정도(예: VPN 끊고 다시 시도)에는 유연성이 있지만, 소스 IP가 광범위하게 변하는 것은 대개 동작하지 않습니다. URL은 24시간까지, 또는 객체가 제거될 때까지 유효합니다.
안정적인 URL, 공개 재생, 시간 경과에 따른 반복 접근이 필요하다면 먼저 본인의 스토리지에 파일을 저장하고 거기서 서비스하세요.
프라이버시: DELETE로 링크 무효화 파일을 가져오는 일을 마쳤거나 보관하지 않기로 결정한 경우 같은 download_url에 **DELETE**를 호출할 수 있습니다. 해당 요청에는 Venice API 키가 필요 없습니다. 선택 사항이지만 프라이버시가 중요할 때 권장됩니다. Venice 외부의 일부 프록시와 미들박스는 전체 URL의 로그를 보관하므로, 링크를 삭제하는 것이 사전 서명 URL이 존재하는 창을 좁히는 가장 단순한 방법입니다. 
curl -X DELETE "$DOWNLOAD_URL"
흐름: COMPLETED가 될 때까지 /video/retrieve 폴링 → download_url에 GET(전송이 끊기면 가볍게 재시도) → 필요한 곳에 파일 저장 → 링크를 무효화하려면 download_url에 DELETE → 큐 기반 정리를 여전히 사용한다면 선택적으로 /video/complete 호출.

​
2단계: 완료 폴링

요청: 
POST https://api.venice.ai/api/v1/video/retrieve
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "wan-2.5-preview-text-to-video",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000"
}
응답은 상태에 따라 다릅니다:
Content-TypeMeaningAction
application/json아직 처리 중5초 대기 후 다시 폴링
video/mp4완료응답 본문이 비디오 파일
"COMPLETED"가 있는 application/json완료, 비디오 인라인 아님큐 응답의 download_url에 GET
처리 중 응답(200, application/json): 
{
  "status": "PROCESSING",
  "average_execution_time": 145000,
  "execution_duration": 53200
}
시간은 밀리초입니다. 남은 대기 시간을 추정하려면 average_execution_time을 사용하세요. 완료 응답(200, video/mp4): 응답 본문은 raw 바이너리 비디오 데이터입니다. 파일에 저장하세요. 완료 응답(200, "COMPLETED" 가 있는 application/json): 큐 시점에 download_url을 반환한 모델은 retrieve가 항상 JSON을 반환합니다. GET download_url(인증 헤더 없음)로 비디오를 가져오세요. 이 URL의 동작 방식, 재시도, 선택적 DELETE는 Private 다운로드 링크를 참고하세요.

​
3단계: 정리(선택)

retrieve 시 자동 삭제하거나: 
{
  "model": "wan-2.5-preview-text-to-video",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000",
  "delete_media_on_completion": true
}
저장 후 /video/complete를 호출하세요: 
POST https://api.venice.ai/api/v1/video/complete
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "wan-2.5-preview-text-to-video",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000"
}
응답(200): 
{
  "success": true
}

​
완전한 예시

import os
import time
import requests

API_KEY = os.environ.get("VENICE_API_KEY")
BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 큐 등록
resp = requests.post(f"{BASE_URL}/video/queue", headers=HEADERS, json={
    "model": "wan-2.5-preview-text-to-video",
    "prompt": "A gondola gliding through Venice canals at sunset",
    "duration": "5s",
    "resolution": "720p",
    "aspect_ratio": "16:9"
})
data = resp.json()
model, queue_id = data["model"], data["queue_id"]
download_url = data.get("download_url")

# 폴링
while True:
    resp = requests.post(f"{BASE_URL}/video/retrieve", headers=HEADERS,
                         json={"model": model, "queue_id": queue_id})
    if "video/mp4" in resp.headers.get("Content-Type", ""):
        with open("output.mp4", "wb") as f:
            f.write(resp.content)
        break
    if resp.json().get("status") == "COMPLETED" and download_url:
        with open("output.mp4", "wb") as f:
            f.write(requests.get(download_url).content)
        break
    time.sleep(5)

# 정리
requests.post(f"{BASE_URL}/video/complete", headers=HEADERS,
              json={"model": model, "queue_id": queue_id})

​
요청 파라미터

​
Queue 요청

ParameterTypeRequiredDefaultDescription
modelstring예-모델 ID. text-to-video는 wan-2.5-preview-text-to-video, image-to-video는 wan-2.5-preview-image-to-video
promptstring예-생성할 내용. 최대 2500자
negative_promptstring아니오"low resolution, error, worst quality, low quality, defects"피할 내용
durationstring예-"5s" 또는 "10s"
resolutionstring아니오"720p""480p", "720p", "1080p"
aspect_ratiostring조건부-모델 의존적. 종횡비 옵션을 노출하는 모델에는 필요, 지원하지 않는 모델에는 생략
audioboolean조건부true(지원 시)supportsAudioConfig: true인 모델에만 유효, 오디오 구성을 지원하지 않는 모델에는 생략
image_urlstringimage-to-video에만-원본 이미지의 URL 또는 base64 data URL
audio_urlstring조건부-오디오 input을 지원하는 모델의 레퍼런스 오디오 URL 또는 base64 data URL
큐 검증은 모델별입니다. /video/queue를 호출하기 전에 각 모델이 지원하는 요청 필드를 /models?type=video에서 확인하세요.

​
Quote 요청

ParameterTypeRequiredDefaultDescription
modelstring예-가격을 매길 모델 ID
durationstring예-"5s" 또는 "10s"
resolutionstring아니오"720p""480p", "720p", "1080p"
aspect_ratiostring조건부-선택한 모델이 종횡비 선택을 지원하거나 요구할 때 포함
audioboolean조건부true(지원 시)supportsAudioConfig: true인 모델에만 유효

​
Retrieve 요청

ParameterTypeRequiredDefaultDescription
modelstring예-큐 응답에서
queue_idstring예-큐 응답에서
delete_media_on_completionboolean아니오false성공적 retrieve 후 비디오 삭제

​
Complete 요청

ParameterTypeRequiredDescription
modelstring예큐 응답에서
queue_idstring예큐 응답에서

​
Image to Video

Image-to-video 모델의 경우 image_url을 통해 원본 이미지를 전달하세요. prompt는 이미지 내용이 아니라 원하는 모션을 설명합니다. 
{
  "model": "wan-2.5-preview-image-to-video",
  "prompt": "Camera slowly zooms in as leaves rustle in the wind",
  "image_url": "https://example.com/image.jpg",
  "duration": "5s"
}
또는 base64로: 
{
  "model": "wan-2.5-preview-image-to-video",
  "prompt": "Camera slowly zooms in as leaves rustle in the wind",
  "image_url": "data:image/jpeg;base64,/9j/4AAQ...",
  "duration": "5s"
}

​
가격 견적

생성 전에 정확한 비용을 받으세요. 가격 input(model, duration, 선택적 resolution, aspect_ratio, audio)만 보내세요: 요청: 
{
  "model": "wan-2.5-preview-text-to-video",
  "duration": "10s",
  "resolution": "1080p"
}
응답: 
{
  "quote": 0.085
}
견적은 USD 단위입니다.

​
에러

StatusReturned ByMeaningAction
400queue, quote, retrieve, complete잘못된 파라미터스키마에 맞춰 요청 본문 확인
401queue, retrieve, complete인증 실패API 키 확인
402queue잔액 부족자금 추가
404retrieve, download_url미디어를 찾을 수 없음(잘못됨, 만료됨, 또는 삭제됨)model/queue_id 확인 또는 재큐
410download_url사전 서명 URL 만료, 완전히 사용됨, 또는 무효화(예: DELETE 이후)다른 파일이 필요하면 새 생성 시작. 각 링크는 의도적으로 짧은 수명
429download_url같은 링크에 대한 다수의 재시도 또는 반복적 fetch로 인한 rate limit다운로드 마무리(연결 끊김 시 몇 번 재시도는 괜찮음), 로컬 복사본 저장, 링크 비우려면 DELETE 사용. 지속적 접근은 본인 스토리지에 유지
413queue페이로드가 너무 큼이미지/오디오 크기 축소
422queue, retrieve콘텐츠 위반prompt 수정
500queue, retrieve, complete추론/처리 실패백오프와 함께 재시도, 지속되면 지원에 문의
503retrieve모델 용량 초과백오프와 함께 재시도

​
폴링 전략

  1. 일정 간격(예: 5초)으로 /video/retrieve 폴링
  2. Content-Type이 application/json이고 status가 "PROCESSING"이면 대기 후 다시 폴링. 남은 시간 추정에는 average_execution_time과 execution_duration(밀리초) 사용
  3. Content-Type이 video/mp4이면 응답 본문을 출력 파일로 저장
  4. Content-Type이 application/json이고 status가 "COMPLETED"이면 큐 응답의 download_url에 GET해서 비디오 가져오기(Private 다운로드 링크 참고)
  5. download_url을 사용했다면, 마쳤을 때 해당 URL에 DELETE를 고려해 사전 서명 URL이 존재하는 시간을 좁히세요. 그런 다음 retrieve에서 delete_media_on_completion: true를 설정하거나 큐 기반 정리를 위해 /video/complete 호출
  6. 404는 잘못됨, 만료됨, 또는 삭제된 미디어로 처리. 500/503은 재시도/백오프로 처리

​
사용 가능한 모델

현재 모델 목록과 가격은 Video Models를 참고하세요.