Wan 3.0(통이완샹) 영상 생성(비동기)입니다. 엔드포인트는 하나이고 파라미터가 모드를 정합니다. 소재가 없으면 텍스트-투-비디오, 참조 이미지 한 장이면 첫 프레임, 두 장이면 첫+마지막 프레임, 그 이상이면 다중 이미지 참조, 참조 영상을 넣으면 영상 편집이 됩니다. duration은 2~30초 사이의 정수, resolution은 480P / 720P / 1080P(기본값 720P, 등급마다 단가가 따로 있음), size는 16:9 / 9:16 / 1:1 / 4:3 / 3:4이며, 첫 프레임이 있으면 size=adaptive로 두어 출력이 참조 이미지를 따라가게 할 수 있습니다. 참조 이미지 최대 10장, 참조 영상 5개, 참조 오디오 5개까지 넣을 수 있습니다(뒤의 둘은 각각 합계 15초까지). 작업 ID를 돌려주고(HTTP 202) GET /v1/videos/jobs/{id}를 status=succeeded가 될 때까지 폴링하면 결과가 data[0].url(재호스팅된 mp4)에 담깁니다. 과금은 출력 길이에 각 참조 영상의 길이를 더한 초에 대해 초당으로 계산하며 참조 이미지와 오디오는 무료입니다. 실패 시 전액 환불합니다.
플레이그라운드에서 사용해 보기 →인증
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
콘솔에서 API 키를 만들면 시작할 수 있습니다.
요청 본문
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| model | string | 예 | 모델 ID. 여기서는 wan3.0-video입니다. |
| prompt | string | 예 | 영상의 내용, 카메라, 움직임을 설명하는 텍스트 프롬프트. 최대 5000 바이트(UTF-8. 한글 한 글자는 3바이트). 참조 소재는 순서대로 @Image1 / @Video1 / @Audio1로 지칭할 수 있습니다. 예: "@Image1의 인물이 @Video1의 카메라 움직임으로". 지칭하지 않으면 모델이 알아서 판단합니다. |
| duration | integer | 아니오 | 길이(초). 2~30 사이의 정수이며 기본값은 2입니다. seconds로도 쓸 수 있습니다. 초당 과금합니다. |
| resolution | string | 아니오 | 해상도: 480P / 720P / 1080P(기본값 720P). 초당 단가: 480P $0.09 / 720P $0.12 / 1080P $0.16. |
| size | string | 아니오 | 화면 비율: 16:9 / 9:16 / 1:1 / 4:3 / 3:4(기본값 16:9). aspect_ratio로도 쓸 수 있습니다. 첫 프레임이 있으면 adaptive를 넘겨 출력이 참조 이미지의 비율을 따라가게 할 수 있습니다. 21:9는 지원하지 않습니다. |
| image | string | 아니오 | 이미지-투-비디오: 참조 이미지 한 장은 기본적으로 첫 프레임으로 쓰입니다(공개 URL, data: URI, base64). 텍스트-투-비디오라면 생략하세요. |
| images | array | 아니오 | 참조 이미지 여러 장. 최대 10장이며 무료입니다. 두 장 이상이면 기본적으로 피사체 / 장면 참조로 취급합니다. 상한을 넘으면 잘라내지 않고 거절하며 reference_images로도 쓸 수 있습니다. 참고: 어느 참조 이미지에든 보이는 사람은 모두 후보 피사체가 되므로, 장면 참조에는 다른 사람이 없는 편이 좋습니다. |
| image_role | string | 아니오 | 참조 이미지의 사용 방식: first_frame(두 번째 이미지는 마지막 프레임이 됩니다) 또는 reference(피사체 / 장면 가이드). 생략하면 이미지 한 장은 first_frame, 두 장 이상은 reference가 기본입니다. 참조 영상과 함께 쓸 때는 reference가 필수입니다. |
| video_references | array | 아니오 | 참조 영상. 최대 5개, 합계 15초까지입니다. 각 항목은 {"url": "...", "duration": 5} 형태로 쓰며 duration(초)은 필수입니다. 참조 영상의 초도 출력과 함께 과금되기 때문입니다. 공개 http(s) 링크만 받습니다. 참조 영상을 넣을 때는 참조 + 출력 길이 합계가 30초를 넘지 않아야 합니다. 참조 이미지와 함께 쓸 수 있습니다. |
| audio_reference | string / array | 아니오 | 참조 오디오의 공개 http(s) 링크. 최대 5개, 합계 15초까지이며 무료입니다. 참조 이미지나 참조 영상과 함께 써야 합니다. |
| prompt_extend | boolean | 아니오 | 공식 프롬프트 재작성. 생략하면 업스트림 기본값(켜짐)이 적용됩니다. 공들여 쓴 프롬프트를 그대로 두려면 false를 넘기세요. |
요청 예시
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "wan3.0-video", "prompt": "a paper crane unfolding over a misty lake", "duration": 5, "resolution": "720P", "size": "16:9"}'
# image-to-video: also pass "image": "https://example.com/first-frame.png"
# 2) poll every ~15s until status=succeeded, then read data[0].url
curl https://nezhagate.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'응답
{
"id": "img_3f9a...c2",
"object": "video.generation.job",
"status": "queued",
"model": "wan3.0-video"
}비동기 영상 작업 (제출 → 폴링)
모델은 하나이고 파라미터로 종류를 고릅니다: tier=lite/fast/quality, resolution=720p/1080p/4k (1080p/4k는 quality 필요), size=16:9/9:16, duration=4s/6s/8s. 이미지-투-비디오는 image 파라미터를 추가하세요(첫 프레임). HTTP 202와 작업 ID를 반환하며, status=succeeded가 될 때까지 폴링하면 결과가 data[0].url에 담깁니다(재호스팅된 mp4, 약 1~2분).
curl https://nezhagate.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "wan3.0-video", "prompt": "노을 속에서 서핑하는 고양이", "tier": "quality", "resolution": "1080p", "size": "16:9", "duration": "8s"}'{ "id": "img_3f9a...c2", "object": "video.generation.job", "status": "queued", "model": "wan3.0-video" }curl https://nezhagate.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
{
"id": "img_3f9a...c2",
"object": "video.generation.job",
"status": "succeeded",
"model": "wan3.0-video",
"data": [{ "url": "https://img.nezhagate.com/i/9f86d081a8....mp4" }]
}초당 과금 ($0.12/초 × 길이). 예치 금액과 정산 금액이 정확히 일치하며, 실패하거나 시간이 초과된 렌더링은 자동으로 전액 환불됩니다.
오류 코드
| Code | 설명 |
|---|---|
| 401 | API 키가 없거나 유효하지 않음 |
| 402 | 잔액 부족 또는 키 한도 초과 |
| 400 | 지원하지 않는 모델 또는 파라미터 |
| 429 | 업스트림 요청 한도 초과 |
| 502 | 모든 업스트림 경로가 실패 |
