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

# 비디오 생성

## 소개

비디오 생성 API는 텍스트-투-비디오, 이미지-투-비디오, 비디오-투-비디오 등을 지원합니다. 통합 API 인터페이스를 통해 Sora 2, Veo, Ali Wanxiang, Doubao Seedance 등 여러 주류 비디오 생성 모델을 호출할 수 있습니다.

**중요 안내**: 비디오 생성은 비동기 작업입니다. 먼저 작업을 제출하여 작업 ID를 받은 후, 성공할 때까지 작업 상태를 폴링해야 합니다.

## 지원 모델 및 기능

| 모델 시리즈              | 모델 이름                                    | 지원 기능                                                 |
| ------------------- | ---------------------------------------- | ----------------------------------------------------- |
| **Sora 2**          | `sora-2`                                 | 텍스트-투-비디오, 이미지-투-비디오, 비디오-투-비디오 (Remix 모드)            |
| **Google Veo**      | `veo-3.0-fast-generate-001`              | 텍스트-투-비디오 (첫 프레임 모드)                                  |
|                     | `veo-3.1-fast-generate-preview`          | 텍스트-투-비디오 (첫 프레임 모드, 첫/마지막 프레임 모드)                    |
| **Ali Wanxiang**    | `wan2.5-t2v-preview`                     | 텍스트-투-비디오                                             |
|                     | `wan2.5-i2v-preview`                     | 이미지-투-비디오 (첫 프레임 모드)                                  |
| **Doubao Seedance** | `doubao-seedance-1-0-lite-t2v-250428`    | 텍스트-투-비디오                                             |
|                     | `doubao-seedance-1-0-lite-i2v-250428`    | 이미지-투-비디오 (첫 프레임 모드, 첫/마지막 프레임 모드, 참조 이미지 모드)         |
|                     | `doubao-seedance-1-0-pro-250528`         | 텍스트-투-비디오 (첫 프레임 모드)                                  |
|                     | `doubao-seedance-1-5-pro-251215`         | 텍스트-투-비디오, 이미지-투-비디오 (첫 프레임 모드, 첫/마지막 프레임 모드), 오디오 포함 |
|                     | `doubao-seedance-1-5-pro-251215-noAudio` | 텍스트-투-비디오, 이미지-투-비디오 (첫 프레임 모드, 첫/마지막 프레임 모드), 무음 비디오 |

**기능 설명**:

* **텍스트-투-비디오 (T2V)**: 텍스트 프롬프트만으로 비디오 생성
* **이미지-투-비디오 (I2V)**: 참조 이미지 기반 비디오 생성
  * **첫 프레임 모드**: 첫 프레임 이미지를 시작 장면으로 사용
  * **첫/마지막 프레임 모드**: 첫 프레임과 마지막 프레임 이미지로 비디오 시작·종료 장면 제어
  * **참조 이미지 모드**: 참조 이미지를 스타일 참조로 사용(일부 모델만 지원)
* **비디오-투-비디오 (Remix)**: 기존 비디오 기반 재생성(Sora 2만 지원)

## 인증

<ParamField header="Authorization" type="string" required>
  Bearer Token, 예: `Bearer sk-xxxxxxxxxx`
</ParamField>

## API 엔드포인트

### 비디오 작업 제출

**POST** `/v1/video/generations`

비디오 생성 작업을 제출하고 후속 조회용 작업 ID를 반환합니다.

### 비디오 작업 조회

**GET** `/v1/video/generations/{task_id}`

작업 ID로 비디오 생성 작업의 상태와 결과를 조회합니다.

#### 경로 매개변수

<ParamField path="task_id" type="string" required>
  작업 제출 인터페이스에서 반환된 비디오 생성 작업 ID
</ParamField>

#### 응답 예제

**작업 상태 설명**:

| 상태            | 설명                  | 권장 조치    |
| ------------- | ------------------- | -------- |
| `queued`      | 작업 대기열에 있음, 처리 대기 중 | 계속 폴링    |
| `in_progress` | 작업 처리 중             | 계속 폴링    |
| `succeeded`   | 작업 성공 완료            | 비디오 다운로드 |
| `failed`      | 작업 실패               | 오류 원인 확인 |

**응답 예제 (대기 중)**:

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "queued",
  "format": "mp4"
}
```

**응답 예제 (처리 중)**:

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "in_progress",
  "format": "mp4"
}
```

**응답 예제 (완료)**:

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "succeeded",
  "format": "mp4"
}
```

**응답 예제 (실패)**:

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "failed",
  "format": "mp4",
  "error": {
    "code": 400,
    "message": "Prompt contains inappropriate content"
  }
}
```

#### 사용 예제

```bash theme={null}
curl -X GET "https://api.gravitex.ai/v1/video/generations/video_69095b4ce0048190893a01510c0c98b0" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"
```

### 비디오 다운로드

**GET** `/v1/video/generations/download?id={videoId}`

완료된 비디오 파일 다운로드 (Sora 2 전용).

#### 쿼리 매개변수

<ParamField query="id" type="string" required>
  조회 작업 인터페이스에서 반환된 비디오 ID (task\_id)
</ParamField>

#### 응답 예제

```json theme={null}
{
  "success": true,
  "generation_id": "video_69095b4ce0048190893a01510c0c98b0",
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "format": "mp4",
  "size": 15728640,
  "base64": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB...",
  "data_url": "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB..."
}
```

**응답 필드 설명**:

| 필드              | 타입      | 설명                                                 |
| --------------- | ------- | -------------------------------------------------- |
| `success`       | boolean | 성공 여부                                              |
| `generation_id` | string  | 생성 ID (videoId와 동일)                                |
| `task_id`       | string  | 작업 ID                                              |
| `format`        | string  | 비디오 형식 (`"mp4"` 고정)                                |
| `size`          | number  | 비디오 파일 크기(바이트)                                     |
| `base64`        | string  | Base64로 인코딩된 비디오 데이터                               |
| `data_url`      | string  | Data URL 형식 비디오 데이터, 프론트엔드 `<video>` 태그에서 바로 사용 가능 |

