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

> Alibaba Wan 2.5 텍스트-투-비디오, 이미지-투-비디오

## 소개

Wan 2.5는 Alibaba Cloud Bailian의 비디오 생성 제품군으로, 텍스트-투-비디오(`wan2.5-t2v-preview`)와 이미지-투-비디오(`wan2.5-i2v-preview`)로 구성됩니다. **480P**, **720P**, **1080P** 출력을 지원합니다.

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

<Note>
  Wan 2.5는 `metadata.input` 및 `metadata.parameters`를 통해 기본 DashScope 매개변수를 전달하는 것을 권장합니다. 최상위 `prompt`, `duration` 등은 호환용이며, **실제 적용은 `metadata.parameters`가 우선**합니다.
</Note>

## 인증

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

## 지원 모델

| 모델 ID                | 설명        | 해상도               | 주요 기능            |
| -------------------- | --------- | ----------------- | ---------------- |
| `wan2.5-t2v-preview` | 텍스트-투-비디오 | 480P, 720P, 1080P | 텍스트 프롬프트로 비디오 생성 |
| `wan2.5-i2v-preview` | 이미지-투-비디오 | 480P, 720P, 1080P | 첫 프레임 이미지 기반 생성  |

## 호출 흐름

1. **제출**: `model`, `prompt` 및 `metadata`의 Wan 매개변수와 함께 `POST /v1/video/generations`.
2. **폴링**: `GET /llm-api/v1/video/generations/{id}`(호스트 `maas.gravitex.ai`)를 3\~15초마다 호출하여 `data.status`가 `completed` 또는 `failed`가 될 때까지 대기.
3. **결과**: 성공 시 `data.url`, `data.video_url` 또는 `data.metadata.output.video_url`에서 비디오 주소 확인(일반적으로 임시 링크—즉시 다운로드 권장).

## 요청 구조

| 필드                    | 타입      | 필수  | 설명                                                                               |
| --------------------- | ------- | --- | -------------------------------------------------------------------------------- |
| `model`               | string  | 예   | 모델 ID(위 표 참조)                                                                    |
| `prompt`              | string  | 권장  | 비디오 프롬프트; `metadata.input.prompt`와 동기화 권장                                        |
| `duration`            | integer | 아니오 | 최상위 길이; `metadata.parameters.duration`과 다르면 후자가 우선                               |
| `metadata.input`      | object  | 예   | 입력: `prompt`, `img_url`(이미지-투-비디오) 등                                             |
| `metadata.parameters` | object  | 권장  | 처리 매개변수: `resolution`, `ratio`, `duration`, `prompt_extend`, `watermark`, `seed` |

### 제출 응답

제출 API는 OpenAI Video 스타일 객체를 반환하며, 후속 조회에는 `id`를 작업 ID로 사용합니다:

```json theme={null}
{
  "id": "d09ee9f4-04ba-4c3f-bc1b-974cb19e109f",
  "object": "video",
  "model": "wan2.5-i2v-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1781767983,
  "metadata": {
    "output": {
      "task_id": "d09ee9f4-04ba-4c3f-bc1b-974cb19e109f",
      "task_status": "PENDING"
    },
    "request_id": "2a17a551-0db2-910d-988b-7d5abed99d2d"
  }
}
```

### 조회 응답

조회 API는 래핑된 구조를 반환하며, `data.status`가 `completed`이면 성공입니다:

```json theme={null}
{
  "code": "success",
  "message": "",
  "data": {
    "id": "d09ee9f4-04ba-4c3f-bc1b-974cb19e109f",
    "object": "video",
    "model": "wan2.5-i2v-preview",
    "status": "completed",
    "progress": 100,
    "seconds": "3",
    "url": "https://xxx.mp4",
    "video_url": "https://xxx.mp4",
    "created_at": 1781767983,
    "completed_at": 1781768013,
    "metadata": {
      "output": {
        "task_id": "d09ee9f4-04ba-4c3f-bc1b-974cb19e109f",
        "task_status": "SUCCEEDED",
        "orig_prompt": "풀을 뜯는 양\n",
        "video_url": "https://xxx.mp4",
        "submit_time": "2026-06-18 15:33:03.266",
        "scheduled_time": "2026-06-18 15:33:03.285",
        "end_time": "2026-06-18 15:33:32.407"
      },
      "usage": {
        "SR": 480,
        "duration": 3,
        "video_count": 1
      },
      "url": "https://xxx.mp4",
      "video_url": "https://xxx.mp4"
    }
  }
}
```

## 사용 사례

