Vidu
Vidu Q3
vidu-q3-ad/reference-to-video
광고 및 소셜 숏폼 영상용 참조 이미지 기반 비디오 생성 모델로, 피사체의 외형과 구도를 제어할 수 있어 빠른 결과물 제작과 다중 버전 반복 작업에 적합합니다
vidu-q3-ad/reference-to-video 사용해 보기
입력
출력
가격
vidu-q3-ad/reference-to-video per second
| 사양 | 단가 |
|---|---|
| 1280*720 | $0.149 |
| 1280*960 | $0.149 |
| 1280*1280 | $0.149 |
| 960*1280 | $0.149 |
| 720*1280 | $0.149 |
| 1920*1080 | $0.180 |
| 1920*1440 | $0.180 |
| 1808*1808 | $0.180 |
| 1440*1920 | $0.180 |
| 1080*1920 | $0.180 |
포지셔닝 소개
Vidu Q3의 레퍼런스 기반 영상 생성 라인은 제어 가능한 화면과 안정적인 피사체가 필요한 숏폼 영상 제작을 위한 것입니다. 개발자는 1~7장의 레퍼런스 이미지와 프롬프트 한 편을 제출하면 3~15초의 영상을 생성할 수 있으며, 레퍼런스 이미지는 배열 순서대로 프롬프트에서 Image1, Image2로 참조되어 캐릭터, 사물 또는 화면 스타일을 제약합니다. 출력은 720P와 1080P 두 단계 총 열 가지 화면 비율을 지원하고, 오디오를 화면과 동기화하여 생성할 수 있으며, 고정 시드로 결과를 재현할 수도 있습니다. 광고 소재, 제품 시연, 캐릭터 짧은 클립 등 빠르게 여러 버전을 시험 제작해야 하는 팀에 적합합니다.
핵심 하이라이트
- 다중 이미지 참조로 피사체와 스타일 제약——한 번에 최대 7장의 레퍼런스 이미지를 전달하고, 순서대로 Image1, Image2로 프롬프트에서 지정하여 각각 캐릭터, 사물 또는 화면 스타일을 제약합니다.
- 화면과 오디오를 한 번에 생성——audio를 켜면 영상과 함께 화면에 맞는 소리가 동기화되어 생성되고, 기본값인 끄기 상태에서는 무음 영상이 출력되어 이후 직접 더빙하기 편리합니다.
- 길이와 화면 비율을 필요에 맞게 조합——길이는 3~15초로 선택 가능하며, 720P와 1080P 두 단계에 각각 16:9, 4:3, 1:1, 3:4, 9:16 다섯 가지 화면 비율이 포함됩니다.
- 시드 고정으로 재현과 반복 개선 용이——0~2147483647의 랜덤 시드를 지정할 수 있어 동일한 설정에서 결과를 재현할 수 있으며, 프롬프트 변경 효과를 비교하기 편리합니다.
기능 설명
다중 레퍼런스 이미지 기반 생성: 공개 접근 가능한 JPG, PNG, WEBP 이미지 1~7장을 받으며, 단일 이미지 최대 50MB, 가로세로 비율 1:4~4:1로 캐릭터, 사물 외형 또는 전체 스타일을 고정하는 데 사용됩니다.
프롬프트로 장면과 카메라 워크 제어: 최대 5000자의 프롬프트로 장면, 동작, 카메라 움직임과 소리를 설명할 수 있고, Image1, Image2 인덱스를 통해 구체적인 레퍼런스 이미지를 가리켜 이미지별로 역할을 분담할 수 있습니다.
선택적 오디오 생성: audio 스위치로 화면에 맞는 오디오를 함께 생성할지 제어하며, 끄면 무음 영상이 출력되어 자체 더빙이나 음악 파이프라인에 연결하기 편리합니다.
해상도와 화면 비율 선택: size 파라미터는 720P와 1080P 두 단계를 제공하며, 각각 가로, 세로, 정사각형 및 두 가지 세로 비율을 포함해 다양한 게재 위치의 완성 규격에 맞춥니다.
길이와 워터마크 제어: duration은 3~15초 사이에서 값을 지정하며, watermark는 오른쪽 아래에 AI 생성 표시를 추가할지 선택할 수 있고, 출력 초 단위로 과금됩니다.
적용 시나리오
- 브랜드 및 광고 집행 팀: 여러 장의 상품 이미지 + 판매 포인트 문구——지정된 화면 비율의 짧은 광고 클립을 제작하여 소셜 플랫폼 게재 및 이커머스 상세 페이지 전시 소재로 사용합니다.
- 캐릭터 콘텐츠 크리에이터: 캐릭터 설정 이미지 + 스토리 설명——캐릭터 외형이 일관된 이야기 짧은 장면을 생성하여 숏드라마 클립, 애니메이션 스타일 콘셉트 검증 및 스토리보드 미리보기에 사용합니다.
- 크리에이티브 팀: 스타일 레퍼런스 이미지 + 기획 설명——여러 버전의 시험 영상을 빠르게 제작해 A/B 비교를 하고, 고정 시드로 변수를 통제한 뒤 선별하여 정식 제작에 들어갑니다.
- 제품 시연 제작: 제품 사진 + 사용 장면 설명——정적인 제품 이미지를 카메라 워크가 있는 시연 영상으로 전환하여 공식 웹사이트, 발표회 및 교육 자료에 사용합니다.
제한 사항 및 선택 가이드
단일 출력 길이는 3~15초로 제한되어 긴 영상이나 연속 다중 장면 서사를 직접 커버할 수 없으며, 완성 영상은 여전히 수동 편집과 이어 붙이기가 필요합니다. 레퍼런스 이미지는 공개 접근 가능해야 하고 단일 이미지가 50MB를 초과할 수 없으며, 비공개 저장소의 이미지는 먼저 접근 가능한 주소로 변환해야 합니다. 오디오는 선택적 생성 항목으로, 화면과 정밀하게 정렬되어야 하는 대사나 더빙이 필요할 때는 무음 출력 후 별도로 제작하는 것이 더 제어하기 쉽습니다. 현재는 레퍼런스 이미지 기반만 지원하고 순수 텍스트 입력은 받지 않으므로, 레퍼런스 소재가 없는 아이디어는 텍스트 투 비디오 라인을 선택하십시오.
생성 작업 제출
https://api.hiapi.ai/v1/tasks 헤더
Authorizationstring필수계정 API 키. 모든 요청에 필수입니다. 예: Bearer YOUR_HIAPI_API_KEY. API 키 받기
Content-Typestring선택요청 본문은 항상 JSON으로 파싱됩니다. 전송 시 application/json(charset 포함 가능)만 허용되며, 다른 값은 415를 반환합니다. 예: application/json.
Idempotency-Keystring선택멱등 키. 최대 255바이트. 같은 계정에서 같은 키의 재시도는 태스크를 한 번만 생성하며, 재전송 시 최초의 taskId를 반환합니다.
네트워크 타임아웃이나 클라이언트 자동 재시도 시 같은 키로는 태스크를 한 번만 생성하고 이중 과금되지 않습니다(범위 = API 키의 계정). 업무 고유 식별자(예: "order-42")를 키로 사용할 것을 권장합니다. 같은 키 재전송 시 최초 taskId를 반환하며, 키는 첫 제출 후 24시간 뒤 만료됩니다. 자세한 시나리오 표는 통합 비동기 API 소개 페이지를 참고하세요.
본문
modelstring필수현재 고정 값: vidu-q3-ad/reference-to-video
routestring선택현재 고정 값: default
inputobject필수
vidu-q3-ad/reference-to-video 및 루트 default의 비즈니스 파라미터 객체. 아래 파라미터 표를 참조하세요.
seedinteger선택min 0max 2147483647생성 결과를 재현하기 위한 랜덤 시드이며, 값 범위는 0에서 2147483647입니다.
sizestring선택기본값: "1280*720"출력 영상 해상도로, 형식은 WIDTH*HEIGHT이며 720P와 1080P 두 등급으로 나뉘고 각 등급은 16:9, 4:3, 1:1, 3:4, 9:16을 모두 지원합니다. 초 단위 과금 가격은 등급에 따라 다릅니다. 기본값은 1280*720입니다.
1280*7201280*9601280*1280960*1280720*12801920*10801920*14401808*1808전체 보기(2개)
1440*19201080*1920audioboolean선택기본값: false화면과 일치하는 오디오를 생성할지 여부이며, 끄면 무음 영상이 출력됩니다. 기본값은 false입니다.
promptstring필수minLength 1maxLength 5000장면, 움직임, 카메라, 소리를 설명합니다. 참조 이미지는 배열 순서대로 Image1, Image2 등으로 번호를 매겨 프롬프트에서 인용합니다.
durationinteger필수기본값: 5min 3max 15출력 영상 길이이며 단위는 초이고 값 범위는 3에서 15입니다. 기본값은 5입니다.
watermarkboolean선택기본값: false화면 오른쪽 아래에 AI 생성 워터마크를 추가할지 여부이며, 기본값은 꺼짐입니다. 기본값은 false입니다.
reference_image_urlsarray필수minItems 1maxItems 7참조 이미지 배열로, 1에서 7장의 이미지(인물, 사물 또는 스타일)를 제공합니다. 각 이미지는 JPG/PNG/WEBP 형식, 50MB 이하, 가로세로 비율 1:4에서 4:1이며 공개적으로 접근 가능해야 하고, 프롬프트에서 Image1, Image2 등으로 번호를 매겨 인용합니다.
Array [ string ]
callbackobject선택
종료 상태 알림 설정. 생략하면 콜백이 전송되지 않으며 호출 측에서 폴링합니다.
생성 시 callback.url을 지정하면 태스크 종료 시 HiAPI가 서비스로 POST하여 폴링이 필요 없습니다. 콜백 본문은 태스크 상세와 동일한 구조입니다. 서명 검증·재시도·멱등에 대한 자세한 내용은 통합 비동기 API 소개 페이지의 콜백 설명을 참고하세요.
urlstring필수callback 사용 시 필수. 태스크 종료 후 이 URL로 POST됩니다. 유효한 http(s) URL이어야 합니다.
whenstring선택기본값: "final"현재는 final만 지원(success / fail 모두 알림).
finalstoragestring선택기본값: "temp"산출물 저장 등급: temp(기본·약 7일) 또는 persistent(장기 보관·용량 과금). 잔액 부족이나 저장 한도 초과 시 자동으로 temp로 강등됩니다. 실제 적용된 등급은 태스크 상세 응답에서 확인할 수 있습니다.
temppersistent요청 예시
# 비동기 태스크 제출. 성공 시 즉시 taskId 반환(생성 완료 대기 없음)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "vidu-q3-ad/reference-to-video",
"input": {
"size": "1280*720",
"audio": false,
"prompt": "…",
"duration": 5,
"watermark": false,
"reference_image_urls": "…"
}
}' const res = await fetch("https://api.hiapi.ai/v1/tasks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "vidu-q3-ad/reference-to-video",
input: {
"size": "1280*720",
"audio": false,
"prompt": "…",
"duration": 5,
"watermark": false,
"reference_image_urls": "…"
}
}),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } } import os, requests
res = requests.post(
"https://api.hiapi.ai/v1/tasks",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "vidu-q3-ad/reference-to-video",
"input": {
"size": "1280*720",
"audio": False,
"prompt": "…",
"duration": 5,
"watermark": False,
"reference_image_urls": "…"
}
},
)
print(res.json()) # { code, message, data: { taskId } } 200 OK
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
}
} 400 Bad Request
{
"code": 400,
"message": "invalid request",
"data": null,
"error_code": "INVALID_REQUEST"
} 작업 상세 조회
https://api.hiapi.ai/v1/tasks/:id 응답 필드
taskIdstring필수태스크 ID. 접두사는 항상 tk-hiapi-.
modelstring필수확인된 전체 모델명. route 파라미터로 제출한 태스크는 base@route(예: gpt-image-2/text-to-image@ext)를 반환하며, 그 외에는 제출 시의 모델명과 동일합니다.
routestring선택route 파라미터를 명시해 제출한 태스크에만 나타나며, 제출한 값을 그대로 반환합니다.
statusstring필수태스크 상태.
queued 대기 중, 아직 시작되지 않음.
handling 처리 중.
archiving 처리 완료, 산출물 준비 중.
success 종료: 완료. 산출물 사용 가능(output 반환).
fail 종료: 실패(error 반환).
제출 후 status로 판단합니다: success와 fail이 종료 상태이며 나머지는 비종료입니다. 1~3초 간격으로 종료까지 폴링하세요. 성공 시 output[].url에서 산출물을 다운로드하고 expireAt 전에 옮기세요. 장기 보관이 필요하면 생성 시 storage: "persistent"를 사용하세요.
creatednumber필수태스크 생성 시각(Unix 초).
completednumber필수종료 상태가 된 Unix 초. 비종료 상태에서는 0.
outputarray선택
status == success일 때만 나타납니다. 산출물 목록 — 항상 배열이며, 하나의 태스크에서 여러 type을 동시에 반환할 수 있습니다(예: video + first_frame).
Array [ object ]
배열 항목
urlstring필수산출물 URL. 바로 다운로드할 수 있습니다.
typestring필수현재 가능한 값: video, image, audio, first_frame, last_frame, thumbnail. 이후 확장될 수 있습니다.
expireAtnumber필수산출물 접근 가능 기한(Unix 초). 만료 전에 다운로드하거나 이전하세요.
errorobject선택
status == fail일 때만 나타납니다.
codestring필수비즈니스 오류 코드.
messagestring필수오류 설명.
응답 예시
성공
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
"model": "happyhorse-1-0",
"status": "success",
"created": 1777282033,
"completed": 1777282099,
"output": [
{
"url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
"type": "video",
"expireAt": 1777886899
}
]
}
} 처리 중(비종료)
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "archiving",
"created": 1777282033,
"completed": 0
}
} 실패
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "fail",
"created": 1777282033,
"completed": 1777282099,
"error": {
"code": "TASK_FAILED",
"message": "task failed"
}
}
} 아티클
모든 아티클 보기 →-
튜토리얼
HiAPI API로 hailuo-2.3-fast/image-to-video 호출하는 방법: curl과 Python 실전
빠르고 저렴한 이미지-투-비디오 등급의 첫 실행 요청 — 모델 ID부터 MP4 다운로드까지
-
튜토리얼
HiAPI에서 kling-4.0/image-to-video를 호출하는 방법: curl, Python 및 폴링
-
튜토리얼
HiAPI에서 kandinsky-6.0-pro/image-to-video 튜토리얼: curl + Python
HiAPI에서 사용 가능한 이미지-투-비디오 요청 보내기: 첫 프레임 업로드부터 비동기 폴링, 최종 다운로드까지
-
튜토리얼
HiAPI API로 kling-4.0/text-to-video를 사용하는 방법: curl, Python 및 실행 가능한 요청 예제
개발자를 위한 실전 가이드: 영화적 프롬프트, 동기화 오디오, 비동기 폴링 및 출력 다운로드
-
튜토리얼
HiAPI에서 Kandinsky 6.0 Pro 텍스트-투-비디오 사용하기: curl 및 Python 튜토리얼
요청 우선 실전 데모: 프롬프트에서 비디오 클립까지의 호출 구성, 요청 제출, 완료 상태 폴링 및 결과 다운로드
-
튜토리얼
HiAPI API로 hailuo-2.3/text-to-video를 호출하는 방법: curl, Python 및 실행 가능한 요청 예시
관련 모델
모든 모델 보기 →동일 유형
-
Grok Imagine 1.5 xAI $0.011 /초 -
Veo 3.1 Lite Google $0.060 /초 -
FLUX 3 Video Black Forest Labs $0.090 /초 -
Wan 3.0 Video Alibaba $0.040 /초 -
Gemini Omni Google -- -
HeyGen Avatar V HeyGen $0.150 /초 -
Wan 2.6 Flash Alibaba $0.043 /초 -
PixVerse V6 PixVerse $0.036 /초 -
Creatify Boreal Creatify $0.015 /초 -
Seedance 2.0 ByteDance $0.017 /초 -
HappyHorse 1.0 Alibaba $0.168 /초 -
FLUX 3 Max Black Forest Labs $0.061 /초