#### 사용 예제

```bash theme={null}
curl -X GET "https://api.gravitex.ai/v1/video/generations/download?id=video_69095b4ce0048190893a01510c0c98b0" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"
```

## 비디오 작업 제출

**POST** `/v1/video/generations`

비디오 생성 작업을 제출하고 후속 조회용 작업 ID를 반환합니다.

#### 사용 예제s

<Tabs>
  <Tab title="Sora 2">
    **1. 텍스트-투-비디오(기본 예제)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "sora-2",
        "prompt": "A cute little cat playing in the garden, sunny and warm",
        "seconds": "4",
        "size": "720x1280"
      }'
    ```

    **2. 텍스트-투-비디오(가로, 8초)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "sora-2",
        "prompt": "A cute little cat playing in the garden, sunny and warm",
        "seconds": "8",
        "size": "1280x720"
      }'
    ```

    **3. 이미지-투-비디오(첫 프레임 모드)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "sora-2",
        "prompt": "A cute little cat playing in the garden, sunny and warm",
        "seconds": "4",
        "size": "720x1280",
        "input_reference": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
      }'
    ```

    **4. Remix 모드(비디오-투-비디오)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "sora-2",
        "prompt": "Change the video to a night scene with stars",
        "seconds": "4",
        "size": "720x1280",
        "remix_from_video_id": "video_69095b4ce0048190893a01510c0c98b0"
      }'
    ```
  </Tab>

  <Tab title="Veo">
    **1. 텍스트-투-비디오(기본 예제)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "veo-3.1-fast-generate-preview",
        "prompt": "Aerial view of a sci-fi city at dawn, sunlight piercing through clouds",
        "durationSeconds": 8,
        "aspectRatio": "16:9",
        "resolution": "1080p",
        "fps": 24,
        "generateAudio": true,
        "personGeneration": "allow_all",
        "addWatermark": false
      }'
    ```

    **2. 텍스트-투-비디오(세로, 랜덤 시드)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "veo-3.1-fast-generate-preview",
        "prompt": "Aerial view of a sci-fi city at dawn, sunlight piercing through clouds",
        "durationSeconds": 6,
        "aspectRatio": "9:16",
        "resolution": "720p",
        "fps": 30,
        "generateAudio": false,
        "personGeneration": "allow_adult",
        "addWatermark": true,
        "seed": 12345,
        "sampleCount": 2
      }'
    ```

    **3. 이미지-투-비디오(첫 프레임 모드)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "veo-3.1-fast-generate-preview",
        "prompt": "Generate video based on this image, scene gradually unfolds",
        "durationSeconds": 8,
        "aspectRatio": "16:9",
        "resolution": "1080p",
        "fps": 24,
        "image": "data:image/png;base64,iVBORw0KGgoAAxxxx...",
        "generateAudio": true,
        "personGeneration": "dont_allow",
        "addWatermark": false
      }'
    ```

    **4. 이미지-투-비디오(첫/마지막 프레임 모드, veo-3.1만 지원)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "veo-3.1-fast-generate-preview",
        "prompt": "Transition from first image to second image",
        "durationSeconds": 8,
        "aspectRatio": "16:9",
        "resolution": "1080p",
        "fps": 24,
        "image": "data:image/png;base64,iVBORw0KGgoAAxxxx...",
        "lastFrame": "data:image/png;base64,iVBORw0KGgoAAyyyy...",
        "generateAudio": true,
        "seed": 67890,
        "sampleCount": 1
      }'
    ```
  </Tab>

  <Tab title="Ali Wanxiang">
    **1. 텍스트-투-비디오(기본 예제)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "wan2.5-t2v-preview",
        "prompt": "A kitten slowly opens its eyes, ears gently twitch, camera slowly pushes in",
        "duration": 5,
        "size": "1280*720",
        "smart_rewrite": true,
        "generate_audio": true
      }'
    ```

    **2. 텍스트-투-비디오(10초, 1080p, 랜덤 시드)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "wan2.5-t2v-preview",
        "prompt": "A kitten slowly opens its eyes, ears gently twitch, camera slowly pushes in",
        "duration": 10,
        "size": "1920*1080",
        "smart_rewrite": false,
        "generate_audio": false,
        "seed": 123456
      }'
    ```

    **3. 이미지-투-비디오(첫 프레임 모드)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "wan2.5-i2v-preview",
        "prompt": "Kitten slowly opens its eyes, ears gently twitch, camera slowly pushes in",
        "duration": 5,
        "resolution": "720p",
        "smart_rewrite": true,
        "generate_audio": true,
        "image": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
      }'
    ```

    **4. 이미지-투-비디오(커스텀 오디오)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "wan2.5-i2v-preview",
        "prompt": "Kitten slowly opens its eyes, ears gently twitch, camera slowly pushes in",
        "duration": 10,
        "resolution": "1080p",
        "smart_rewrite": false,
        "generate_audio": false,
        "audio_url": "https://example.com/audio.mp3",
        "image": "data:image/png;base64,iVBORw0KGgoAAxxxx...",
        "seed": 789012
      }'
    ```
  </Tab>

  <Tab title="Doubao Seedance">
    **1. 텍스트-투-비디오(T2V, 기본 예제)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-1-0-lite-t2v-250428",
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "A cute kitten playing in a garden, sunny day --ratio 16:9 --dur 5 --rs 720p --wm false"
            }
          ]
        }
      }'
    ```

    **2. 텍스트-투-비디오(T2V, 전체 매개변수)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-1-0-lite-t2v-250428",
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "A cute kitten playing in a garden, sunny day --ratio 9:16 --dur 10 --rs 1080p --fps 30 --wm true --seed 12345"
            }
          ]
        }
      }'
    ```

    **3. 이미지-투-비디오(첫 프레임 모드)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-1-0-lite-i2v-250428",
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "A girl opens her eyes and looks gently at the camera --ratio adaptive --dur 5 --rs 720p --wm false"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
              }
            }
          ]
        }
      }'
    ```

    **4. 이미지-투-비디오(첫/마지막 프레임 모드, lite-i2v만 지원)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-1-0-lite-i2v-250428",
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "A blue-green jingwei bird transforms into human form --rs 720p --dur 5 --fps 24 --cf false --wm false --seed 67890"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
              },
              "role": "first_frame"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "data:image/png;base64,iVBORw0KGgoAAyyyy..."
              },
              "role": "last_frame"
            }
          ]
        }
      }'
    ```

    **5. 이미지-투-비디오(참조 이미지 모드, lite-i2v만 지원)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-1-0-lite-i2v-250428",
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "[图1] A boy wearing glasses and blue T-shirt and [图2] corgi dog, sitting on [图3] lawn, 3D cartoon style --rs 720p --dur 5 --ratio 16:9 --wm false"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "https://example.com/ref1.png"
              },
              "role": "reference_image"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "https://example.com/ref2.png"
              },
              "role": "reference_image"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "https://example.com/ref3.png"
              },
              "role": "reference_image"
            }
          ]
        }
      }'
    ```

    **6. Pro 모델(첫 프레임 모드)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-1-0-pro-250528",
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "A girl opens her eyes and looks gently at the camera --ratio 16:9 --dur 5 --rs 1080p --wm false"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
              }
            }
          ]
        }
      }'
    ```

    **7. 1.5 Pro 모델(텍스트-투-비디오, 오디오 포함)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-1-5-pro-251215",
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "A cute kitten playing in a sunny garden, gentle breeze --ratio 16:9 --dur 6 --rs 720p --wm false"
            }
          ],
          "return_last_frame": true,
          "callback_url": "https://your-domain.com/callback"
        }
      }'
    ```

    **8. 1.5 Pro 모델(이미지-투-비디오 첫/마지막 프레임, 무음)**

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-1-5-pro-251215-noAudio",
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "Transition from static scene to dynamic motion --ratio 9:16 --dur 8 --rs 480p --wm false --seed 12345"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
              },
              "role": "first_frame"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "data:image/png;base64,iVBORw0KGgoAAyyyy..."
              },
              "role": "last_frame"
            }
          ],
          "return_last_frame": true
        }
      }'
    ```
  </Tab>
