> ## 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.

# Wan 2.7 비디오 생성

> Alibaba Wan 2.7 텍스트-투-비디오, 이미지-투-비디오, 참조-투-비디오

## 소개

Wan 2.7은 Alibaba Cloud Bailian의 비디오 생성 제품군입니다: 텍스트-투-비디오(Wan2.7-t2v), 이미지-투-비디오(Wan2.7-i2v), 참조-투-비디오(Wan2.7-r2v), 비디오 편집(Wan2.7-videoedit). **720P** 및 **1080P** 출력을 지원합니다.

GravitexAI 통합 비디오 API를 사용하세요: [작업 제출](/ko/api-reference/endpoint/submit-video-task)로 `task_id`를 받은 후 [작업 조회](/ko/api-reference/endpoint/query-video-task)로 상태를 폴링하고 `url`을 확인합니다.

<Note>
  Wan 2.7과 Wan 2.5 모두 `metadata.input` 및 `metadata.parameters`를 사용합니다. Wan 2.7은 `media` 배열을 통해 더 많은 모드를 지원합니다. [Wan 2.5](/ko/api-reference/endpoint/wan2.5)를 참조하세요.
</Note>

## 인증

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

## 지원 모델

| 모델 ID                   | 설명        | 해상도         | 최대 길이                     | 주요 기능                   |
| ----------------------- | --------- | ----------- | ------------------------- | ----------------------- |
| `wan2.7-t2v-2026-04-25` | 텍스트-투-비디오 | 720P, 1080P | 15초                       | 멀티샷 내러티브, 커스텀 오디오       |
| `wan2.7-i2v-2026-04-25` | 이미지-투-비디오 | 720P, 1080P | 15초                       | 첫 프레임, 첫+마지막 프레임, 연속 생성 |
| `wan2.7-r2v`            | 참조-투-비디오  | 720P, 1080P | 10초(비디오 참조 시) / 15초(없을 때) | 멀티모달 참조, 보이스 클론, 다중 캐릭터 |

## 호출 흐름

1. **제출**: `model`, `prompt`, `duration` 및 `metadata`의 Wan 매개변수와 함께 `POST /v1/video/generations`.
2. **폴링**: `succeeded` 또는 `failed`가 될 때까지 3\~15초마다 `GET /v1/video/generations/{task_id}`.
3. **결과**: 성공 시 `url`에 비디오 포함(보통 24시간 유효—즉시 다운로드 권장).

## 요청 구조

| 필드                    | 타입      | 필수  | 설명                                                                      |
| --------------------- | ------- | --- | ----------------------------------------------------------------------- |
| `model`               | string  | 예   | 모델 ID(위 표 참조)                                                           |
| `prompt`              | string  | 예   | 비디오 프롬프트(`metadata.input.prompt`와 동일)                                   |
| `duration`            | integer | 아니오 | 길이(초); `metadata.parameters.duration`과 동기화 유지                           |
| `metadata.input`      | object  | 예   | `prompt`, `media`, `audio_url`, `negative_prompt` 등                     |
| `metadata.parameters` | object  | 아니오 | `resolution`, `ratio`, `duration`, `prompt_extend`, `watermark`, `seed` |

### 제출 응답

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

### 조회 응답(성공)

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

## 사용 시나리오

