curl --request POST \
--url https://api.apimart.ai/v1/videos/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "viduq4-preview",
"prompt": "소녀가 뒤돌아 미소 짓고 긴 머리카락이 바람에 날리며 카메라가 천천히 다가간다",
"image_urls": ["https://example.com/first-frame.png"],
"duration": 5,
"resolution": "1080p"
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/videos/generations",
headers={"Authorization": "Bearer <token>"},
json={
"model": "viduq4-preview",
"prompt": "소녀가 뒤돌아 미소 짓고 긴 머리카락이 바람에 날리며 카메라가 천천히 다가간다",
"image_urls": ["https://example.com/first-frame.png"],
"duration": 5,
"resolution": "1080p"
}
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"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());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
Vidu Q4 Preview
Vidu Q4 Preview 동영상 생성
첫 프레임 1장 또는 참조 이미지 최대 15장과 참조 오디오 최대 3개로 동영상 생성. 3~16초, 최대 4K, 기본 오디오 포함.
POST
/
v1
/
videos
/
generations
curl --request POST \
--url https://api.apimart.ai/v1/videos/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "viduq4-preview",
"prompt": "소녀가 뒤돌아 미소 짓고 긴 머리카락이 바람에 날리며 카메라가 천천히 다가간다",
"image_urls": ["https://example.com/first-frame.png"],
"duration": 5,
"resolution": "1080p"
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/videos/generations",
headers={"Authorization": "Bearer <token>"},
json={
"model": "viduq4-preview",
"prompt": "소녀가 뒤돌아 미소 짓고 긴 머리카락이 바람에 날리며 카메라가 천천히 다가간다",
"image_urls": ["https://example.com/first-frame.png"],
"duration": 5,
"resolution": "1080p"
}
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"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());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
이미지 기반 및 참조 소재 기반 동영상 생성을 지원합니다. 이미지 없는 텍스트 생성과 첫·마지막 프레임 지정은 지원하지 않습니다. 제출 후
data[0].task_id에서 작업 ID를 읽고 작업 조회로 상태와 결과를 확인하세요.생성 모드
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을 반환합니다.
curl --request POST \
--url https://api.apimart.ai/v1/videos/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "viduq4-preview",
"prompt": "소녀가 뒤돌아 미소 짓고 긴 머리카락이 바람에 날리며 카메라가 천천히 다가간다",
"image_urls": ["https://example.com/first-frame.png"],
"duration": 5,
"resolution": "1080p"
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/videos/generations",
headers={"Authorization": "Bearer <token>"},
json={
"model": "viduq4-preview",
"prompt": "소녀가 뒤돌아 미소 짓고 긴 머리카락이 바람에 날리며 카메라가 천천히 다가간다",
"image_urls": ["https://example.com/first-frame.png"],
"duration": 5,
"resolution": "1080p"
}
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"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());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
요청 헤더
string
필수
Bearer 인증 형식은
Bearer <token>이며 <token>은 APIMart API Key입니다.요청 매개변수
string
필수
소문자
viduq4-preview와 정확히 일치해야 합니다.string
동영상 생성 프롬프트. 최대 20,000자.
- 이미지 기반: 선택 사항. 생략하면 첫 프레임을 바탕으로 모델이 내용을 생성합니다.
- 참조 소재 기반: 필수. 누락 시 HTTP 400.
string[]
이미지 배열. 공개 접근 가능한 이미지 URL 또는
data:image/png;base64,... 같은 Base64 Data URL을 지원합니다.- 이미지 기반: 첫 프레임으로 사용할 이미지 1장만.
- 참조 소재 기반:
image_with_roles와 합쳐 1~15장.
image_with_roles와 함께 사용할 수 있으며 개수는 합산됩니다. first_frame_image 또는 명시적 first_frame 역할과 함께 사용하지 마세요. 역할 없는 이미지 1장은 참조 오디오 유무에 따라서도 모드가 결정됩니다.object[]
역할을 지정한 이미지 배열. 이미지 기반은 요소 1개, 참조 소재 기반은
image_urls와 합쳐 1~15장.표시 이미지 필드 표시
표시 이미지 필드 표시
image_urls와 함께 참조 이미지를 제공할 수 있지만 첫 프레임 역할과 참조 소재는 혼합할 수 없습니다.string
이미지 기반 전용. 첫 프레임의 공개 URL 또는 Base64 Data URL을 전달합니다.이 필드를 사용할 때 다른 이미지나 참조 오디오를 제공하지 마세요. 참조 소재 기반은
image_urls 또는 image_with_roles를 사용하세요.string[]
참조 오디오 URL 배열. 참조 소재 기반 전용이며
audio_url과 합쳐 최대 3개.MP3 형식, 각 3~12초, 각 50MB 이하. 참조 오디오를 제공해도 이미지 최소 1장과 prompt가 필요합니다.오디오 형식이나 길이가 요건에 맞지 않으면 제출 시 동기 HTTP 400이 아닌 실행 중 작업 실패로 처리되며 전액 환불됩니다.string
단일 참조 오디오 URL.
audio_urls와 동일한 요건이 적용되며 두 필드 합계 최대 3개.string
기본값:"16:9"
참조 소재 기반 전용.
1:1, 9:16, 16:9, 3:4, 4:3 지원. 기본값은 16:9.이미지 기반에서는 첫 프레임이 화면비를 결정하므로 이 매개변수는 무시됩니다.string
aspect_ratio의 호환 필드로 동일한 값을 지원합니다. 둘 중 하나만 사용하는 것을 권장합니다. 이미지 기반에서는 적용되지 않습니다.integer
기본값:"5"
동영상 길이(초). 316초 지원, 12초 미지원.
string
기본값:"720p"
해상도는
540p, 720p, 1080p, 2K, 4K를 지원하며 대소문자를 구분하지 않습니다.boolean
기본값:"true"
대화와 효과음이 포함된 동영상을 출력할지 여부.
true: 오디오가 포함된 동영상(기본값).false: 무음 동영상.
integer
난수 시드. 생략하거나
0을 전달하면 무작위로 생성합니다.소재 요건
- 이미지 기반: 첫 프레임 이미지 정확히 1장이 필수이며 참조 오디오는 허용하지 않습니다.
- 참조 소재 기반: 참조 이미지 1~15장이 필수이며 참조 오디오는 선택 사항으로 최대 3개.
- PNG, JPEG, JPG, WEBP 지원. 이미지당 최대 50MB.
- Base64 사용 시 전체 요청 본문은 20MB 미만이어야 합니다. 공개 URL을 권장합니다.
- 이미지 URL은 공개 접근 가능해야 합니다. 예시 URL을 실제 접근 가능한 이미지 주소로 바꾸세요.
두 모드 모두 이미지가 필수이며
last_frame_image는 지원하지 않습니다. 첫 프레임과 참조 소재 혼합, 이미지·오디오 개수 초과 등은 제출 시 HTTP 400을 반환하고 작업을 생성하거나 과금하지 않습니다. 참조 오디오 형식·길이 오류는 실행 중 실패하며 환불됩니다.요청 예시
첫 프레임만 제공하고 프롬프트 생략
{
"model": "viduq4-preview",
"image_urls": ["https://example.com/first-frame.png"]
}
역할이 지정된 첫 프레임과 4K 출력
{
"model": "viduq4-preview",
"prompt": "카메라가 천천히 다가가고 인물이 자연스럽게 미소 짓는다",
"image_with_roles": [
{
"url": "https://example.com/first-frame.png",
"role": "first_frame"
}
],
"duration": 8,
"resolution": "4K",
"audio": true
}
첫 프레임 필드로 무음 동영상 생성
{
"model": "viduq4-preview",
"first_frame_image": "https://example.com/first-frame.png",
"duration": 5,
"resolution": "1080p",
"audio": false
}
여러 이미지와 참조 오디오로 동영상 생성
{
"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장으로 참조 소재 기반 생성
{
"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을 실제 접근 가능한 소재 주소로 바꾸세요.
제출 응답
integer
응답 상태 코드. 성공은
200.array
작업 결과 조회
5~10초 간격으로 폴링하고completed 또는 failed에서 중지하세요. 통합 조회 엔드포인트를 사용합니다:
curl --request GET \
--url https://api.apimart.ai/v1/tasks/task_01K... \
--header 'Authorization: Bearer <token>'
{
"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에서 원인 확인 후 폴링 중지, 전액 환불 |
status로 완료 여부를 판단하세요.
요금
길이와 해상도로 과금: 비용 = 길이(초) × 해당 해상도의 초당 단가. 실제 가격은 모델 요금을 확인하세요. 이미지 기반과 참조 소재 기반은 동일 가격이며 오디오 유무에 따른 차이도 없습니다. 참조 이미지·오디오는 추가 요금이 없고 작업 실패 시 자동 전액 환불됩니다.일반적인 매개변수 오류
다음은 동기적으로 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를 사용하세요. 본 모델은 여러 참조 이미지를 지원하며 Vidu Q3 Mix / Standard의 참조 생성 기능도 확인할 수 있습니다. 1~2초 동영상은viduq3-pro를 선택하세요. 본 모델은 최소 3초입니다.