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

# HappyHorse 비디오 생성

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

## 소개

HappyHorse는 Alibaba Cloud Bailian의 비디오 생성 제품군입니다: 텍스트-투-비디오(HappyHorse-T2V), 이미지-투-비디오(HappyHorse-I2V), 참조-투-비디오(HappyHorse-R2V). **720P** 및 **1080P**에서 물리적으로 사실적이고 부드러운 동작의 비디오를 **3\~15초** 길이로 생성합니다.

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

<Note>
  HappyHorse는 Wan 2.7과 동일한 구조로 `metadata.input` 및 `metadata.parameters`를 통해 기본 DashScope 매개변수를 전달합니다. 참조-투-비디오는 프롬프트에서 **`[Image 1]`, `[Image 2]`**(영문 괄호 형식)를 사용하며 이미지 참조만 지원합니다—비디오 참조는 없습니다.
</Note>

## 인증

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

## 지원 모델

| 모델 ID                | 설명               | 해상도         | 최대 길이 | 주요 기능                   |
| -------------------- | ---------------- | ----------- | ----- | ----------------------- |
| `happyhorse-1.0-t2v` | 텍스트-투-비디오        | 720P, 1080P | 15초   | 텍스트 의미, 다양한 화면 비율       |
| `happyhorse-1.0-i2v` | 이미지-투-비디오(첫 프레임) | 720P, 1080P | 15초   | 첫 프레임 기반; 화면 비율은 입력을 따름 |
| `happyhorse-1.0-r2v` | 참조-투-비디오         | 720P, 1080P | 15초   | 최대 9개 참조 이미지, 주체 융합     |

## 워크플로

1. **작업 제출**: `model`, `prompt`, `duration` 및 `metadata`의 HappyHorse 매개변수와 함께 `POST /v1/video/generations`.
2. **상태 폴링**: `status`가 `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` 등                                        |
| `metadata.parameters` | object  | 아니오    | 매개변수: `resolution`, `ratio`, `duration`, `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>
      원하는 비디오를 설명하는 텍스트 프롬프트
    </ParamField>

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

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

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

    <ParamField body="metadata.parameters.watermark" type="boolean" default="true">
      워터마크 추가(우하단 고정 텍스트 "Happy Horse")
    </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": "happyhorse-1.0-t2v",
        "prompt": "A miniature city built from cardboard and bottle caps comes alive at night. A cardboard train rolls through, tiny lights illuminating the path ahead.",
        "duration": 5,
        "metadata": {
          "input": {
            "prompt": "A miniature city built from cardboard and bottle caps comes alive at night. A cardboard train rolls through, tiny lights illuminating the path ahead."
          },
          "parameters": {
            "resolution": "720P",
            "ratio": "16:9",
            "duration": 5,
            "watermark": false
          }
        }
      }'
    ```
  </Tab>

  <Tab title="이미지-투-비디오 (I2V)">
    첫 프레임 이미지와 선택적 텍스트 가이드로 비디오를 생성합니다. 화면 비율은 첫 프레임을 따릅니다—**`ratio`를 전달하지 마세요**.

    #### media 유형

    | type          | 설명        | 제한     |
    | ------------- | --------- | ------ |
    | `first_frame` | 첫 프레임 이미지 | 정확히 1개 |

    <ParamField body="metadata.input.prompt" type="string">
      첫 프레임이 어떻게 움직일지 설명하는 텍스트 프롬프트(선택)
    </ParamField>

    <ParamField body="metadata.input.media" type="array" required>
      `first_frame` 객체 1개가 포함된 미디어 목록, 각각 `type`과 `url` 포함
    </ParamField>

    <ParamField body="metadata.parameters.resolution" type="string" default="1080P">
      `720P` 또는 `1080P`. 출력 화면 비율은 첫 프레임에 근사
    </ParamField>

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

    <ParamField body="metadata.parameters.watermark" type="boolean" default="true">
      워터마크 추가
    </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": "happyhorse-1.0-i2v",
        "prompt": "A cat running across the grass",
        "duration": 5,
        "metadata": {
          "input": {
            "prompt": "A cat running across the grass",
            "media": [
              {"type": "first_frame", "url": "https://example.com/first_frame.png"}
            ]
          },
          "parameters": {
            "resolution": "720P",
            "duration": 5,
            "watermark": false
          }
        }
      }'
    ```
  </Tab>

  <Tab title="참조-투-비디오 (R2V)">
    **1\~9**개의 참조 이미지를 전달하고 텍스트로 장면을 설명하여 주체를 부드러운 비디오로 융합합니다. 프롬프트에서 \*\*`[Image 1]`, `[Image 2]`\*\*로 `media` 항목을 참조합니다(순서 일치 필요).

    #### media 유형

    | type              | 설명     | 제한   |
    | ----------------- | ------ | ---- |
    | `reference_image` | 참조 이미지 | 1\~9 |

    <ParamField body="metadata.input.prompt" type="string" required>
      `[Image n]` 참조를 사용하는 프롬프트; 각 참조의 구체적 객체 명시, 예: "\[Image 1]의 빨간 치파오를 입은 여성"
    </ParamField>

    <ParamField body="metadata.input.media" type="array" required>
      참조 이미지 목록; 1번째 = `[Image 1]`, 2번째 = `[Image 2]` 등
    </ParamField>

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

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

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

    <ParamField body="metadata.parameters.watermark" type="boolean" default="true">
      워터마크 추가
    </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": "happyhorse-1.0-r2v",
        "prompt": "The woman in a red cheongsam in [Image 1] opens the folding fan from [Image 2] while tassel earrings from [Image 3] sway gently.",
        "duration": 5,
        "metadata": {
          "input": {
            "prompt": "The woman in a red cheongsam in [Image 1] opens the folding fan from [Image 2] while tassel earrings from [Image 3] sway gently.",
            "media": [
              {"type": "reference_image", "url": "https://example.com/girl.jpg"},
              {"type": "reference_image", "url": "https://example.com/fan.jpg"},
              {"type": "reference_image", "url": "https://example.com/earrings.jpg"}
            ]
          },
          "parameters": {
            "resolution": "720P",
            "ratio": "16:9",
            "duration": 5,
            "watermark": false
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## 매개변수 참조

### 공통 매개변수

| 매개변수         | 타입      | 설명                             |
| ------------ | ------- | ------------------------------ |
| `duration`   | integer | 3\~15초, 기본값 `5`                |
| `resolution` | string  | `720P` 또는 `1080P`, 기본값 `1080P` |
| `watermark`  | boolean | 워터마크 추가, 기본값 `true`            |
| `seed`       | integer | 랜덤 시드, 범위 `[0, 2147483647]`    |

### 텍스트-투-비디오 & 참조-투-비디오

| 매개변수    | 타입     | 설명                                                                                                       |
| ------- | ------ | -------------------------------------------------------------------------------------------------------- |
| `ratio` | string | `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `4:5`, `5:4`, `9:21`, `21:9`, 기본값 `16:9`. I2V는 첫 프레임을 따름—`ratio` 생략 |