</Tabs>

#### 응답 예제

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "submitted",
  "format": "mp4"
}
```

## 요청 매개변수

<ParamField body="model" type="string" required>
  모델 식별자, 지원 모델 및 기능:

  **Sora 2 시리즈**:

  * `sora-2` - 텍스트-투-비디오, 이미지-투-비디오, 비디오-투-비디오(Remix 모드) 지원

  **Google Veo 시리즈**:

  * `veo-3.0-fast-generate-001` - 텍스트-투-비디오 (첫 프레임 모드)
  * `veo-3.1-fast-generate-preview` - 텍스트-투-비디오 (첫 프레임 모드, 첫/마지막 프레임 모드)

  **Ali Wanxiang 시리즈**:

  * `wan2.5-t2v-preview` - 텍스트-투-비디오
  * `wan2.5-i2v-preview` - 이미지-투-비디오 (첫 프레임 모드)

  **Doubao Seedance 시리즈**:

  * `doubao-seedance-1-0-lite-t2v-250428` - 텍스트-투-비디오
  * `doubao-seedance-1-0-lite-i2v-250428` - 이미지-투-비디오 (첫 프레임 모드, 첫/마지막 프레임 모드, 참조 이미지 모드)
  * `doubao-seedance-1-0-pro-250528` - 텍스트-투-비디오 (첫 프레임 모드)
  * `doubao-seedance-1-5-pro-251215` - 텍스트-투-비디오, 이미지-투-비디오 (첫 프레임 모드, 첫/마지막 프레임 모드), 오디오 포함, 길이 4-12초, 해상도 480p/720p
  * `doubao-seedance-1-5-pro-251215-noAudio` - 텍스트-투-비디오, 이미지-투-비디오 (첫 프레임 모드, 첫/마지막 프레임 모드), 무음 비디오, 길이 4-12초, 해상도 480p/720p
</ParamField>

<ParamField body="prompt" type="string">
  장면 동작과 설정을 설명하는 비디오 생성 프롬프트. **참고**: Doubao Seedance 시리즈 모델은 이 필드가 필요하지 않으며, 프롬프트는 `metadata.content` 배열의 `text` 필드에 직접 작성해야 합니다
</ParamField>

<ParamField body="image" type="string">
  이미지-투-비디오용 참조 이미지(Base64 또는 URL 형식 지원)
</ParamField>

<ParamField body="duration" type="integer" default="5">
  비디오 길이(초), 모델마다 지원 길이가 다름
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  비디오 해상도: `480p`, `720p`, `1080p`, `4k`
</ParamField>

<ParamField body="aspect_ratio" type="string" default="16:9">
  화면 비율: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `adaptive`(적응형, 일부 모델만 지원)
</ParamField>

## 모델별 매개변수

모델마다 지원하는 전용 매개변수가 다릅니다. 모델 시리즈별 상세 설명:

<Tabs>
  <Tab title="Sora 2">
    <ParamField body="seconds" type="string|integer" default="4">
      비디오 길이(초), 지원: `4`, `8`, `12`
    </ParamField>

    <ParamField body="size" type="string" default="720x1280">
      비디오 해상도, 지원: `720x1280`(세로), `1280x720`(가로)
    </ParamField>

    <ParamField body="input_reference" type="string">
      참조 이미지(URL 또는 Base64 형식 지원), 이미지-투-비디오용
    </ParamField>

    <ParamField body="remix_from_video_id" type="string">
      Remix 모드: 기존 비디오 ID 기반 재생성(`video_`로 시작해야 함)
    </ParamField>
  </Tab>

  <Tab title="Veo">
    <ParamField body="durationSeconds" type="integer" default="4">
      비디오 길이(초), 지원: `4`, `6`, `8`
    </ParamField>

    <ParamField body="aspectRatio" type="string" default="16:9">
      화면 비율, `16:9`, `9:16`만 지원
    </ParamField>

    <ParamField body="resolution" type="string" default="1080p">
      해상도, 지원: `720p`, `1080p`
    </ParamField>

    <ParamField body="fps" type="integer" default="24">
      프레임 레이트, 기본값 24
    </ParamField>

    <ParamField body="image" type="string">
      첫 프레임 참조 이미지(URL 또는 Base64 형식 지원)
    </ParamField>

    <ParamField body="lastFrame" type="string">
      마지막 프레임 참조 이미지(URL 또는 Base64 형식 지원), `veo-3.1` 시리즈만 지원
    </ParamField>

    <ParamField body="generateAudio" type="boolean" default="false">
      동기화된 오디오 생성 여부. Fast 모델은 이 매개변수를 무시하고 항상 오디오 포함
    </ParamField>

    <ParamField body="personGeneration" type="string" default="allow_all">
      인물 생성 전략: `allow_all`(전 연령), `allow_adult`(성인만), `dont_allow`(인물 없음)
    </ParamField>

    <ParamField body="addWatermark" type="boolean" default="false">
      워터마크 추가 여부
    </ParamField>

    <ParamField body="seed" type="integer">
      결과 재현용 랜덤 시드
    </ParamField>

    <ParamField body="sampleCount" type="integer" default="1">
      요청당 생성할 비디오 수, 범위: `1-4`
    </ParamField>
  </Tab>

  <Tab title="Ali Wanxiang">
    <ParamField body="duration" type="integer" default="5">
      비디오 길이(초), 지원: `5`, `10`
    </ParamField>

    <ParamField body="resolution" type="string" default="720p">
      비디오 해상도, 지원: `480p`, `720p`, `1080p`
    </ParamField>

    <ParamField body="size" type="string">
      비디오 크기(t2v 모드 전용), 형식: `width*height`, 예: `1280*720`
    </ParamField>

    <ParamField body="smart_rewrite" type="boolean" default="false">
      지능형 프롬프트 확장 활성화 여부
    </ParamField>

    <ParamField body="generate_audio" type="boolean" default="false">
      비디오와 동기화된 오디오 생성 여부
    </ParamField>

    <ParamField body="audio_url" type="string">
      커스텀 오디오 파일 URL(HTTPS 형식)
    </ParamField>

    <ParamField body="seed" type="integer">
      랜덤 시드, 범위: `0-2147483647`
    </ParamField>
  </Tab>

  <Tab title="Doubao Seedance">
    <ParamField body="metadata.content" type="array" required>
      콘텐츠 배열, `metadata` 객체 안에 배치해야 합니다. 텍스트와 선택적 이미지를 포함해야 합니다. 매개변수는 텍스트 프롬프트의 특수 마커로 제어됩니다:

      * `--rs` 또는 `--resolution`: 해상도 (`480p`, `720p`, `1080p`)
      * `--ratio`: 화면 비율 (`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `adaptive`, `doubao-seedance-1-0-lite-t2v-250428`은 `adaptive` 미지원)
      * `--dur` 또는 `--duration`: 길이(초, 예: `5`, `10`)
      * `--fps` 또는 `--framespersecond`: 프레임 레이트(예: `24`, `30`)
      * `--seed`: 랜덤 시드
      * `--wm` 또는 `--watermark`: 워터마크 토글(`true`, `false`)
      * `--cf` 또는 `--camerafixed`: 고정 카메라(`true`, `false`, lite 모델만 지원)

      **1.5 Pro 시리즈 제한**:

      * 길이: 4-12초
      * 해상도: 480p, 720p만
      * 생성 모드: 텍스트-투-비디오, 첫 프레임 모드, 첫/마지막 프레임 모드

      **metadata.content 배열 형식**:

      ```json theme={null}
      {
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "Prompt content --ratio 16:9 --dur 5 --rs 720p --wm false"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "data:image/png;base64,..."
              },
              "role": "first_frame"  // Optional: first_frame, last_frame, reference_image
            }
          ],
          "return_last_frame": true,  // Whether to return last frame (1.5 Pro series)
          "callback_url": "https://your-domain.com/callback"  // Optional callback URL
        }
      }
      ```
    </ParamField>
  </Tab>
