> ## 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 Q3 비디오 생성

> Vidu Q3 비디오 모델로 비동기 비디오 작업을 생성합니다.

<Note>
  **중국 본토 사용자 안내:** 중국 본토 사용자는 `https://toapis.cn` 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 `https://toapis.com` 을 `https://toapis.cn` 로 바꿔 주세요.
</Note>

* 비동기 작업 API로, 제출 후 통일된 `generation.task` 를 반환합니다
* 공개 모델: `viduq3-pro-fast`, `viduq3-ad`, `viduq3-drama`, `viduq3-mix`

<Warning>
  `viduq3-ad`, `viduq3-drama`, `viduq3-mix` 는 순수 텍스트-비디오 생성 모델이 아닙니다. `prompt` 만 전달하지 마세요. 최소한 참조 소재가 필요합니다. 그렇지 않으면 업스트림에서 일반적으로 `InvalidParameter` 를 반환합니다. 예: `Missing required field 'subjects' in request body`。
</Warning>

## 인증

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

  ```http theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 지원 모델

| 모델 | 생성 유형 | 권장 입력 | 권장 해상도 |
| - | - | - | - |
| `viduq3-pro-fast` | 첫 프레임 이미지-비디오 | 참조 이미지 1장 | `720P` / `1080P` |
| `viduq3-ad` | 참조 비디오 생성 | 참조 비디오 + 참조 이미지 | `720P` / `1080P` |
| `viduq3-drama` | 드라마형 참조 비디오 생성 | 참조 비디오 + 참조 이미지 | `1080P` |
| `viduq3-mix` | 혼합 참조 생성 | 참조 비디오 + 참조 이미지 | `720P` / `1080P` |

## 요청 파라미터

<ParamField body="model" type="string" required>
  다음 4개의 공개 모델 이름만 지원합니다:

  * `viduq3-pro-fast`
  * `viduq3-ad`
  * `viduq3-drama`
  * `viduq3-mix`
</ParamField>

<ParamField body="prompt" type="string" required>
  프롬프트.

  참조 생성 모델에서도 `prompt` 를 항상 입력하여 샷, 동작, 리듬, 스타일을 설명하는 것을 권장합니다.
</ParamField>

<ParamField body="image_urls" type="string[]">
  참조 이미지 URL 목록.

  * `viduq3-pro-fast`: 첫 번째 이미지만 사용하여 첫 프레임으로 사용
  * `viduq3-ad` / `viduq3-drama` / `viduq3-mix`: 피사체/스타일 참조 이미지 1장 이상 권장

  호환 필드:

  * `input_reference`
  * `reference_images`
  * `images`
  * `image`
</ParamField>

<ParamField body="url" type="string">
  참조 비디오 URL.

  `viduq3-ad` / `viduq3-drama` / `viduq3-mix` 에만 권장됩니다. 기본 참조 비디오 하나를 전달하는 것과 동일합니다.
</ParamField>

<ParamField body="video_list" type="array">
  참조 비디오 목록.

  `viduq3-ad` / `viduq3-drama` / `viduq3-mix` 에만 사용됩니다. 각 항목은 다음을 지원합니다:

  * `video_url`
  * `refer_type` (선택)
  * `keep_original_sound` (선택)
</ParamField>

<ParamField body="duration" type="integer" default={5}>
  비디오 길이(초). 기본값 `5`.
</ParamField>

<ParamField body="resolution" type="string" default="720P">
  해상도. `720P`, `1080P` 지원.

  권장:

  * `viduq3-drama` 는 `1080P` 우선 사용
</ParamField>

<ParamField body="audio" type="boolean">
  오디오 생성 여부.

  현재 서버 측 기본 동작:

  * `viduq3-pro-fast`: 기본값 `true`
  * `viduq3-ad`: 기본값 `true`
  * `viduq3-mix`: 기본값 `true`
  * `viduq3-drama`: 값을 명시적으로 전달하고 기본값에 의존하지 마세요
</ParamField>

<ParamField body="watermark" type="boolean" default={false}>
  워터마크 추가 여부.
</ParamField>

<ParamField body="seed" type="integer">
  랜덤 시드.
</ParamField>

<ParamField body="metadata" type="object">
  확장 파라미터. 업스트림 비디오 요청 구조에 따라 그대로 전달됩니다.

  일반적인 사용법:

  * `metadata.input.first_frame_url`
  * `metadata.input.last_frame_url`
  * `metadata.input.audio_url`
  * `metadata.parameters.audio`
  * `metadata.parameters.watermark`

  <Warning>
    `viduq3-ad` / `viduq3-drama` / `viduq3-mix` 는 업스트림 측에서 피사체의 구조화된 입력(예: `subjects`)을 요구할 수 있습니다. 순수 텍스트 prompt 만 있는 요청은 일반적으로 바로 실패합니다.
  </Warning>
</ParamField>

## 입력 규칙

### 1. `viduq3-pro-fast`

* 첫 프레임 이미지-비디오 모델입니다
* 이미지를 최소 1장 전달해야 합니다
* 여러 장을 전달하면 현재 첫 번째 이미지만 사용됩니다
* "정지 이미지를 움직이게 하는" 시나리오에 적합합니다

### 2. `viduq3-ad` / `viduq3-drama` / `viduq3-mix`

* 참조 비디오 생성 모델로, 순수 prompt 호출은 권장하지 않습니다
* 최소 권장 입력:
  * 참조 비디오 1개: `url` 또는 `video_list`
  * 참조 이미지 1장: `image_urls` 또는 호환 이미지 필드
* 피사체/참조 소재가 없으면 업스트림에서 다음을 반환할 수 있습니다:
  * `InvalidParameter`
  * `Missing required field 'subjects' in request body`

## 요청 예시

### `viduq3-pro-fast` 첫 프레임 이미지-비디오

```bash theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/videos/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-pro-fast",
    "prompt": "让角色自然抬头微笑，镜头轻微推进，保留原画风格。",
    "image_urls": [
      "https://example.com/first-frame.png"
    ],
    "duration": 5,
    "resolution": "720P",
    "audio": true,
    "watermark": false
  }'