### 미디어 입력 제한

| 유형                         | 형식                   | 크기     | 기타 제한                                 |
| -------------------------- | -------------------- | ------ | ------------------------------------- |
| 첫 프레임 (`first_frame`)      | JPEG, JPG, PNG, WEBP | ≤ 20MB | 너비·높이 ≥ 300px                         |
| 참조 이미지 (`reference_image`) | JPEG, JPG, PNG, WEBP | ≤ 20MB | 짧은 변 ≥ 400px; 720P+ 선명도 권장; 1\~9개 이미지 |

## 오류 처리

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

실패 시 `status`는 `failed`이며 `error.message`에 원인이 포함됩니다.

## FAQ

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

  <Accordion title="R2V에서 이미지는 어떻게 참조하나요?">
    프롬프트에서 \*\*`[Image 1]`, `[Image 2]`\*\*를 사용하세요. 순서는 `media`의 `reference_image` 항목과 일치합니다. 각 참조의 구체적 객체를 설명하세요.
  </Accordion>

  <Accordion title="I2V 모드는 무엇을 지원하나요?">
    HappyHorse I2V는 **첫 프레임**(`first_frame`)만 지원합니다—첫+마지막 프레임, 연속 생성, 오디오 드라이빙은 없습니다.
  </Accordion>

  <Accordion title="Wan 2.7과의 차이는?">
    동일한 `metadata.input` / `metadata.parameters` 구조. HappyHorse R2V는 `[Image n]`과 이미지만 사용(최대 9개); Wan 2.7은 图n/视频n과 비디오 참조 및 보이스 클론을 사용합니다. HappyHorse는 기본 1080P 및 워터마크 켜짐; 길이는 3\~15초입니다.
  </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>