</Tabs>

## 전체 예제

### Doubao Seedance 시리즈

Doubao Seedance 시리즈 모델은 특수 매개변수 전달 방식을 사용합니다: **모든 매개변수는 프롬프트의 특수 마커로 전달**되며, 이미지는 `metadata.content` 배열을 통해 전달됩니다.

#### 1. 텍스트-투-비디오 (T2V)

```bash theme={null}
curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-t2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A cute kitten playing in a garden, sunny day --ratio 16:9 --dur 5 --rs 720p --wm false"
        }
      ]
    }
  }'
```

#### 2. 이미지-투-비디오 - 첫 프레임 모드

```bash theme={null}
curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A girl opens her eyes and looks gently at the camera --ratio adaptive --dur 5 --rs 720p --wm false"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
          }
        }
      ]
    }
  }'
```

#### 3. 이미지-투-비디오 - 첫/마지막 프레임 모드 (lite-i2v만 지원)

```bash theme={null}
curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A blue-green jingwei bird transforms into human form --rs 720p --dur 5 --cf false"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
          },
          "role": "first_frame"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAyyyy..."
          },
          "role": "last_frame"
        }
      ]
    }
  }'
```

#### 4. 이미지-투-비디오 - 참조 이미지 모드 (lite-i2v만 지원)

