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

# Grok Imagine 동영상 모델

> WideRouter에서 제공하는 xAI의 두 가지 동영상 모델로, 클립 생성·편집·확장과 길이, 해상도, 참조 이미지 및 사전 설정 음성을 지원합니다.

Grok Imagine 제품군의 두 모델은 동영상을 생성합니다. 두 모델 모두
[비동기 작업 API](/ko/api/async-tasks)를 사용하며, 다른 모든 기능과 동일한 봉투를 사용합니다 —
동기식 동영상 엔드포인트는 없으므로 두 모델에 접근하는 유일한 방법입니다.

두 모델은 단순한 구형 및 신형 조합이 아닙니다. `grok-imagine-video-1.5`은 더 높은
해상도로 생성하며 사전 설정 음성을 사용할 수 있습니다. `grok-imagine-video`은
**동영상을 입력으로** 받는 유일한 모델이며, 이는 편집과 확장에 필요합니다.
클립을 새로 만들지, 기존 클립을 변경할지에 따라 사용할 모델이 달라집니다.

## 시리즈 한눈에 보기

|                   | Grok Imagine Video 1.5        | Grok Imagine Video   |
| ----------------- | ----------------------------- | -------------------- |
| **모델 ID**         | `grok-imagine-video-1.5`      | `grok-imagine-video` |
| 텍스트를 동영상으로        | 예                             | 예                    |
| 이미지를 동영상으로(첫 프레임) | 예                             | 예                    |
| 참조 이미지            | 최대 3개, 예                      | 최대 3개, 예             |
| **기존 클립 편집**      | 아니요                           | **예**                |
| **기존 클립 확장**      | 아니요                           | **예**                |
| 해상도               | `480p` / `720p` / **`1080p`** | `480p` / `720p`      |
| 사전 설정 음성          | **예**, 최대 3개                  | 아니요                  |
| 무음 출력             | 예                             | 예                    |
| 길이                | 1\~15초                        | 1\~15초               |

모델에서 지원하지 않는 작업을 요청하면 대기열에 추가되기 전에 제출 시점에
실패하며, 대신 사용할 모델을 안내하는 메시지가 표시됩니다.

```json theme={null}
{
  "error": {
    "code": "invalid_params",
    "message": "edit needs a model that takes video input; use grok-imagine-video",
    "param": "input.mode"
  }
}
```

## 모드

`input.mode`은 모델이 수행할 작업을 선택합니다. `generate`, `edit` 또는
`extend`을 사용하며, 기본값은 `generate`입니다.

| `mode`     | `input.video` 필요 여부 | 출력 길이              | 모델                    |
| ---------- | ------------------- | ------------------ | --------------------- |
| `generate` | 아니요                 | `duration` + 0.04초 | 둘 다                   |
| `edit`     | 예                   | **원본을 따름**         | `grok-imagine-video`만 |
| `extend`   | 예                   | 원본 + `duration`    | `grok-imagine-video`만 |

`edit`은 프롬프트를 사용해 기존 클립을 다시 작성하고 길이를 유지하므로
`resolution`을 허용하지 않습니다. 출력은 원본을 따릅니다. `extend`은 새로운
영상을 끝에 추가합니다.

```json theme={null}
{
  "model": "grok-imagine-video",
  "input": {
    "prompt": "the camera slowly pulls back",
    "mode": "extend",
    "video": "https://example.com/boat.mp4",
    "duration": 3
  }
}
```

측정 결과: `duration: 3`을 사용한 3.04초 원본에서 **6.04초**
클립이 생성되었습니다. 이는 다시 렌더링한 것이 아니라 원본에 3초를 확장한 결과입니다.

<Warning>
  **`duration` 범위는 `extend` 모드에서 좁아집니다.** 계약상 1\~15
  초를 허용하지만, 확장 길이는 실제로 **2\~10초**로 제한되며 원본 클립
  자체도 **최소 2초** 이상이어야 합니다. 두 제한 모두 제출 시점에는
  확인되지 않으므로 작업이 대기열에 추가된 후 작업 수준 실패로 반환됩니다:

  `Duration must be between 2 and 10 seconds` · `Input video must be at least 2 seconds long, got 1.0s`
</Warning>

## 매개변수

아래의 모든 항목은 `input` 안에 들어갑니다. 엔벌로프는
[비동기 작업 API](/ko/api/async-tasks)에 설명되어 있습니다.

