> ## 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`으로 교체하세요.
</Note>

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

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

## 인증

<ParamField header="Authorization" type="string" required>
  모든 엔드포인트는 Bearer Token 인증이 필요합니다.

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 요청 파라미터

<ParamField body="model" type="string" required>
  모델 이름. `viduq4-preview`로 고정됩니다.
</ParamField>

<ParamField body="prompt" type="string" required>
  비디오 프롬프트. 피사체, 동작, 장면, 카메라 움직임, 스타일을 설명합니다.
</ParamField>

<ParamField body="image_urls" type="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"]`
</ParamField>

<ParamField body="video_generation_mode" type="string">
  생성 모드 선택자.

  옵션:

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

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

<ParamField body="duration" type="integer" default="5">
  비디오 길이(초). `3`부터 `16`까지.
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  비디오 해상도.

  옵션:

  * `540p`
  * `720p`
  * `1080p`
  * `2K`
  * `4K`
</ParamField>

<ParamField body="aspect_ratio" type="string">
  비디오 화면 비율. 참조 모드에서 사용합니다.

  옵션: `16:9`, `9:16`, `4:3`, `3:4`, `1:1`
</ParamField>

<ParamField body="audio" type="boolean" default="true">
  비디오에 오디오를 생성할지 여부.
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  생성된 비디오에 워터마크를 추가할지 여부.
</ParamField>

<ParamField body="seed" type="integer">
  랜덤 시드. 같은 파라미터로 더 재현 가능한 결과를 얻을 수 있습니다.
</ParamField>

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

  <Expandable title="metadata 필드 보기">
    <ParamField body="is_rec" type="boolean">
      프롬프트를 자동으로 확장·최적화할지 여부. 생략 시 업스트림 기본값은 `true`입니다.
    </ParamField>

    <ParamField body="sounds" type="string[]">
      참조 오디오 URL 배열(참조 이미지-비디오 모드 전용). 최대 3개.

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

    <ParamField body="wm_position" type="integer">
      워터마크 위치. `1`부터 `4`까지. `watermark`가 `true`일 때 적용됩니다.
    </ParamField>

    <ParamField body="wm_url" type="string">
      커스텀 워터마크 이미지 URL. `watermark`가 `true`일 때 적용됩니다.
    </ParamField>

    <ParamField body="meta_data" type="string">
      커스텀 메타데이터 식별자. JSON 형식 문자열로 결과에 그대로 전달됩니다.
    </ParamField>

    <ParamField body="callback_url" type="string">
      ToAPIs 최종 작업 Webhook. 먼저 Token URL과 서명 시크릿을 설정하세요. [작업 Webhooks](/docs/ko/api-reference/webhooks/task-webhooks) 참조.
    </ParamField>
  </Expandable>
</ParamField>

## 모드 선택

| 모드 | 트리거 방법 | 이미지 입력 | 오디오 입력 |
| - | - | - | - |
| 첫 프레임 이미지-비디오 변환 | `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` - 해상도가 높을수록 초당 단가가 올라갑니다

## 응답

<ResponseField name="id" type="string">
  작업 ID. 작업 상태 조회에 사용합니다.
</ResponseField>

<ResponseField name="object" type="string">
  객체 타입. 일반적으로 `generation.task`입니다.
</ResponseField>

<ResponseField name="model" type="string">
  요청에 사용된 모델.
</ResponseField>

<ResponseField name="status" type="string">
  작업 상태: `queued`, `in_progress`, `completed`, `failed`.
</ResponseField>

<ResponseField name="created_at" type="integer">
  작업 생성 타임스탬프.
</ResponseField>

## 예시

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

```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>
  비디오 생성은 비동기입니다. [비디오 작업 상태 조회](../../tasks/video-status) 엔드포인트로 진행 상황과 결과를 확인하세요.
</Note>

<RequestExample>
  ```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());
  ```
</RequestExample>


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