> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vidu Q4 Preview 비디오 생성

> Vidu Q4 Preview 모델로 비디오를 생성합니다. 이미지-비디오 변환과 다중 참조 이미지 비디오(참조 오디오 지원)를 지원합니다

> [!NOTE]
>
> **중국 본토 사용자 안내:** API 엔드포인트(Base URL)로 `https://toapis.cn`을 사용하세요. 문서 예시의 `https://toapis.com`은 `https://toapis.cn`으로 교체하세요.

* 비동기 작업 API. 제출 후 작업 ID를 반환합니다
* 지원 모델: `viduq4-preview`
* 두 가지 생성 모드:
  * **첫 프레임 이미지-비디오 변환**: 이미지 1장을 첫 프레임으로 사용
  * **참조 이미지-비디오 변환**: 여러 참조 이미지와 선택적 참조 오디오

> [!WARNING]
>
> 공개적으로 접근 가능한 이미지와 오디오 URL을 사용하세요. `image_urls`, `reference_images`, `sounds`에 base64 데이터를 직접 전달하지 마세요. 로컬 파일은 먼저 [이미지 업로드 API](https://docs.toapis.com/docs/ko/api-reference/uploads/images.md)로 URL을 받으세요.

## 인증

**Authorization** `string` *required*

모든 엔드포인트는 Bearer Token 인증이 필요합니다.

```
Authorization: Bearer YOUR_API_KEY
```

## 요청 파라미터

**model** `string` *required*

모델 이름. `viduq4-preview`로 고정됩니다.

**prompt** `string` *required*

비디오 프롬프트. 피사체, 동작, 장면, 카메라 움직임, 스타일을 설명합니다.

**image\_urls** `string[]`

이미지 URL 배열. 모드는 `video_generation_mode`와 이미지 수로 결정됩니다:

* **첫 프레임 모드**(기본값): `image_urls`에 이미지 URL을 정확히 1장 전달합니다. 이미지가 첫 프레임이 됩니다.
* **참조 모드**: `video_generation_mode`를 `reference_images_to_video`로 설정하고 `image_urls`(또는 `reference_images`)에 참조 이미지를 전달합니다.

예: `["https://example.com/first-frame.jpg"]`

**video\_generation\_mode** `string`

생성 모드 선택자.

옵션:

* `reference_images_to_video` - 다중 참조 이미지 생성. `image_urls`의 여러 이미지를 참조 이미지로 처리합니다

생략하면 첫 프레임 이미지-비디오 변환입니다. 여러 이미지, `reference_images`, `sounds`를 포함한 요청은 자동으로 참조 이미지-비디오 변환으로 라우팅됩니다.

**duration** `integer` (default: 5)

비디오 길이(초). `3`부터 `16`까지.

**resolution** `string` (default: 720p)

비디오 해상도.

옵션:

* `540p`
* `720p`
* `1080p`
* `2K`
* `4K`

**aspect\_ratio** `string`

비디오 화면 비율. 참조 모드에서 사용합니다.

옵션: `16:9`, `9:16`, `4:3`, `3:4`, `1:1`

**audio** `boolean` (default: true)

비디오에 오디오를 생성할지 여부.

**watermark** `boolean` (default: false)

생성된 비디오에 워터마크를 추가할지 여부.

**seed** `integer`

랜덤 시드. 같은 파라미터로 더 재현 가능한 결과를 얻을 수 있습니다.

**metadata** `object`

확장 파라미터. 업스트림 API가 지원하지만 최상위 필드로 노출되지 않는 항목을 전달합니다.

**metadata 필드 보기**

**is\_rec** `boolean`

프롬프트를 자동으로 확장·최적화할지 여부. 생략 시 업스트림 기본값은 `true`입니다.

**sounds** `string[]`

참조 오디오 URL 배열(참조 이미지-비디오 모드 전용). 최대 3개.

예: `["https://example.com/voice.mp3"]`

**wm\_position** `integer`

워터마크 위치. `1`부터 `4`까지. `watermark`가 `true`일 때 적용됩니다.

**wm\_url** `string`

커스텀 워터마크 이미지 URL. `watermark`가 `true`일 때 적용됩니다.

**meta\_data** `string`

커스텀 메타데이터 식별자. JSON 형식 문자열로 결과에 그대로 전달됩니다.

**callback\_url** `string`

ToAPIs 최종 작업 Webhook. 먼저 Token URL과 서명 시크릿을 설정하세요. [작업 Webhooks](https://docs.toapis.com/docs/ko/api-reference/webhooks/task-webhooks.md) 참조.

## 모드 선택

| 모드 | 트리거 방법 | 이미지 입력 | 오디오 입력 |
| - | - | - | - |
| 첫 프레임 이미지-비디오 변환 | `image_urls`에 1장(기본값) | 정확히 1장 | `audio` 플래그만 |
| 참조 이미지-비디오 변환 | `video_generation_mode: "reference_images_to_video"`, 또는 여러 이미지 / `reference_images` / `sounds` | 최대 15장의 참조 이미지 | 최대 3개의 `sounds` + `audio` 플래그 |

## 과금 단위

Vidu Q4 Preview는 생성 비디오 초당 과금이며, 해상도별로 가격이 다릅니다:

* `540p` / `720p` / `1080p` / `2K` / `4K` - 해상도가 높을수록 초당 단가가 올라갑니다

## 응답

**id** `string`

작업 ID. 작업 상태 조회에 사용합니다.

**object** `string`

객체 타입. 일반적으로 `generation.task`입니다.

**model** `string`

요청에 사용된 모델.

**status** `string`

작업 상태: `queued`, `in_progress`, `completed`, `failed`.

**created\_at** `integer`

작업 생성 타임스탬프.

## 예시

### 첫 프레임 이미지-비디오 변환

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "이미지 속 인물이 천천히 돌아보며 미소 짓는, 시네마틱 조명",
  "image_urls": ["https://example.com/portrait.jpg"],
  "duration": 5,
  "resolution": "1080p",
  "audio": true
}
```

### 참조 이미지-비디오 변환

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "참조 이미지의 캐릭터 일관성을 유지하며, 밤의 네온 거리를 걷는 모습",
  "video_generation_mode": "reference_images_to_video",
  "image_urls": [
    "https://example.com/character-front.jpg",
    "https://example.com/character-side.jpg"
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "3:4",
  "audio": true
}
```

### 참조 오디오를 포함한 참조 이미지-비디오 변환

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "캐릭터가 대사를 말하며 입모양이 동기화됨",
  "video_generation_mode": "reference_images_to_video",
  "image_urls": ["https://example.com/character.jpg"],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "metadata": {
    "sounds": ["https://example.com/voice.mp3"]
  }
}
```

### 프롬프트 확장과 워터마크

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "석양 해변을 걷는 고양이",
  "image_urls": ["https://example.com/cat.jpg"],
  "duration": 8,
  "resolution": "2K",
  "watermark": true,
  "metadata": {
    "is_rec": true
  }
}
```

> [!NOTE]
>
> 비디오 생성은 비동기입니다. [비디오 작업 상태 조회](https://docs.toapis.com/docs/ko/api-reference/tasks/video-status.md) 엔드포인트로 진행 상황과 결과를 확인하세요.

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq4-preview",
    "prompt": "이미지 속 인물이 천천히 돌아보며 미소 짓는, 시네마틱 조명",
    "image_urls": ["https://example.com/portrait.jpg"],
    "duration": 5,
    "resolution": "1080p",
    "audio": true
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "viduq4-preview",
        "prompt": "이미지 속 인물이 천천히 돌아보며 미소 짓는, 시네마틱 조명",
        "image_urls": ["https://example.com/portrait.jpg"],
        "duration": 5,
        "resolution": "1080p",
        "audio": True,
    },
)

print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://toapis.com/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/portrait.jpg"],
    duration: 5,
    resolution: "1080p",
    audio: true
  })
});

console.log(await response.json());
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.