```bash theme={null}
curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "[图1] A boy wearing glasses and blue T-shirt and [图2] corgi dog, sitting on [图3] lawn, 3D cartoon style --rs 720p --dur 5"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/ref1.png"
          },
          "role": "reference_image"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/ref2.png"
          },
          "role": "reference_image"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/ref3.png"
          },
          "role": "reference_image"
        }
      ]
    }
  }'
```

**중요 참고**:

* `content` 배열은 `metadata` 객체 안에 배치해야 합니다
* 모든 매개변수는 프롬프트의 특수 마커로 전달해야 합니다(예: `--ratio 16:9`)
* 이미지는 `image_url` 유형으로 `metadata.content` 배열에 배치해야 합니다
* 첫/마지막 프레임 모드는 두 이미지가 필요하며, 각각 `role: "first_frame"` 및 `role: "last_frame"`로 표시
* 참조 이미지 모드는 프롬프트에서 `[图1]`, `[图2]` 등으로 이미지를 참조하고, 이미지는 `role: "reference_image"`로 표시
* `doubao-seedance-1-0-lite-t2v-250428`은 이미지 입력 및 `adaptive` 화면 비율 미지원
* `doubao-seedance-1-0-pro-250528`은 첫 프레임 모드만 지원

<Tabs>
  <Tab title="Sora 2 전체 예제">
    ### 1. 비디오 생성 작업 제출

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "sora-2",
        "prompt": "A cute kitten playing in a garden, sunny day, warm scene",
        "seconds": "4",
        "size": "720x1280"
      }'
    ```

    **응답 예제**:

    ```json theme={null}
    {
      "task_id": "video_69095b4ce0048190893a01510c0c98b0",
      "status": "submitted",
      "format": "mp4"
    }
    ```

    ### 2. 작업 상태 폴링

    ```bash theme={null}
    curl -X GET "https://api.gravitex.ai/v1/video/generations/video_69095b4ce0048190893a01510c0c98b0" \
      -H "Authorization: Bearer sk-xxxxxxxxxx"
    ```

    **작업 상태 설명**:

    | 상태            | 설명                  | 권장 조치    |
    | ------------- | ------------------- | -------- |
    | `queued`      | 작업 대기열에 있음, 처리 대기 중 | 계속 폴링    |
    | `in_progress` | 작업 처리 중             | 계속 폴링    |
    | `succeeded`   | 작업 성공 완료            | 비디오 다운로드 |
    | `failed`      | 작업 실패               | 실패 원인 확인 |

    **응답 예제 (대기 중)**:

    ```json theme={null}
    {
      "task_id": "video_69095b4ce0048190893a01510c0c98b0",
      "status": "queued",
      "format": "mp4"
    }
    ```

    **응답 예제 (처리 중)**:

    ```json theme={null}
    {
      "task_id": "video_69095b4ce0048190893a01510c0c98b0",
      "status": "in_progress",
      "format": "mp4"
    }
    ```

    **응답 예제 (완료)**:

    ```json theme={null}
    {
      "task_id": "video_69095b4ce0048190893a01510c0c98b0",
      "status": "succeeded",
      "format": "mp4"
    }
    ```

    **응답 예제 (실패)**:

    ```json theme={null}
    {
      "task_id": "video_69095b4ce0048190893a01510c0c98b0",
      "status": "failed",
      "format": "mp4",
      "error": {
        "code": 400,
        "message": "Prompt contains inappropriate content"
      }
    }
    ```

    **중요 안내**:

    * 작업 상태가 `queued` 또는 `in_progress`일 때는 정기적으로 폴링해야 합니다(3\~5초 간격 권장)
    * 상태가 `succeeded`가 되면 `task_id`를 `videoId`로 사용하여 비디오를 다운로드할 수 있습니다
    * 상태가 `failed`가 되면 `error` 필드에서 실패 원인을 확인할 수 있습니다

    ### 3. 비디오 다운로드 (Sora 2 전용)

    폴링 성공 후 반환된 `task_id`(`videoId`로 사용)로 비디오를 다운로드합니다:

    ```bash theme={null}
    curl -X GET "https://api.gravitex.ai/v1/video/generations/download?id=video_69095b4ce0048190893a01510c0c98b0" \
      -H "Authorization: Bearer sk-xxxxxxxxxx"
    ```

    **참고**: `id` 매개변수 값은 2단계에서 폴링 성공 후 반환된 `task_id`입니다.

    **응답 예제**:

    ```json theme={null}
    {
      "success": true,
      "generation_id": "video_69095b4ce0048190893a01510c0c98b0",
      "task_id": "video_69095b4ce0048190893a01510c0c98b0",
      "format": "mp4",
      "size": 15728640,
      "base64": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB...",
      "data_url": "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB..."
    }
    ```

    **응답 필드 설명**:

    | 필드명             | 타입      | 설명                                                 |
    | --------------- | ------- | -------------------------------------------------- |
    | `success`       | boolean | 성공 여부                                              |
    | `generation_id` | string  | 생성 ID (videoId와 동일)                                |
    | `task_id`       | string  | 작업 ID                                              |
    | `format`        | string  | 비디오 형식 (`"mp4"` 고정)                                |
    | `size`          | number  | 비디오 파일 크기(바이트)                                     |
    | `base64`        | string  | Base64로 인코딩된 비디오 데이터                               |
    | `data_url`      | string  | Data URL 형식 비디오 데이터, 프론트엔드 `<video>` 태그에서 바로 사용 가능 |
  </Tab>

  <Tab title="Veo 전체 예제">
    ### 1. 비디오 생성 작업 제출

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "veo-3.1-generate-preview",
        "prompt": "Aerial view of a sci-fi city at dawn, sunlight piercing through clouds",
        "durationSeconds": 8,
        "aspectRatio": "16:9",
        "resolution": "1080p",
        "generateAudio": true,
        "image": "https://example.com/start-frame.png",
        "lastFrame": "https://example.com/end-frame.png"
      }'
    ```

    **응답 예제**:

    ```json theme={null}
    {
      "task_id": "video_1234567890abcdef",
      "status": "submitted",
      "format": "mp4"
    }
    ```

    ### 2. 작업 상태 폴링

    ```bash theme={null}
    curl -X GET "https://api.gravitex.ai/v1/video/generations/video_1234567890abcdef" \
      -H "Authorization: Bearer sk-xxxxxxxxxx"
    ```

    **응답 예제 (완료)**:

    ```json theme={null}
    {
      "task_id": "video_1234567890abcdef",
      "status": "succeeded",
      "format": "mp4",
      "url": "https://gravitex-ads.oss-cn-guangzhou.aliyuncs.com/2025/11/18/abc123/veo-demo-1.mp4"
    }
    ```

    **참고**: Veo와 Ali Wanxiang의 경우 작업이 성공하면 응답에 비디오 URL이 직접 포함되므로 추가 다운로드 단계가 필요하지 않습니다.
  </Tab>

  <Tab title="Ali Wanxiang 전체 예제">
    ### 1. 비디오 생성 작업 제출

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "wan2.5-i2v-preview",
        "prompt": "A kitten slowly opens its eyes, ears gently twitch, camera slowly pushes in",
        "image": "https://example.com/cat.jpg",
        "duration": 5,
        "resolution": "720p",
        "smart_rewrite": true,
        "generate_audio": true
      }'
    ```

    **응답 예제**:

    ```json theme={null}
    {
      "task_id": "ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97",
      "status": "submitted",
      "format": "mp4"
    }
    ```

    ### 2. 작업 상태 폴링

    ```bash theme={null}
    curl -X GET "https://api.gravitex.ai/v1/video/generations/ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97" \
      -H "Authorization: Bearer sk-xxxxxxxxxx"
    ```

    **응답 예제 (완료)**:

    ```json theme={null}
    {
      "task_id": "ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97",
      "status": "succeeded",
      "format": "mp4",
      "url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/.../video.mp4?Expires=..."
    }
    ```
  </Tab>

  <Tab title="Doubao Seedance 전체 예제">
    ### 1. 텍스트-투-비디오 (T2V)

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-1-0-pro-250528",
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "Multiple shots. A detective enters a dimly lit room. He examines clues on the table, picks up an item. Camera turns to him thinking. --ratio 16:9 --dur 5"
            }
          ]
        }
      }'
    ```

    ### 2. 이미지-투-비디오 - 첫 프레임 모드 (I2V)

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-1-0-pro-250528",
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "A girl holding a fox, the girl opens her eyes, looks gently at the camera, the fox hugs friendly, camera slowly pulls out, the girl'\''s hair is blown by the wind --ratio adaptive --dur 5"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "https://example.com/first-frame.png"
              }
            }
          ]
        }
      }'
    ```

    ### 3. 이미지-투-비디오 - 첫/마지막 프레임 모드 (lite-i2v만 지원)

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-1-0-lite-i2v-250428",
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "A blue-green jingwei bird transforms into human form --rs 720p --dur 5 --cf false"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "https://example.com/first-frame.png"
              },
              "role": "first_frame"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "https://example.com/last-frame.png"
              },
              "role": "last_frame"
            }
          ]
        }
      }'
    ```

    ### 4. 이미지-투-비디오 - 참조 이미지 모드 (lite-i2v만 지원)

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/video/generations" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-1-0-lite-i2v-250428",
        "metadata": {
          "content": [
            {
              "type": "text",
              "text": "[图1] A boy wearing glasses and blue T-shirt and [图2] corgi dog, sitting on [图3] lawn, 3D cartoon style"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "https://example.com/ref1.png"
              },
              "role": "reference_image"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "https://example.com/ref2.png"
              },
              "role": "reference_image"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "https://example.com/ref3.png"
              },
              "role": "reference_image"
            }
          ]
        }
      }'
    ```

    **응답 예제**:

    ```json theme={null}
    {
      "task_id": "cgt-2025123456-abcd",
      "status": "submitted",
      "format": "mp4"
    }
    ```

    ### 5. 작업 상태 폴링

    ```bash theme={null}
    curl -X GET "https://api.gravitex.ai/v1/video/generations/cgt-2025123456-abcd" \
      -H "Authorization: Bearer sk-xxxxxxxxxx"
    ```

    **응답 예제 (완료)**:

    ```json theme={null}
    {
      "task_id": "cgt-2025123456-abcd",
      "status": "succeeded",
      "format": "mp4",
      "url": "https://ark-content-generation-cn-beijing.tos-cn-beijing.volces.com/.../video.mp4?X-Tos-Algorithm=..."
    }
    ```
  </Tab>
</Tabs>

## 지원 모델

### Sora 2 시리즈

**모델 이름**: `sora-2`

**핵심 기능**:

* ✅ 텍스트-투-비디오(순수 텍스트 설명으로 비디오 생성)
* ✅ 이미지-투-비디오(단일 이미지 + 텍스트로 비디오 생성)
* ✅ Remix 모드(기존 비디오 기반 재생성)

**지원 매개변수**:

* `seconds`: 비디오 길이(4, 8, 12초), 기본값 4초
* `size`: 비디오 해상도(`720x1280` 세로, `1280x720` 가로), 기본값 `720x1280`
* `width` / `height`: 비디오 너비와 높이(`size` 매개변수로 자동 변환)
* `input_reference`: 참조 이미지(URL 또는 Base64 형식 지원), 이미지-투-비디오용
* `remix_from_video_id`: Remix 모드, 기존 비디오 ID 기반 재생성(`video_`로 시작해야 함)

**참고**:

* 비디오 생성은 비동기 작업이며, 먼저 작업을 제출하여 `task_id`를 받은 후 작업 상태를 폴링해야 합니다
* 작업 상태가 `succeeded`이면 `task_id`를 `videoId`로 사용하여 다운로드 인터페이스를 호출해 비디오를 가져옵니다
* 다운로드 인터페이스는 Base64로 인코딩된 비디오 데이터를 반환하며, 프론트엔드 재생 또는 파일 저장에 바로 사용할 수 있습니다
* 이미지 입력 형식은 JPEG, PNG를 지원하며, 이미지-투-비디오 시 이미지 크기는 `size` 매개변수와 정확히 일치해야 합니다

### Veo 시리즈

**모델 이름**: `veo-3.1-generate-preview`, `veo-3.1-fast-generate-preview`, `veo-3.0-generate-preview`, `veo-3.0-fast-generate-001`

**핵심 기능**:

* ✅ 텍스트-투-비디오
* ✅ 이미지-투-비디오(첫 프레임 및 마지막 프레임 제약 지원)
* ✅ 오디오 생성

**지원 매개변수**:

* `durationSeconds`: 비디오 길이(4, 6, 8초)
* `aspectRatio`: 화면 비율(16:9, 9:16)
* `resolution`: 해상도(720p, 1080p)
* `generateAudio`: 오디오 생성 여부
* `image`: 첫 프레임 참조 이미지
* `lastFrame`: 마지막 프레임 참조 이미지
* `seed`: 랜덤 시드

### Ali Wanxiang 시리즈

**모델 이름**: `wan2.5-i2v-preview`

**핵심 기능**:

* ✅ 이미지-투-비디오
* ✅ 커스텀 오디오 업로드 지원
* ✅ 지능형 프롬프트 확장
* ✅ 비디오와 동기화된 오디오 자동 생성

**지원 매개변수**:

* `duration`: 비디오 길이(5, 10초)
* `resolution`: 비디오 해상도(480p, 720p, 1080p)
* `smart_rewrite`: 지능형 프롬프트 확장 활성화 여부
* `generate_audio`: 비디오와 동기화된 오디오 생성 여부
* `audio_url`: 커스텀 오디오 파일 URL
* `seed`: 랜덤 시드

### Doubao Seedance 시리즈

**모델 이름**:

* `doubao-seedance-1-0-pro-250528` - Pro 버전, 텍스트-투-비디오 및 이미지-투-비디오(첫 프레임 모드) 지원
* `doubao-seedance-1-0-lite-t2v-250428` - Lite 버전 텍스트-투-비디오
* `doubao-seedance-1-0-lite-i2v-250428` - Lite 버전 이미지-투-비디오, 첫 프레임, 첫/마지막 프레임, 참조 이미지 세 가지 모드 지원
* `doubao-seaweed-1-0-t2v-250428` - Seaweed 버전 텍스트-투-비디오
* `wan2-1-14b-i2v-250417` - Wanxiang 버전 이미지-투-비디오
* `wan2-1-14b-flf2v-250417` - Wanxiang 버전 첫/마지막 프레임 생성

**핵심 기능**:

* ✅ 텍스트-투-비디오 (T2V)
* ✅ 이미지-투-비디오 - First frame mode (I2V)
* ✅ 이미지-투-비디오 - 첫/마지막 프레임 모드 (`doubao-seedance-1-0-lite-i2v-250428` 및 `wan2-1-14b-flf2v-250417`만 지원)
* ✅ 이미지-투-비디오 - 참조 이미지 모드 (`doubao-seedance-1-0-lite-i2v-250428`만 지원)

**지원 매개변수**(텍스트 프롬프트의 특수 마커로 제어):

* `--rs` / `--resolution`: Resolution (`480p`, `720p`, `1080p`)
* `--ratio`: Aspect ratio (`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `adaptive`)
* `--dur` / `--duration`: 길이(초, 예: `5`, `10`)
* `--fps` / `--framespersecond`: Frame rate (e.g. `24`, `30`)
* `--seed`: Random seed
* `--wm` / `--watermark`: Watermark toggle (`true`, `false`)
* `--cf` / `--camerafixed`: 고정 카메라(`true`, `false`, lite 모델만 지원)

