Vidu

Vidu Q3

vidu-q3-mix/reference-to-video

광고 및 소셜 숏폼 영상용 참조 이미지 기반 비디오 생성 모델로, 피사체의 외형과 구도를 제어할 수 있어 빠른 결과물 제작과 다중 버전 반복 작업에 적합합니다

vidu-q3-ad/reference-to-video vidu-q3-mix/reference-to-video

vidu-q3-mix/reference-to-video 사용해 보기

입력

출력

파라미터를 입력하고 생성하면 결과가 여기에 표시됩니다.

가격

vidu-q3-mix/reference-to-video per second

사양	단가
1280*720	$0.1555
1280*960	$0.1555
1280*1280	$0.1555
960*1280	$0.1555
720*1280	$0.1555
1920*1080	$0.1865
1920*1440	$0.1865
1808*1808	$0.1865
1440*1920	$0.1865
1080*1920	$0.1865

포지셔닝 소개

Vidu Q3의 참조 이미지 기반 이미지-투-비디오 라인: 1~7장의 참조 이미지(인물, 사물 또는 스타일)로 화면 주체를 제약하고, 프롬프트와 함께 1~16초의 짧은 영상을 생성합니다. 출력은 720P와 1080P 두 단계, 다섯 가지 화면 비율을 지원하며, 화면과 매칭되는 오디오를 선택적으로 생성할 수 있습니다. 여러 숏 클립에서 캐릭터나 상품의 외형을 일관되게 유지하면서 후보 버전을 빠르게 만들어야 하는 개발자에게 적합하며, 광고 소재, 이커머스 전시, 캐릭터 단편 드라마 등 짧은 콘텐츠 제작에 활용됩니다.

핵심 특징

다중 이미지 참조로 주체 일관성 제약——최대 7장의 참조 이미지를 전달할 수 있으며, 프롬프트에서 Image1, Image2 순서로 참조하여 인물, 사물, 전체 스타일을 각각 제약합니다.
선택적 오디오와 화면 동시 생성——audio를 켜면 화면과 매칭되는 소리를 생성하고, 끄면 무음 영상을 출력하므로 필요에 따라 후반 더빙 여부를 결정할 수 있습니다.
길이와 화면 비율 정밀 제어——길이는 1~16초까지 연속 조정 가능하며, 화면 비율은 16:9, 4:3, 1:1, 3:4, 9:16을 지원하므로 세로·가로 소재를 2차 크롭 없이 사용할 수 있습니다.
seed로 생성 결과 재현——시드를 고정하면 동일한 프롬프트와 참조 이미지 조합으로 반복 출력할 수 있어 파라미터 비교와 버전 회귀에 유용합니다.

기능 설명

참조 이미지 기반 이미지-투-비디오: 1~7장의 JPG, PNG, WEBP 이미지를 외형과 구도 기준으로 삼아 생성을 구동하며, 단일 파일 최대 50MB, 가로세로 비율은 1:4~4:1을 지원하므로 기존 캐릭터 설정이나 상품 이미지를 그대로 활용할 수 있습니다.

프롬프트와 이미지 인덱스 바인딩: 프롬프트는 최대 5000자이며 장면, 움직임, 카메라, 소리를 동시에 설명할 수 있고, 배열 순서에 따라 Image1, Image2로 각 참조 이미지의 역할을 지정할 수 있습니다.

두 단계 해상도 출력: 출력 크기는 720P와 1080P 두 단계를 지원하며 각 단계마다 다섯 가지 화면 비율이 포함되어, 게재 채널에 맞춰 완성본 규격을 바로 선택할 수 있습니다.

오디오 및 길이 스위치: audio 스위치로 매칭 사운드 생성 여부를 결정하고, duration은 1~16초 사이 값을 가지므로 짧은 움직이는 이미지부터 완전한 단편 숏 클립까지 다양한 요구에 맞춥니다.

워터마크 및 시드 제어: 선택적 AI 생성 워터마크는 기본적으로 꺼져 있으며, seed 파라미터로 난수 시드를 고정하면 대량 시험 출력 시 특정 결과를 재현하고 추적하기 쉽습니다.

활용 시나리오