```

### `viduq3-ad` 참조 비디오 생성

```bash theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/videos/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-ad",
    "prompt": "延续参考视频中的节奏与镜头语言，让主角走入商场中庭并面向镜头挥手。",
    "url": "https://example.com/reference-video.mp4",
    "image_urls": [
      "https://example.com/subject-reference.png"
    ],
    "duration": 5,
    "resolution": "1080P",
    "audio": true
  }'
```

### `viduq3-drama` 드라마형 참조 생성

```bash theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/videos/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-drama",
    "prompt": "保持角色一致性，情绪逐步递进，镜头由中景切到近景。",
    "video_list": [
      {
        "video_url": "https://example.com/reference-scene.mp4"
      }
    ],
    "image_urls": [
      "https://example.com/character.png"
    ],
    "duration": 5,
    "resolution": "1080P",
    "watermark": false
  }'
```

### `viduq3-mix` 혼합 참조 생성

```bash theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/videos/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-mix",
    "prompt": "融合参考视频动作与参考图角色设定，生成一个更具广告感的过场镜头。",
    "url": "https://example.com/reference-action.mp4",
    "image_urls": [
      "https://example.com/brand-character.png"
    ],
    "duration": 5,
    "resolution": "720P",
    "audio": true
  }'
```

## 제출 성공 응답

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-pro-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1784169600
}
```

## 작업 조회

`GET /v1/videos/generations/{task_id}`

처리 중:

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-pro-fast",
  "status": "in_progress",
  "progress": 60,
  "created_at": 1784169600
}
```

성공:

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-pro-fast",
  "status": "completed",
  "progress": 100,
  "created_at": 1784169600,
  "completed_at": 1784169660,
  "expires_at": 1784256060,
  "result": {
    "type": "video",
    "data": [
      {
        "url": "https://files.toapis.com/videos/vid_01KABCDEF1234567890.mp4",
        "format": "mp4"
      }
    ]
  }
}
```

실패:

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-ad",
  "status": "failed",
  "progress": 100,
  "created_at": 1784169600,
  "completed_at": 1784169620,
  "error": {
    "code": "InvalidParameter",
    "message": "Missing required field 'subjects' in request body"
  }
}
```

## 설명

* 제출 후 ToAPIs 가 업스트림 작업 상태를 통합 폴링한 뒤 표준 비디오 작업 결과를 반환합니다.
* `viduq3-pro-fast` 는 현재 가장 안정적인 연동 형태로, 첫 프레임 이미지-비디오에 적합합니다.
* `viduq3-ad`, `viduq3-drama`, `viduq3-mix` 는 참조 소재 요구 사항이 더 엄격합니다. 연동 전 위 예시에 따라 소재를 완전히 준비하고 prompt 만 전달하지 마세요.


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