| 필드                 | 유형     | 기본값        | 참고                                                                  |
| ------------------ | ------ | ---------- | ------------------------------------------------------------------- |
| `prompt`           | 문자열    | —          | 필수입니다.                                                              |
| `mode`             | 문자열    | `generate` | `generate`, `edit` 또는 `extend`입니다.                                  |
| `duration`         | 정수     | 모델 기본값     | 1\~15초입니다. `extend`에 관한 경고는 위를 참조하십시오.                              |
| `resolution`       | 문자열    | `480p`     | 1.5에서만 `480p`, `720p` 또는 `1080p`입니다. `edit` 모드에서는 허용되지 않습니다.        |
| `aspect_ratio`     | 문자열\[] | `16:9`     | `1:1` `16:9` `9:16` `4:3` `3:4` `3:2` `2:3` 중 하나입니다.                |
| `images`           | 문자열\[] | —          | 정확히 하나의 이미지이며, **첫 번째 프레임**으로 사용됩니다.                                |
| `video`            | 문자열    | —          | `edit` 및 `extend`의 소스 클립입니다. `https` URL 또는 base64 동영상 데이터 URI입니다.  |
| `reference_images` | 문자열\[] | —          | 모델이 스타일과 피사체를 참고할 이미지로 최대 3개까지 지정할 수 있습니다. `images`와 함께 사용할 수 없습니다. |
| `voice_ids`        | 문자열\[] | —          | 프리셋 음성은 최대 3개까지 지정할 수 있습니다. `grok-imagine-video-1.5`에서만 사용할 수 있습니다. |
| `generate_audio`   | 불리언    | `true`     | 무음 클립을 사용하려면 `false`로 설정하십시오. 가격은 변경되지 않습니다.                        |

`n`은 없습니다. 동영상 모델은 작업당 하나의 클립을 생성합니다.

<Note>
  이미지 모델과 달리 동영상에는 **`auto` 가로세로 비율**이 없으며 초광각
  비율도 없습니다. 위의 7가지 값이 전체 목록입니다.
</Note>

## 해상도 및 길이

측정된 출력 픽셀, 티어당 샘플 하나:

| `resolution` | `aspect_ratio` | 출력          |
| ------------ | -------------- | ----------- |
| `480p`       | `16:9` (기본값)   | 848 × 480   |
| `480p`       | `9:16`         | 480 × 848   |
| `720p`       | `16:9`         | 1280 × 720  |
| `1080p`      | `16:9`         | 1920 × 1088 |

`1080p`은 `grok-imagine-video`에서
`1080p is only available on grok-imagine-video-1.5`와 함께 거부됩니다.

**클립은 요청한 길이보다 약 0.04초 더 길게 반환됩니다** — 3초를 요청하면
파일 길이는 3.04초입니다. 이는 모든 샘플에서 일관되며, 요청한 길이를 기준으로
과금되므로 청구 금액에는 영향을 주지 않습니다.

## 참조 이미지, 첫 프레임 및 음성

세 가지 항목을 입력할 수 있으며, 그중 두 가지는 상호 배타적입니다.

* \*\*`images`\*\*은 **첫 프레임**입니다. 이미지는 정확히 하나만 사용할 수 있으며, 클립은 해당 프레임에서 바깥쪽으로 애니메이션됩니다.
* \*\*`reference_images`\*\*은 스타일 및 주제 가이드이며, 이미지는 최대 세 개까지 사용할 수 있습니다. 두 모델 모두 이를 지원하지만, 사용하면 출력이 \*\*`720p`\*\*로 제한됩니다. 따라서 `reference_images`과 `1080p`를 함께 사용하면 `reference images are capped at 720p`와 함께 요청이 거부됩니다.
* 두 항목을 모두 전달하면 요청이 거부됩니다.
  `cannot be combined with images; a first frame and reference images are different modes`.

`voice_ids`은 `grok-imagine-video-1.5`에서 사전 설정된 음성을 선택하며, 클립당 최대 세 개까지 선택할 수 있습니다. 허용되는 값은 다음과 같습니다.

|          |           |          |          |          |          |
| -------- | --------- | -------- | -------- | -------- | -------- |
| `ara`    | `eve`     | `leo`    | `rex`    | `sal`    | `carina` |
| `zagan`  | `helix`   | `orion`  | `luna`   | `iris`   | `altair` |
| `zenith` | `perseus` | `helios` | `lux`    | `kepler` | `rigel`  |
| `cosmo`  | `celeste` | `ursa`   | `sirius` | `lumen`  | `castor` |
| `naksh`  | `atlas`   |          |          |          |          |

WideRouter에서는 사용자 지정 음성을 사용할 수 없습니다. 음성 ID 자체는 제출 시점에 **검증되지 않는다**는 점에 유의하십시오. 인식할 수 없는 이름도 허용되지만, 이후 작업이 실패합니다. 음성과 `generate_audio: false`는 모두 가격을 변경하지 않습니다.

## 요금

이 모델들은 **`Grok-Official`** 그룹을 통해 제공됩니다. WideRouter의 정가 목록은 xAI의 공식 가격과 정확히 일치하며, 할인은 **그룹 요율 배수**에 적용됩니다. `Grok-Official`의 경우 `0.8`입니다. 따라서 실제 지불 금액은 다음과 같습니다.

```
list price × group multiplier = charge
```