<Tabs>
  <Tab title="텍스트-투-비디오 (T2V)">
    멀티샷 프롬프트, 프롬프트 재작성, 선택적 커스텀 오디오로 텍스트에서 비디오를 생성합니다.

    <ParamField body="metadata.input.prompt" type="string" required>
      텍스트 프롬프트. 샷 타임스탬프 사용, 예: "Shot 1 \[0-3s] … Shot 2 \[3-6s] …"
    </ParamField>

    <ParamField body="metadata.input.negative_prompt" type="string">
      네거티브 프롬프트, 최대 500자
    </ParamField>

    <ParamField body="metadata.input.audio_url" type="string">
      커스텀 오디오 URL(wav/mp3), 2\~30초, 최대 15MB
    </ParamField>

    <ParamField body="metadata.parameters.resolution" type="string" default="720P">
      `720P` 또는 `1080P`
    </ParamField>

    <ParamField body="metadata.parameters.ratio" type="string" default="16:9">
      화면 비율: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
    </ParamField>

    <ParamField body="metadata.parameters.duration" type="integer" default="5">
      길이(초), 2\~15
    </ParamField>

    <ParamField body="metadata.parameters.prompt_extend" type="boolean" default="true">
      프롬프트 재작성 활성화
    </ParamField>

    <ParamField body="metadata.parameters.watermark" type="boolean" default="false">
      워터마크 추가
    </ParamField>

    **멀티샷 예제:**

    ```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.7-t2v-2026-04-25",
        "prompt": "Shot 1 [0-3s] Wide: rainy NYC street at night. Shot 2 [3-6s] Medium: detective enters an old building.",
        "duration": 6,
        "metadata": {
          "input": {
            "prompt": "Shot 1 [0-3s] Wide: rainy NYC street at night. Shot 2 [3-6s] Medium: detective enters an old building."
          },
          "parameters": {
            "resolution": "720P",
            "ratio": "16:9",
            "duration": 6,
            "prompt_extend": true,
            "watermark": false
          }
        }
      }'
    ```
  </Tab>

  <Tab title="이미지-투-비디오 (I2V)">
    `metadata.input.media`를 통해 첫 프레임, 첫+마지막 프레임, 비디오 연속 생성을 지원합니다.

    #### media 유형

    | type            | 설명          | 제한                    |
    | --------------- | ----------- | --------------------- |
    | `first_frame`   | 첫 프레임 이미지   | 1                     |
    | `last_frame`    | 마지막 프레임 이미지 | 1 (`first_frame`과 함께) |
    | `driving_audio` | 드라이빙 오디오    | 1 (선택, 첫 프레임 모드)      |
    | `first_clip`    | 첫 비디오 클립    | 1 (연속 생성)             |

    <ParamField body="metadata.input.media" type="array" required>
      미디어 목록; 각 항목에 `type`과 `url` 포함
    </ParamField>

    <ParamField body="metadata.parameters.resolution" type="string" default="720P">
      `720P` 또는 `1080P`
    </ParamField>

    <ParamField body="metadata.parameters.duration" type="integer" default="5">
      길이(초), 2\~15
    </ParamField>

    **첫 프레임 + 드라이빙 오디오:**

    ```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.7-i2v-2026-04-25",
        "prompt": "A graffiti boy comes alive from the wall and performs rap.",
        "duration": 10,
        "metadata": {
          "input": {
            "prompt": "A graffiti boy comes alive from the wall and performs rap.",
            "media": [
              {"type": "first_frame", "url": "https://example.com/first_frame.png"},
              {"type": "driving_audio", "url": "https://example.com/rap.mp3"}
            ]
          },
          "parameters": {
            "resolution": "720P",
            "duration": 10,
            "prompt_extend": true
          }
        }
      }'
    ```

    **첫 + 마지막 프레임:**

    ```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.7-i2v-2026-04-25",
        "prompt": "Timelapse from sunrise to sunset",
        "duration": 10,
        "metadata": {
          "input": {
            "prompt": "Timelapse from sunrise to sunset",
            "media": [
              {"type": "first_frame", "url": "https://example.com/sunrise.png"},
              {"type": "last_frame", "url": "https://example.com/sunset.png"}
            ]
          },
          "parameters": {
            "duration": 10
          }
        }
      }'
    ```

    **비디오 연속 생성:**

    ```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.7-i2v-2026-04-25",
        "prompt": "A girl takes a mirror selfie, then leaves with her backpack",
        "duration": 15,
        "metadata": {
          "input": {
            "prompt": "A girl takes a mirror selfie, then leaves with her backpack",
            "media": [
              {"type": "first_clip", "url": "https://example.com/girl_selfie.mp4"}
            ]
          },
          "parameters": {
            "duration": 15
          }
        }
      }'
    ```
  </Tab>

  <Tab title="참조-투-비디오 (R2V)">
    `prompt`에서 **图1/图2** 또는 **视频1/视频2**로 `media` 항목을 참조합니다(이미지와 비디오는 별도로 번호 매김).

    #### media 유형

    | type              | 설명        | 제한                    |
    | ----------------- | --------- | --------------------- |
    | `reference_image` | 참조 이미지    | 최대 5개(이미지+비디오 합계 ≤ 5) |
    | `reference_video` | 참조 비디오    | 최대 5개                 |
    | `first_frame`     | 첫 프레임 이미지 | 최대 1개(선택, 화면 비율 제어)   |

    <ParamField body="metadata.input.prompt" type="string" required>
      图n / 视频n으로 미디어를 참조하는 프롬프트
    </ParamField>

    <ParamField body="metadata.input.media[].reference_voice" type="string">
      보이스 참조 오디오 URL(`reference_image` / `reference_video`용)
    </ParamField>

    <ParamField body="metadata.parameters.ratio" type="string" default="16:9">
      화면 비율; `first_frame` 제공 시 무시됨
    </ParamField>

    <ParamField body="metadata.parameters.duration" type="integer" default="5">
      비디오 참조 시 2~~10초; 없으면 2~~15초
    </ParamField>

    **다중 주체 예제:**

    ```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.7-r2v",
        "prompt": "视频1抱着图3，在图4的椅子上弹奏民谣，并说道：\"今天的阳光真好。\"图1路过，把图2放到视频1旁边的桌子上。",
        "duration": 10,
        "metadata": {
          "input": {
            "prompt": "视频1抱着图3，在图4的椅子上弹奏民谣，并说道：\"今天的阳光真好。\"图1路过，把图2放到视频1旁边的桌子上。",
            "media": [
              {"type": "reference_image", "url": "https://example.com/girl.jpg", "reference_voice": "https://example.com/girl_voice.mp3"},
              {"type": "reference_video", "url": "https://example.com/boy_video.mp4", "reference_voice": "https://example.com/boy_voice.mp3"},
              {"type": "reference_image", "url": "https://example.com/object3.png"},
              {"type": "reference_image", "url": "https://example.com/object4.png"},
              {"type": "reference_image", "url": "https://example.com/background5.png"}
            ]
          },
          "parameters": {
            "resolution": "720P",
            "ratio": "16:9",
            "duration": 10,
            "prompt_extend": true
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## 매개변수 참조

### 공통 매개변수

| 매개변수            | 타입      | 설명                                                |
| --------------- | ------- | ------------------------------------------------- |
| `duration`      | integer | T2V/I2V: 2~~15초; R2V: 비디오 참조 시 2~~10초, 그 외 2\~15초 |
| `resolution`    | string  | `720P` 또는 `1080P`                                 |
| `prompt_extend` | boolean | 프롬프트 재작성, 기본값 `true`                              |
| `watermark`     | boolean | 워터마크, 기본값 `false`                                 |
| `seed`          | integer | 랜덤 시드, `[0, 2147483647]`                          |

### T2V & R2V

| 매개변수    | 타입     | 설명                                                                |
| ------- | ------ | ----------------------------------------------------------------- |
| `ratio` | string | `16:9`, `9:16`, `1:1`, `4:3`, `3:4`. I2V 화면 비율은 에셋을 따름—`ratio` 생략 |

### 미디어 제한

| 유형                     | 형식                        | 크기      | 참고                                            |
| ---------------------- | ------------------------- | ------- | --------------------------------------------- |
| 이미지                    | JPEG, JPG, PNG, BMP, WEBP | ≤ 20MB  | 240~~8000px, 비율 1:8~~8:1                      |
| 오디오 (driving\_audio)   | WAV, MP3                  | ≤ 15MB  | 2\~30초                                        |
| 오디오 (reference\_voice) | WAV, MP3                  | ≤ 15MB  | 1\~10초                                        |
| 비디오                    | MP4, MOV                  | ≤ 100MB | first\_clip: 2~~10초; reference\_video: 1~~30초 |

## 오류 처리

| HTTP | 의미       | 조치                     |
| ---- | -------- | ---------------------- |
| 400  | 잘못된 매개변수 | `metadata` 및 미디어 제한 확인 |
| 401  | 인증 실패    | API Key 확인             |
| 429  | 요청 한도 초과 | 나중에 재시도                |
| 502  | 업스트림 오류  | 나중에 재시도                |

실패 시 `status`는 `failed`이며 `error.message`에 세부 정보가 있습니다.

## FAQ

<AccordionGroup>
  <Accordion title="비디오 URL은 얼마나 유효한가요?">
    `url`과 `task_id`는 보통 **24시간** 유효합니다. 즉시 다운로드하여 저장하세요.
  </Accordion>

  <Accordion title="보이스 참조는 어떻게 사용하나요?">
    **wan2.7-r2v**만 `reference_image` 또는 `reference_video`에 `reference_voice`(1\~10초 오디오 URL)를 지원합니다.
  </Accordion>

  <Accordion title="I2V 모드는 무엇을 지원하나요?">
    * **첫 프레임**: `first_frame`(선택적 `driving_audio`)
    * **첫 + 마지막**: `first_frame` + `last_frame`
    * **연속 생성**: `first_clip`
  </Accordion>

  <Accordion title="Wan 2.7과 Wan 2.5의 차이는?">
    둘 다 `metadata.input` / `metadata.parameters`를 사용하지만, Wan 2.5 이미지-투-비디오는 `img_url`을 사용하고 Wan 2.7은 `media` 배열로 첫 프레임, 첫+마지막 프레임, 연속 생성, 참조-투-비디오 등을 지원합니다. [Wan 2.5](/ko/api-reference/endpoint/wan2.5)를 참조하세요.
  </Accordion>
</AccordionGroup>

## 관련 엔드포인트

<Columns cols={2}>
  <Card title="비디오 작업 제출" icon="upload" href="/ko/api-reference/endpoint/submit-video-task">
    통합 제출 엔드포인트 및 다중 모델 매개변수
  </Card>

  <Card title="비디오 작업 조회" icon="search" href="/ko/api-reference/endpoint/query-video-task">
    상태 폴링 및 비디오 URL 확인
  </Card>
</Columns>