이커머스 및 제품 팀: 다중 상품 이미지로 전시용 짧은 영상 생성——상품의 여러 각도 이미지로 외형을 제약하고 수 초 분량의 제품 시연 클립을 만들어 상세 페이지와 게재 소재로 활용합니다.
광고 크리에이티브 팀: 캐릭터 설정 이미지로 스토리보드 구동——캐릭터와 장면 참조 이미지로 9:16 또는 16:9 숏 클립을 생성하여 제안서와 A/B 테스트의 후보 버전으로 사용합니다.
단편 드라마 및 애니메이션 크리에이터: 캐릭터 일관성 클립——캐릭터 참조 이미지를 고정해 숏 클립을 대량 생성하고 이어 붙여 캐릭터 중심의 짧은 클립을 개념 검증에 활용합니다.
사운드가 필요한 소셜 콘텐츠 제작——오디오 생성을 켜서 소리가 포함된 세로형 짧은 영상을 만들고, 소셜 플랫폼 게시 전 샘플 평가에 바로 사용합니다.

제한 사항 및 선택 가이드

단일 생성 길이 상한은 16초이므로, 긴 영상이나 복잡한 연속 서사는 직접 스토리보드를 나누어 여러 번 생성한 뒤 편집·연결해야 합니다. 참조 이미지는 공개 인터넷에서 접근 가능한 JPG, PNG, WEBP 파일이어야 하며, 해상도와 화면 비율이 1:4~4:1 범위를 벗어난 소재는 사용할 수 없습니다. 오디오 스위치는 기본적으로 꺼져 있으므로 소리가 필요하면 반드시 명시적으로 켜야 합니다. 단일 이미지로 구동하는 일반적인 이미지-투-비디오가 필요하다면 같은 계열의 다른 라인을 참고할 수 있으며, 장편이나 더 복잡한 서사가 필요할 때는 이 라인의 단일 클립 포지셔닝이 적합하지 않습니다.

생성 작업 제출

POST 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-mix/reference-to-video

routestring선택

현재 고정 값: default

inputobject필수

vidu-q3-mix/reference-to-video 및 루트 default의 비즈니스 파라미터 객체. 아래 파라미터 표를 참조하세요.

seedinteger선택min 0max 2147483647

생성 결과를 재현하기 위한 랜덤 시드로, 0에서 2147483647 사이의 정수를 사용합니다.

sizestring선택기본값: "1280*720"

출력 화면 크기로, 형식은 WIDTH*HEIGHT이며 기본값은 1280*720입니다. 720P와 1080P 두 등급으로 나뉘고, 각 등급마다 다양한 화면 비율을 포함하며 초 단위 과금 가격은 등급에 따라 다릅니다.

옵션:1280*7201280*9601280*1280960*1280720*12801920*10801920*14401808*1808

전체 보기(2개)

1440*19201080*1920

audioboolean선택기본값: false

화면과 일치하는 소리를 생성할지 여부이며, 불리언 값이고 기본값은 false로 무음 비디오를 출력합니다.

promptstring필수minLength 1maxLength 5000

장면, 움직임, 카메라 및 소리를 설명하는 프롬프트입니다. 참조 이미지는 배열 순서대로 Image1, Image2 등으로 인덱싱하여 프롬프트에서 참조합니다.

durationinteger필수기본값: 5min 1max 16

출력 비디오 길이로, 단위는 초이며 1에서 16 사이의 정수를 사용하고 기본값은 5입니다.

watermarkboolean선택기본값: false

화면 오른쪽 아래에 AI 생성 워터마크를 추가할지 여부이며, 불리언 값이고 기본값은 false입니다.

reference_image_urlsarray필수minItems 1maxItems 7

참조 이미지 배열로, 1에서 7장의 참조 이미지(인물, 사물 또는 스타일)를 제공합니다. 요소는 이미지 URL이며, JPG/PNG/WEBP 형식이고 장당 50MB 이하, 화면 비율 1:4에서 4:1이며 공개적으로 접근 가능해야 합니다.

Array [ string ]

callbackobject선택

종료 상태 알림 설정. 생략하면 콜백이 전송되지 않으며 호출 측에서 폴링합니다.

콜백(Webhook)

생성 시 callback.url을 지정하면 태스크 종료 시 HiAPI가 서비스로 POST하여 폴링이 필요 없습니다. 콜백 본문은 태스크 상세와 동일한 구조입니다. 서명 검증·재시도·멱등에 대한 자세한 내용은 통합 비동기 API 소개 페이지의 콜백 설명을 참고하세요.

urlstring필수

callback 사용 시 필수. 태스크 종료 후 이 URL로 POST됩니다. 유효한 http(s) URL이어야 합니다.

whenstring선택기본값: "final"

현재는 final만 지원(success / fail 모두 알림).

옵션:final

storagestring선택기본값: "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-mix/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-mix/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-mix/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"
}

작업 상세 조회

GET 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"
    }
  }
}