동영상은 해상도에 따라 **출력 초당** 요금이 부과됩니다. 다음은 정가입니다.

| 모델                       | `480p`     | `720p`     | `1080p`    |
| ------------------------ | ---------- | ---------- | ---------- |
| `grok-imagine-video-1.5` | \$0.08 / s | \$0.14 / s | \$0.25 / s |
| `grok-imagine-video`     | \$0.05 / s | \$0.07 / s | 이용 불가      |

초당 요금만으로는 알 수 없는 세 가지 규칙은 다음과 같습니다.

* **전송하는 미디어에도 요금이 부과됩니다.** 참조 이미지를 추가하면 약 \$0.01이
  부과됩니다. `edit` 또는 `extend`의 소스 클립에는 해당 클립 자체의 길이에 따라
  초당 약 \$0.01의 요금이 부과됩니다.
* **`extend`는 원본에 다시 요금을 부과하지 않습니다.** 새 세그먼트에만 초당
  요금이 부과되며, 소스 클립은 입력으로 별도 요금이 부과됩니다. 측정 결과,
  3.04초 클립을 3초 연장하는 데 \$0.18이 들었습니다. 이는 \$0.05의 출력
  3초분과 \$0.01의 입력 3.04초분을 합한 금액이며, 결과물의 길이는 6.04초입니다.
  6초를 처음부터 다시 생성했다면 \$0.30이 들었을 것입니다.
* **`edit`에는 소스 길이의 약 두 배에 해당하는 요금이 부과됩니다.** 출력과
  입력에 각각 한 번씩 요금이 부과됩니다. 측정 결과, 1.04초 클립을 편집하는 데
  \$0.06이 들었습니다.

처음부터 끝까지 살펴보는 예시입니다. `grok-imagine-video`에서 `480p`를 3초 생성하는 경우입니다.

```
\$0.05 / s × 3 s        = \$0.15   list price
\$0.15 × 0.8            = \$0.12   charged on Grok-Official
```

<Info>
  완료된 작업에는 `usage.cost_in_usd_ticks`이 적용되며, 여기서 `10000000000` 틱은
  \$1입니다. 이 금액은 **정가**이며 그룹 요율 배수를 적용하기 전의 값입니다.
  실제로 잔액에서 차감되는 금액을 확인하려면 여기에 그룹의 요율을 곱합니다.
</Info>

## 지연 시간

비동기 API에서 엔드투엔드로 측정했으며, `completed`에 제출합니다:

| 요청                                    | 엔드투엔드  |
| ------------------------------------- | ------ |
| `grok-imagine-video`, `480p`, 1초      | 19초    |
| `grok-imagine-video-1.5`, `480p`, 1초  | 21초    |
| `grok-imagine-video`, `480p`, 3초      | 21–30초 |
| `grok-imagine-video`, 1초 클립의 `edit`   | 30초    |
| `grok-imagine-video`, `extend`로 3초 연장 | 30초    |
| `grok-imagine-video-1.5`, `1080p`, 3초 | \~48초  |
| `grok-imagine-video-1.5`, `480p`, 15초 | \~51초  |

생성은 동영상 모델에 흔히 언급되는 “보통 몇 분”보다 훨씬 빠르지만,
연결을 계속 열어 둘 수 없을 만큼은 여전히 느립니다. 따라서 동기식 엔드포인트는 없습니다. 2\~3초마다 폴링하고, 클라이언트 타임아웃은 가장 빠른 행이 아니라
여기서 가장 느린 행을 기준으로 설정하십시오.

## 작업이 실패하는 경우

동영상 실패는 HTTP 오류가 아니라 `error` 객체가 포함된 `failed` 작업으로 반환됩니다. 읽기 엔드포인트는 여전히 `200`를 반환합니다. 일반적인 코드는
`upstream_error`이며, 메시지는 xAI에서 그대로 전달됩니다.

```json theme={null}
{
  "status": "failed",
  "counts": { "requested": 1, "succeeded": 0, "failed": 1 },
  "error": {
    "code": "upstream_error",
    "message": "Input video must be at least 2 seconds long, got 1.0s"
  }
}
```

생성이 시작되기 전에 발생하는 실패는 빠르게 처리됩니다. 연결할 수 없는 입력의 경우 1초 이내이며, 업스트림 모델이 적용하는 제약 조건의 경우 약 6초가 걸립니다.

## 다음 단계

<CardGroup cols={2}>
  <Card title="Playground" icon="play" href="/ko/models/grok-imagine/video/playground">
    브라우저에서 실제 동영상 작업을 제출하고 완료될 때까지 폴링합니다.
  </Card>

  <Card title="Grok Imagine 이미지" icon="image" href="/ko/models/grok-imagine/image/overview">
    제품군의 이미지 부분 — 세 가지 변형과 품질 그리드입니다.
  </Card>
</CardGroup>