**이미지 입력 형식**:

* `metadata.content` 배열에서 이미지 항목은 `role` 필드로 표시할 수 있습니다:
  * `first_frame`: 첫 프레임 이미지
  * `last_frame`: 마지막 프레임 이미지
  * `reference_image`: 참조 이미지(프롬프트에서 `[图N]`으로 참조)

**참고**:

* `doubao-seedance-1-0-lite-t2v-250428`은 텍스트-투-비디오만 지원하며, 이미지 입력 미지원
* `doubao-seedance-1-0-lite-i2v-250428`의 참조 이미지 모드는 `1080p` 해상도 미지원
* `doubao-seedance-1-0-lite-t2v-250428`은 `adaptive` 화면 비율 미지원

## 모범 사례

### 폴링 전략

<Tabs>
  <Tab title="Python 폴링 예제">
    ```python theme={null}
    import requests
    import time

    def poll_task_status(task_id, api_key, max_wait_time=300):
        """Poll task status until completion"""
        url = f"https://api.gravitex.ai/v1/video/generations/{task_id}"
        headers = {"Authorization": f"Bearer {api_key}"}
        
        start_time = time.time()
        while True:
            response = requests.get(url, headers=headers)
            data = response.json()
            status = data.get("status")
            
            print(f"Current status: {status}")
            
            if status == "succeeded":
                video_url = data.get("url")
                print(f"✅ Task completed! Video URL: {video_url}")
                return video_url
            elif status == "failed":
                error_msg = data.get("metadata", {}).get("output", {}).get("message", "Unknown error")
                print(f"❌ Task failed: {error_msg}")
                return None
            
            # Check timeout
            if time.time() - start_time > max_wait_time:
                print("⏰ Wait timeout")
                return None
            
            # Wait 5 seconds before querying again
            time.sleep(5)
    ```
  </Tab>

  <Tab title="JavaScript 폴링 예제">
    ```javascript theme={null}
    async function pollTaskStatus(taskId, apiKey, maxWaitTime = 300000) {
      const url = `https://api.gravitex.ai/v1/video/generations/${taskId}`;
      const headers = { 'Authorization': `Bearer ${apiKey}` };
      
      const startTime = Date.now();
      
      while (true) {
        const response = await fetch(url, { headers });
        const data = await response.json();
        const status = data.status;
        
        console.log(`Current status: ${status}`);
        
        if (status === 'succeeded') {
          const videoUrl = data.url;
          console.log(`✅ Task completed! Video URL: ${videoUrl}`);
          return videoUrl;
        } else if (status === 'failed') {
          const errorMsg = data.metadata?.output?.message || 'Unknown error';
          console.error(`❌ Task failed: ${errorMsg}`);
          throw new Error(errorMsg);
        }
        
        // Check timeout
        if (Date.now() - startTime > maxWaitTime) {
          throw new Error('Wait timeout');
        }
        
        // Wait 5 seconds before querying again
        await new Promise(resolve => setTimeout(resolve, 5000));
      }
    }
    ```
  </Tab>
</Tabs>

## FAQ

<Tabs>
  <Tab title="일반 질문">
    <AccordionGroup>
      <Accordion title="비디오 생성에는 얼마나 걸리나요?">
        보통 1\~5분이 소요되며, 비디오 길이, 해상도, 서버 부하에 따라 달라집니다.
      </Accordion>

      <Accordion title="생성된 비디오는 얼마나 유효한가요?">
        비디오 URL은 약 24시간 유효합니다. 응답을 받은 후 즉시 다운로드하여 저장하는 것을 권장합니다.
      </Accordion>

      <Accordion title="어떤 이미지 입력 형식을 지원하나요?">
        PNG, JPEG, JPG, WEBP 형식을 지원하며, 최대 파일 크기는 10MB입니다.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Sora 2">
    <AccordionGroup>
      <Accordion title="Sora 2는 왜 추가 다운로드 단계가 필요한가요?">
        Sora 2 비디오 파일은 별도 스토리지 서비스에 저장됩니다. 작업 성공 후 서명된 임시 URL이 반환되며 추가 다운로드가 필요합니다.
      </Accordion>

      <Accordion title="어떤 비디오 길이를 지원하나요?">
        4초, 8초, 12초를 지원합니다.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Veo">
    <AccordionGroup>
      <Accordion title="어떤 비디오 길이를 지원하나요?">
        4초, 6초, 8초를 지원합니다.
      </Accordion>

      <Accordion title="오디오는 어떻게 생성하나요?">
        `generateAudio: true` 매개변수를 설정하면 시스템이 비디오와 동기화된 오디오를 자동 생성합니다.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Ali Wanxiang">
    <AccordionGroup>
      <Accordion title="어떤 비디오 길이를 지원하나요?">
        5초와 10초를 지원합니다.
      </Accordion>

      <Accordion title="커스텀 오디오는 어떻게 업로드하나요?">
        공개적으로 접근 가능한 오디오 파일 URL을 가리키는 `audio_url` 매개변수를 제공하세요.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Doubao Seedance">
    <AccordionGroup>
      <Accordion title="비디오 매개변수는 어떻게 설정하나요?">
        Doubao Seedance 모델 매개변수는 텍스트 프롬프트의 특수 마커로 제어됩니다. 예:
        `--rs 720p --ratio 16:9 --dur 5 --fps 24 --seed 12345`
      </Accordion>

      <Accordion title="어떤 이미지-투-비디오 모드를 지원하나요?">
        * **첫 프레임 모드**: 이미지-투-비디오를 지원하는 모든 모델에서 지원
        * **첫/마지막 프레임 모드**: `doubao-seedance-1-0-lite-i2v-250428` 및 `wan2-1-14b-flf2v-250417`만 지원
        * **참조 이미지 모드**: `doubao-seedance-1-0-lite-i2v-250428`만 지원, 프롬프트에서 `[图1]`, `[图2]` 등으로 여러 참조 이미지 참조 가능
      </Accordion>

      <Accordion title="콜백 알림은 어떻게 설정하나요?">
        `metadata`에 `callback_url` 필드를 설정하면 작업 상태 변경 시 결과가 해당 URL로 자동 푸시됩니다.
      </Accordion>

      <Accordion title="어떤 화면 비율을 지원하나요?">
        대부분의 모델은 `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `adaptive`(적응형)를 지원합니다. `doubao-seedance-1-0-lite-t2v-250428`은 `adaptive`를 지원하지 않습니다.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## 관련 리소스

<Columns cols={2}>
  <Card title="이미지 생성" icon="image" href="/ko/api-reference/endpoint/image-generation">
    이미지 생성 API 문서 보기
  </Card>

  <Card title="모델 목록" icon="list" href="/ko/api-reference/models">
    지원되는 모든 모델 정보 보기
  </Card>
</Columns>