> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Vidu Q4 Preview 동영상 생성 > 첫 프레임 1장 또는 참조 이미지 최대 15장과 참조 오디오 최대 3개로 동영상 생성. 3~16초, 최대 4K, 기본 오디오 포함. 이미지 기반 및 참조 소재 기반 동영상 생성을 지원합니다. 이미지 없는 텍스트 생성과 첫·마지막 프레임 지정은 지원하지 않습니다. 제출 후 `data[0].task_id`에서 작업 ID를 읽고 [작업 조회](/ko/api-reference/tasks/status)로 상태와 결과를 확인하세요. ## 생성 모드 `viduq4-preview`는 이미지, 역할, 참조 오디오에 따라 모드를 자동 선택합니다. 별도의 모드 매개변수는 필요하지 않습니다. | 입력 | 모드 | | - | - | | `first_frame_image`만 또는 `role: "first_frame"` 이미지 1장 | 이미지 기반 | | 역할 없는 이미지 1장, 참조 오디오 없음 | 이미지 기반 | | `reference_image` 또는 `reference` 역할 포함, 명시적 첫 프레임 없음 | 참조 소재 기반 | | 총 이미지 2\~15장, 명시적 첫 프레임 없음 | 참조 소재 기반 | | 참조 오디오와 이미지 1\~15장, 명시적 첫 프레임 없음 | 참조 소재 기반 | * **이미지 기반**: 첫 프레임 정확히 1장. 프롬프트는 선택 사항이며 참조 오디오는 사용할 수 없습니다. * **참조 소재 기반**: 참조 이미지 1\~15장, 참조 오디오 최대 3개, **프롬프트 필수**. 참조 오디오 없이 이미지 1장만 사용할 때는 `role: "reference_image"`를 명시해야 합니다. 그렇지 않으면 이미지 기반으로 처리됩니다. * 명시적 첫 프레임(`first_frame_image` 또는 `role: "first_frame"`)을 다른 이미지, 참조 이미지 역할 또는 참조 오디오와 함께 사용하면 HTTP 400을 반환합니다. ```bash cURL theme={null} curl --request POST \ --url https://api.apimart.ai/v1/videos/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "viduq4-preview", "prompt": "소녀가 뒤돌아 미소 짓고 긴 머리카락이 바람에 날리며 카메라가 천천히 다가간다", "image_urls": ["https://example.com/first-frame.png"], "duration": 5, "resolution": "1080p" }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.apimart.ai/v1/videos/generations", headers={"Authorization": "Bearer "}, json={ "model": "viduq4-preview", "prompt": "소녀가 뒤돌아 미소 짓고 긴 머리카락이 바람에 날리며 카메라가 천천히 다가간다", "image_urls": ["https://example.com/first-frame.png"], "duration": 5, "resolution": "1080p" } ) response.raise_for_status() print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.apimart.ai/v1/videos/generations", { method: "POST", headers: { Authorization: "Bearer ", "Content-Type": "application/json" }, body: JSON.stringify({ model: "viduq4-preview", prompt: "소녀가 뒤돌아 미소 짓고 긴 머리카락이 바람에 날리며 카메라가 천천히 다가간다", image_urls: ["https://example.com/first-frame.png"], duration: 5, resolution: "1080p" }) }); if (!response.ok) throw new Error(await response.text()); console.log(await response.json()); ``` ```json 200 theme={null} { "code": 200, "data": [ { "status": "submitted", "task_id": "task_01K..." } ] } ``` ## 요청 헤더 Bearer 인증 형식은 `Bearer `이며 ``은 APIMart API Key입니다. ## 요청 매개변수 소문자 `viduq4-preview`와 정확히 일치해야 합니다. 동영상 생성 프롬프트. 최대 20,000자. * 이미지 기반: 선택 사항. 생략하면 첫 프레임을 바탕으로 모델이 내용을 생성합니다. * 참조 소재 기반: 필수. 누락 시 HTTP 400. 이미지 배열. 공개 접근 가능한 이미지 URL 또는 `data:image/png;base64,...` 같은 Base64 Data URL을 지원합니다. * 이미지 기반: 첫 프레임으로 사용할 이미지 1장만. * 참조 소재 기반: `image_with_roles`와 합쳐 1\~15장. `image_with_roles`와 함께 사용할 수 있으며 개수는 합산됩니다. `first_frame_image` 또는 명시적 `first_frame` 역할과 함께 사용하지 마세요. 역할 없는 이미지 1장은 참조 오디오 유무에 따라서도 모드가 결정됩니다. 역할을 지정한 이미지 배열. 이미지 기반은 요소 1개, 참조 소재 기반은 `image_urls`와 합쳐 1\~15장. 이미지의 공개 URL 또는 Base64 Data URL. 이미지 역할. 대소문자를 구분하지 않습니다: * `first_frame`: 이미지 기반 생성의 첫 프레임. * `reference_image`: 참조 소재 기반 생성의 참조 이미지. `reference`도 허용합니다. * 생략 또는 빈 값: 참조 오디오가 없으면 총 이미지 수로 판단합니다. 1장은 이미지 기반, 2장 이상은 참조 소재 기반입니다. 참조 오디오가 있으면 참조 소재 기반입니다. `last_frame` 등 다른 값은 동기적으로 HTTP 400을 반환합니다. `image_urls`와 함께 참조 이미지를 제공할 수 있지만 첫 프레임 역할과 참조 소재는 혼합할 수 없습니다. 이미지 기반 전용. 첫 프레임의 공개 URL 또는 Base64 Data URL을 전달합니다. 이 필드를 사용할 때 다른 이미지나 참조 오디오를 제공하지 마세요. 참조 소재 기반은 `image_urls` 또는 `image_with_roles`를 사용하세요. 참조 오디오 URL 배열. 참조 소재 기반 전용이며 `audio_url`과 합쳐 최대 3개. MP3 형식, 각 3\~12초, 각 50MB 이하. 참조 오디오를 제공해도 이미지 최소 1장과 `prompt`가 필요합니다. 오디오 형식이나 길이가 요건에 맞지 않으면 제출 시 동기 HTTP 400이 아닌 실행 중 작업 실패로 처리되며 전액 환불됩니다. 단일 참조 오디오 URL. `audio_urls`와 동일한 요건이 적용되며 두 필드 합계 최대 3개. 참조 소재 기반 전용. `1:1`, `9:16`, `16:9`, `3:4`, `4:3` 지원. 기본값은 `16:9`. 이미지 기반에서는 첫 프레임이 화면비를 결정하므로 이 매개변수는 무시됩니다. `aspect_ratio`의 호환 필드로 동일한 값을 지원합니다. 둘 중 하나만 사용하는 것을 권장합니다. 이미지 기반에서는 적용되지 않습니다. 동영상 길이(초). 3~~16초 지원, 1~~2초 미지원. 해상도는 `540p`, `720p`, `1080p`, `2K`, `4K`를 지원하며 대소문자를 구분하지 않습니다. 대화와 효과음이 포함된 동영상을 출력할지 여부. * `true`: 오디오가 포함된 동영상(기본값). * `false`: 무음 동영상. 오디오 유무와 관계없이 가격은 같습니다. 난수 시드. 생략하거나 `0`을 전달하면 무작위로 생성합니다. ## 소재 요건 * 이미지 기반: 첫 프레임 이미지 정확히 1장이 필수이며 참조 오디오는 허용하지 않습니다. * 참조 소재 기반: 참조 이미지 1\~15장이 필수이며 참조 오디오는 선택 사항으로 최대 3개. * PNG, JPEG, JPG, WEBP 지원. 이미지당 최대 50MB. * Base64 사용 시 전체 요청 본문은 20MB 미만이어야 합니다. 공개 URL을 권장합니다. * 이미지 URL은 공개 접근 가능해야 합니다. 예시 URL을 실제 접근 가능한 이미지 주소로 바꾸세요. 두 모드 모두 이미지가 필수이며 `last_frame_image`는 지원하지 않습니다. 첫 프레임과 참조 소재 혼합, 이미지·오디오 개수 초과 등은 제출 시 HTTP 400을 반환하고 작업을 생성하거나 과금하지 않습니다. 참조 오디오 형식·길이 오류는 실행 중 실패하며 환불됩니다. ## 요청 예시 ### 첫 프레임만 제공하고 프롬프트 생략 ```json theme={null} { "model": "viduq4-preview", "image_urls": ["https://example.com/first-frame.png"] } ``` 기본으로 5초, 720p, 오디오 포함 동영상을 생성합니다. ### 역할이 지정된 첫 프레임과 4K 출력 ```json theme={null} { "model": "viduq4-preview", "prompt": "카메라가 천천히 다가가고 인물이 자연스럽게 미소 짓는다", "image_with_roles": [ { "url": "https://example.com/first-frame.png", "role": "first_frame" } ], "duration": 8, "resolution": "4K", "audio": true } ``` ### 첫 프레임 필드로 무음 동영상 생성 ```json theme={null} { "model": "viduq4-preview", "first_frame_image": "https://example.com/first-frame.png", "duration": 5, "resolution": "1080p", "audio": false } ``` ### 여러 이미지와 참조 오디오로 동영상 생성 ```json theme={null} { "model": "viduq4-preview", "prompt": "이미지1의 소년이 참조 오디오의 내용으로 이미지2의 소녀에게 말하고 배경은 이미지3의 카페", "image_urls": [ "https://example.com/boy.png", "https://example.com/girl.png", "https://example.com/cafe.png" ], "audio_urls": ["https://example.com/line.mp3"], "aspect_ratio": "16:9", "duration": 8, "resolution": "720p" } ``` ### 이미지 1장으로 참조 소재 기반 생성 ```json theme={null} { "model": "viduq4-preview", "prompt": "참조 이미지의 인물이 카페에 들어가 직원에게 손을 흔든다", "image_with_roles": [ { "url": "https://example.com/person.png", "role": "reference_image" } ], "aspect_ratio": "9:16", "duration": 5, "resolution": "1080p" } ``` 이 예시는 참조 오디오 없이 `reference_image` 역할로 참조 소재 기반 모드를 명시합니다. 모든 이미지·오디오 URL을 실제 접근 가능한 소재 주소로 바꾸세요. ## 제출 응답 응답 상태 코드. 성공은 `200`. 작업 제출 결과. `submitted`는 제출 성공을 의미하며 동영상 생성 완료를 의미하지 않습니다. 상태와 결과 조회에 사용하는 작업 ID. ## 작업 결과 조회 5\~10초 간격으로 폴링하고 `completed` 또는 `failed`에서 중지하세요. 통합 조회 엔드포인트를 사용합니다: ```bash theme={null} curl --request GET \ --url https://api.apimart.ai/v1/tasks/task_01K... \ --header 'Authorization: Bearer ' ``` 성공 응답 예시(동영상 URL은 자리표시자): ```json theme={null} { "code": 200, "data": { "id": "task_01K...", "status": "completed", "progress": 100, "result": { "videos": [ { "url": ["https://example.com/generated-video.mp4"] } ] } } } ``` | 상태 | 처리 | | - | - | | `pending` | 대기 중, 폴링 계속 | | `processing` | 생성 중, 폴링 계속 | | `completed` | 성공, `data.result.videos[0].url` 배열에서 동영상 링크 확인 | | `failed` | 실패, `data.error.message`에서 원인 확인 후 폴링 중지, 전액 환불 | 동영상 링크는 24시간 동안 유효합니다. 즉시 다운로드하여 저장하세요. 고정 진행률이 아닌 `status`로 완료 여부를 판단하세요. ## 요금 길이와 해상도로 과금: 비용 = 길이(초) × 해당 해상도의 초당 단가. 실제 가격은 [모델 요금](https://apimart.ai/pricing)을 확인하세요. 이미지 기반과 참조 소재 기반은 동일 가격이며 오디오 유무에 따른 차이도 없습니다. 참조 이미지·오디오는 추가 요금이 없고 작업 실패 시 자동 전액 환불됩니다. ## 일반적인 매개변수 오류 다음은 동기적으로 HTTP 400을 반환하며 작업 생성 및 과금이 없습니다: | 문제 | 해결 | | - | - | | 이미지 없음 | 이미지 기반은 첫 프레임 1장, 참조 소재 기반은 참조 이미지 1\~15장 제공 | | 명시적 첫 프레임과 다른 이미지·참조 역할·참조 오디오 혼합 | 이미지 기반은 첫 프레임 1장만 유지, 참조 소재 기반은 명시적 첫 프레임 필드·역할 제거 | | `last_frame` 등 지원하지 않는 `role` | `first_frame`, `reference_image`, `reference` 또는 빈 값 사용 | | 참조 이미지 15장 초과 | `image_urls`와 `image_with_roles` 합계를 최대 15장으로 제한 | | 참조 오디오 3개 초과 | `audio_urls`와 `audio_url` 합계를 최대 3개로 제한 | | 참조 소재 기반에서 `prompt` 누락 | 최대 20,000자의 프롬프트 추가 | | `21:9` 등 지원하지 않는 참조 생성 화면비 | `1:1`, `9:16`, `16:9`, `3:4`, `4:3` 사용 | | `last_frame_image` 제공 | 필드 제거. 첫·마지막 프레임 지정은 미지원 | | `duration`이 3 미만 또는 16 초과 | 3\~16초의 정수 사용 | | `480p`, `8K` 등 미지원 해상도 | `540p`, `720p`, `1080p`, `2K`, `4K` 사용 | ## 기타 Vidu 모델 텍스트 기반 생성이나 첫·마지막 프레임 지정은 [Vidu Q3 Pro / Turbo](/ko/api-reference/videos/vidu-q3-pro/generation)를 사용하세요. 본 모델은 여러 참조 이미지를 지원하며 [Vidu Q3 Mix / Standard](/ko/api-reference/videos/vidu-q3/generation)의 참조 생성 기능도 확인할 수 있습니다. 1\~2초 동영상은 `viduq3-pro`를 선택하세요. 본 모델은 최소 3초입니다. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.