Wan 3.0 Prime · API

빠른 시작

세 단계면 됩니다: 작업 제출 → 결과 조회 → 영상 링크 받기. YOUR_API_KEY를 내 키로 바꾸면 아래 명령을 그대로 실행할 수 있습니다.

1단계 · 제출(작업 ID를 바로 돌려줍니다, HTTP 202)

curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "wan3.0-video-prime", "prompt": "벚나무 아래에서 떨어지는 꽃잎을 쫓는 시바견, 화창한 햇살, 슬로 모션", "duration": 5, "resolution": "720P", "size": "16:9"}'

응답(HTTP 202)

{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "wan3.0-video-prime"
}

2단계 · status가 succeeded 또는 failed가 될 때까지 5~10초마다 조회

curl https://nezhagate.com/v1/videos/jobs/img_5c2e8f1a9b3d7e6f0a4c8b2d \
  -H "Authorization: Bearer YOUR_API_KEY"

성공했을 때의 응답

{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "wan3.0-video-prime",
  "data": [
    {"url": "https://img.nezhagate.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
  ],
  "usage": {"clips": 1, "model": "wan3.0-video-prime"}
}

3단계 · data[0].url이 결과 영상(MP4)입니다. 15일 동안 보관되므로 더 오래 쓰려면 내 저장소에 내려받아 두세요.

전체 예제(Python: 제출 → 대기 → 로컬에 저장)

import time
import requests

BASE = "https://nezhagate.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. 제출
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
    "model": "wan3.0-video-prime",
    "prompt": "벚나무 아래에서 떨어지는 꽃잎을 쫓는 시바견, 화창한 햇살, 슬로 모션",
    "duration": 5,
    "resolution": "720P",
    "size": "16:9",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 10초마다 조회, 최대 1시간까지 대기
deadline = time.time() + 3600
while job["status"] not in ("succeeded", "failed") and time.time() < deadline:
    time.sleep(10)
    job = requests.get(f"{BASE}/videos/jobs/{job['id']}", headers=HEADERS).json()

# 3. 영상 내려받기
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("wan3.0-video-prime.mp4", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
elif job["status"] == "failed":
    print("failed:", job["error"]["code"], job["error"]["message"])
else:
    print("still", job["status"], job["id"])

대기 중일 때는 조회 결과에 queue_position(앞에 있는 작업 수)과 eta_seconds(예상 대기 시간)도 함께 옵니다. 프로그램에 정해 둔 대기 시간을 넘겨도 다시 제출하지 마세요. 작업은 그대로 남아 있으니 나중에 같은 작업 ID로 이어서 조회하면 됩니다.

인증

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

콘솔에서 API 키를 만들면 시작할 수 있습니다.

사양 한눈에 보기

요청 파라미터

POST /v1/videos/generations의 요청 본문(JSON):

그 밖의 필드(seed, negative_prompt, fps, watermark 등)는 전달되지 않으며 가격에도 영향을 주지 않습니다. 결과는 항상 MP4이며 url로 돌려줍니다.

가격

초 단위로 과금합니다: 비용 = 선택한 해상도의 초당 단가 × (결과 영상 초 수 + 모든 참조 영상의 초 수). 참조 이미지와 참조 오디오는 무료입니다. 제출할 때 예약되고, 실패하면 전액 환불됩니다. 1크레딧 = $0.005.

480P / 720P / 1080P 등급은 아직 열리지 않아 제출하면 400으로 거절됩니다. 열리면 이 표가 자동으로 갱신됩니다.

참조 소재

• 엔드포인트 하나에서 파라미터로 모드를 고릅니다. 이미지가 없으면 텍스트-투-비디오, 1장이면 첫 프레임, 2장에 image_role: first_frame을 넣으면 첫·마지막 프레임(1번째 이미지가 첫 프레임, 2번째가 마지막 프레임)입니다. 넣지 않으면 2장 이상은 모두 참조이며 최대 10장입니다.
• 참조 영상은 최대 5개(합계 15초, 각각 duration 필수)이며, 그 영상을 새롭게 바꾸거나 이어서 만드는 데 쓰입니다. 참조 영상이 있으면 이미지는 참조로만 쓸 수 있고 첫·마지막 프레임으로는 쓸 수 없습니다. 참조 오디오는 최대 5개이며 공개 URL만 받습니다.
• 첫 프레임이 있을 때 size: adaptive를 보내면 영상이 첫 프레임 이미지의 비율을 따릅니다. 사람 얼굴 심사 제한: 실제 사람의 얼굴이 포함된 참조 소재는 피하세요. 사실적인 얼굴도 감지될 수 있습니다. FaceDetectionSuspect는 실제 사람 얼굴이 의심된다는 뜻입니다. DataInspectionFailed는 입력 소재가 콘텐츠 심사를 통과하지 못했다는 뜻이며 서비스 중단을 의미하지 않습니다. 같은 입력을 반복하지 말고 참조 소재를 교체한 후 다시 제출하세요. 오탐이 의심되면 지원팀에 문의하세요. 실패한 작업은 과금되지 않습니다.
• 이미지는 각각 공개 이미지 URL, data: URI, base64 중 하나로 보낼 수 있으며 한 장당 16MB 이하입니다. 여러 장은 images에 배열로 넣으세요. 제출할 때 당사가 이미지를 먼저 저장한 뒤 작업을 대기열에 넣습니다. 읽을 수 없는 이미지가 있으면 400으로 거절되고 message에 몇 번째 이미지인지 적혀 있으며, 과금되지 않습니다.
• 당사가 저장한 참조 소재는 7일, 결과 영상은 15일 동안 보관됩니다.

첫·마지막 프레임: 두 이미지 사이의 전환 만들기

curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "wan3.0-video-prime", "prompt": "새벽에서 해 질 녘으로 바뀌는 하늘, 흘러가는 구름, 점점 따뜻해지는 빛", "images": ["https://example.com/first.png", "https://example.com/last.png"], "image_role": "first_frame", "duration": 5, "resolution": "720P", "size": "adaptive"}'

image_role: first_frame은 두 이미지를 첫 프레임과 마지막 프레임으로 쓰게 하고, size: adaptive는 영상이 첫 프레임 이미지의 비율을 따르게 합니다. image_role을 넣지 않으면 두 이미지는 참조로 쓰입니다.

작업 상태와 응답 필드

GET /v1/videos/jobs/{id}는 아래 상태를 돌려줍니다. 각 필드의 설명은 비동기 작업에 있습니다. 5~10초마다 조회하거나, 아래의 웹훅으로 결과를 받으세요. 조회는 무료이며, 같은 계정의 어느 키로든 조회할 수 있습니다.

• processing이 queued로 돌아갈 때가 있습니다. 예를 들어 모든 회선이 가득 찼을 때, 완성된 영상을 다시 가져오는 중일 때, 서비스가 재시작된 뒤입니다. 어떤 회선이 작업을 끝내지 못하면 게이트웨이가 다음 회선으로 넘겨 다시 만들 수 있습니다. 회선을 몇 번 거치든 작업 하나에 한 번만 과금됩니다.
• 한 계정은 최대 50개 작업을 동시에 생성하며, 그보다 많은 작업은 제출 순서대로 대기합니다. 15분이 지나도 시작되지 않은 작업은 자동으로 실패 처리되고 전액 환불됩니다. 작업 기록은 3일, 영상 링크는 15일 동안 보관됩니다.

생성 시간

보통 1~3분 걸리며, 표준 Wan 3.0보다 빠릅니다.

오류와 환불

제출 단계의 오류는 HTTP 4xx / 5xx로 바로 돌아오며, 작업은 만들어지지 않고 과금되지 않습니다. 작업이 접수된 뒤의 실패는 작업 조회 결과로 알려 주며, 예약된 크레딧은 전액 환불됩니다. 전체 코드는 오류 코드에 있습니다.

제출할 때 돌아오는 오류

작업 실패(status가 failed)

message의 문구가 아니라 code로 판단하세요. 모르는 code가 오거나 code가 없으면 upstream_error로 처리하면 됩니다. 다시 제출하면 대개 성공합니다. 실패한 작업은 모두 전액 환불됩니다.

조회 대신 웹훅으로 받기

제출할 때 callback_url을 넣으면 작업이 끝나는 즉시(성공이든 실패든) 게이트웨이가 조회 엔드포인트와 똑같은 결과를 그 URL로 보냅니다. 서명이 포함되며, 전송에 실패하면 자동으로 재시도합니다. 콘솔의 「설정 → 웹훅」에서 계정 전체에 쓸 주소를 지정할 수도 있습니다. 웹훅 문서 →

curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "wan3.0-video-prime", "prompt": "벚나무 아래에서 떨어지는 꽃잎을 쫓는 시바견, 화창한 햇살, 슬로 모션", "duration": 5, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'