<Tabs>
  <Tab title="텍스트-투-비디오 (T2V)">
    텍스트 프롬프트로 비디오를 생성합니다. 스마트 프롬프트 재작성, 사용자 지정 해상도 및 화면 비율을 지원합니다.

    <ParamField body="metadata.input.prompt" type="string" required>
      텍스트 프롬프트; 최상위 `prompt`와 동기화 권장
    </ParamField>

    <ParamField body="metadata.parameters.resolution" type="string" default="720P">
      `480P`, `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">
      비디오 길이(초); 일반적인 값: 3, 5, 10
    </ParamField>

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

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

    <ParamField body="metadata.parameters.seed" type="integer">
      랜덤 시드, 범위 `[0, 2147483647]`
    </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.5-t2v-preview",
        "prompt": "새끼 고양이가 천천히 눈을 뜨고, 귀가 살짝 떨리며, 카메라가 천천히 다가갑니다",
        "metadata": {
          "input": {
            "prompt": "새끼 고양이가 천천히 눈을 뜨고, 귀가 살짝 떨리며, 카메라가 천천히 다가갑니다"
          },
          "parameters": {
            "resolution": "720P",
            "ratio": "16:9",
            "duration": 5,
            "prompt_extend": true,
            "watermark": false
          }
        }
      }'
    ```
  </Tab>

  <Tab title="이미지-투-비디오 (I2V)">
    첫 프레임 이미지로 비디오를 생성합니다. `metadata.input.img_url`로 첫 프레임 이미지 주소를 전달합니다.

    <ParamField body="metadata.input.img_url" type="string" required>
      첫 프레임 이미지 URL
    </ParamField>

    <ParamField body="metadata.input.prompt" type="string" required>
      텍스트 프롬프트; 최상위 `prompt`와 동기화 권장
    </ParamField>

    <ParamField body="metadata.input.media" type="array">
      선택 사항; 입력 미디어 유형 설명, 예: `[{"type": "reference_image"}]`
    </ParamField>

    <ParamField body="metadata.parameters.resolution" type="string" default="720P">
      `480P`, `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">
      비디오 길이(초); 일반적인 값: 3, 5, 10
    </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.5-i2v-preview",
        "prompt": "풀을 뜯는 양",
        "metadata": {
          "input": {
            "img_url": "https://example.com/first_frame.png",
            "prompt": "풀을 뜯는 양",
            "media": [
              {"type": "reference_image"}
            ]
          },
          "parameters": {
            "resolution": "480P",
            "ratio": "16:9",
            "duration": 3,
            "prompt_extend": true,
            "watermark": false
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## 매개변수 참조

### metadata.parameters

| 매개변수            | 타입      | 설명                                  |
| --------------- | ------- | ----------------------------------- |
| `duration`      | integer | 실제 적용되는 비디오 길이(초)                   |
| `resolution`    | string  | `480P`, `720P` 또는 `1080P`           |
| `ratio`         | string  | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` |
| `prompt_extend` | boolean | 스마트 프롬프트 재작성, 기본값 `true`            |
| `watermark`     | boolean | 워터마크 추가, 기본값 `false`                |
| `seed`          | integer | 랜덤 시드, 범위 `[0, 2147483647]`         |

### metadata.input

| 매개변수      | 타입     | 사용 사례     | 설명                  |
| --------- | ------ | --------- | ------------------- |
| `prompt`  | string | T2V / I2V | 업스트림에서 실제 사용하는 프롬프트 |
| `img_url` | string | I2V       | 첫 프레임 이미지 주소        |
| `media`   | array  | I2V       | 선택 사항; 입력 미디어 유형 설명 |

### 조회 응답 주요 필드

| 필드                                 | 설명                                                       |
| ---------------------------------- | -------------------------------------------------------- |
| `data.status`                      | 통합 작업 상태: `queued`, `in_progress`, `completed`, `failed` |
| `data.seconds`                     | 최종 비디오 길이(문자열)                                           |
| `data.url` / `data.video_url`      | 비디오 다운로드 주소                                              |
| `data.metadata.output.task_status` | 업스트림 원본 상태, 예: `SUCCEEDED`                               |
| `data.metadata.usage.SR`           | 해상도 등급, 예: `480`, `720`                                  |
| `data.metadata.usage.duration`     | 최종 과금/산출 길이                                              |

## 상태 매핑

| 업스트림 상태                           | 조회 API `data.status` |
| --------------------------------- | -------------------- |
| `PENDING`                         | `queued`             |
| `RUNNING`                         | `in_progress`        |
| `SUCCEEDED`                       | `completed`          |
| `FAILED` / `CANCELED` / `UNKNOWN` | `failed`             |

## 오류 처리

| HTTP 상태 | 의미      | 권장 조치                     |
| ------- | ------- | ------------------------- |
| 400     | 잘못된 요청  | `metadata` 구조 및 미디어 제한 확인 |
| 401     | 인증 실패   | API 키 확인                  |
| 429     | 요청 제한   | 빈도를 낮춰 재시도                |
| 502     | 업스트림 오류 | 나중에 재시도                   |

실패 시 `data.status`는 `failed`이며, `data.metadata.output.task_status`로 원인을 확인할 수 있습니다.

## 자주 묻는 질문

<AccordionGroup>
  <Accordion title="최상위 duration과 metadata.parameters.duration이 다르면?">
    **`metadata.parameters.duration`이 우선**합니다. 운영 환경에서는 최상위 `duration`을 생략하거나 두 값을 동일하게 유지하세요.
  </Accordion>

  <Accordion title="prompt는 몇 번 전달해야 하나요?">
    최상위 `prompt`와 `metadata.input.prompt`를 **동일하게 유지**하면 조회 결과의 `orig_prompt`와 요청이 일치합니다.
  </Accordion>

  <Accordion title="생성된 비디오 링크 유효 기간은?">
    `video_url`은 일반적으로 임시 OSS 링크입니다. 성공 후 즉시 다운로드하여 자체 저장소에 보관하세요.
  </Accordion>

  <Accordion title="작업 성공 여부는 어떻게 판단하나요?">
    다음 순서로 확인하세요:

    1. `data.status == "completed"`
    2. `data.video_url` 또는 `data.url`이 비어 있지 않음
    3. `data.metadata.output.task_status == "SUCCEEDED"`
  </Accordion>

  <Accordion title="Wan 2.5와 Wan 2.7의 차이는?">
    Wan 2.5는 텍스트-투-비디오와 첫 프레임 이미지-투-비디오만 지원하며, 2.7의 `media` 배열 대신 `metadata.input.img_url`을 사용합니다. Wan 2.7은 참조-투-비디오, 연속 생성, 첫+마지막 프레임 등 추가 기능을 제공합니다. [Wan 2.7](/ko/api-reference/endpoint/wan2.7)을 참조하세요.
  </Accordion>
</AccordionGroup>

## 관련 API

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