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

# Grok Imagine 동영상 생성

> APIYI의 xAI Grok Imagine 동영상 공식 채널에 대한 완벽 가이드입니다. grok-imagine-video / grok-imagine-video-1.5 / grok-imagine-video-1.5-lite, 네이티브 오디오를 지원하는 텍스트-동영상 및 이미지-동영상, 1–15초, 해상도별 초당 가격은 xAI와 동일합니다($0.02–0.25/s). OpenAI Videos와 호환되며, 신청을 통해 GrokOfficial 그룹 권한이 필요합니다.

## 개요

**Grok Imagine Video**는 xAI 동영상 모델을 위한 **공식 채널**입니다. 요청은 APIYI에 의해 공식 xAI API로 릴레이되며, **가격은 xAI 정가와 동일**하고 생성된 초 및 해상도에 따라 과금됩니다. 이 API는 **텍스트-동영상** 및 **이미지-동영상**을 지원하는 OpenAI Videos 호환 비동기 태스크 엔드포인트(`/v1/videos`)이며, 모든 동영상에는 오디오 트랙이 포함됩니다.

사용 가능한 모델은 세 가지입니다:

* **`grok-imagine-video`**: 기본 모델, 480p / 720p
* **`grok-imagine-video-1.5`**: 최신 모델, 480p / 720p / 1080p
* **`grok-imagine-video-1.5-lite`**: 경량화된 1.5 모델, 480p / 720p에서 가장 저렴한 가격 제공

> [!WARNING]
>
> **🔒 이 채널은 `GrokOfficial` 그룹이 필요하며, 신청 시 부여됩니다**
>
> Grok Imagine Video는 `Default` 그룹에 포함되어 있지 않습니다. 이 제품군의 콘텐츠 안전 정책은 플랫폼의 다른 모델과 크게 다르므로, 컴플라이언스 리스크를 제한하기 위해 접근 권한을 **선별적으로** 부여합니다:
>
> * **누적 사용 금액이 \$1,000+인 기존 고객**: 지원팀에 문의하여 사용 사례를 설명해 주시면 확인 후 활성화해 드립니다
> * **그 외 모든 사용자**: [WeCom 지원팀](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec)을 통해 신청하고 **사용 사례**와 **콘텐츠 검수 제어 장치**를 설명해 주시면 승인 후 활성화해 드립니다
>
> `GrokOfficial` 그룹이 없는 Token은 \*\*`503`\*\*를 반환합니다. 이는 서비스 장애가 아닌 권한 문제입니다. 아래의 [그룹 설정](#group-setup)을 참고하십시오.

> [!WARNING]
>
> **⚠️ `size`가 없으면 기본값은 480p 및 8초입니다**
>
> 해상도나 재생 시간 없이 제출하면 동영상이 **480p, 8초**로 생성 및 과금됩니다. 720p / 1080p 또는 더 짧은 클립을 원하시면 `size`(예: `"1280x720"`) 및 `seconds`을 명시적으로 전달하십시오.

> **[동영상 생성 API](/ko/api-capabilities/grok-imagine-video/video-generation)**
>
> 인터랙티브 Playground를 통해 텍스트-동영상 / 이미지-동영상 작업을 제출합니다.

> **[Grok Imagine 공식 이미지](/ko/api-capabilities/grok-imagine-image-official/overview)**
>
> 동일한 `GrokOfficial` 그룹 — xAI와 동일한 티어별 가격이 책정되는 이미지 생성입니다.

## AI 에이전트로 연동하기

이 프로젝트에서 Grok Imagine 동영상 생성(text-to-video + image-to-video)을 연동/문제 해결하십시오.

코드를 작성하기 전에 문서를 읽으십시오. 이 페이지의 일반 텍스트 버전을 확인하려면 [https://docs.apiyi.com/en/api-capabilities/grok-imagine-video/overview.md](https://docs.apiyi.com/en/api-capabilities/grok-imagine-video/overview.md) 를 호출하십시오. 자세한 매개변수 정보는 동영상 생성 페이지 URL에도 동일한 방식으로 `.md`를 붙여 가져오십시오.

요구사항:

1. 모델을 하나 선택하십시오: `grok-imagine-video` (480p / 720p), `grok-imagine-video-1.5` (480p / 720p / 1080p) 또는 `grok-imagine-video-1.5-lite` (경량 1.5). Token 그룹에는 과금 모드가 Pay-as-you-go Priority 또는 Pay-as-you-go인 `GrokOfficial`이 포함되어야 하며, 그렇지 않으면 모든 호출에서 503이 반환됩니다.

2. 비동기 3단계 흐름: `POST /v1/videos`을(를) 통해 제출하고 작업 `id`을(를) 수신 → `status`이(가) `completed` 또는 `failed`이 될 때까지 5\~10초마다 `GET /v1/videos/{id}` 폴링 → `GET /v1/videos/{id}/content`에서 MP4 다운로드(동일한 Authorization 헤더 사용). 전체 폴링 시간은 최대 10분으로 제한합니다.

3. 해상도와 재생 시간을 명시적으로 전달하십시오: `size` 픽셀 단위(예: `"1280x720"`, `"720x1280"`, `"1920x1080"`). 더 짧은 변을 기준으로 티어가 결정되며(≥1080은 1080p, ≥720은 720p, 그 외는 480p), 화면비는 지원되는 가장 가까운 비율로 자동 조정됩니다. `seconds` 범위는 1\~15입니다. **지정하지 않으면 기본값인 480p 및 8초로 설정되며, 해당 기준으로 과금됩니다.** `grok-imagine-video`은(는) 1080p를 지원하지 않으며 요청 시 400을 반환합니다.

4. Image-to-video: 동일한 엔드포인트에 `input_reference`을(를) 추가하고 공개 이미지 URL 또는 `data:image/...;base64,...` URI로 설정하십시오. 또는 필드 이름 `input_reference` 아래에 multipart 형식으로 파일을 업로드하십시오. 출력 프레임은 입력 이미지를 따릅니다.

5. 과금: 생성된 시간(초) × 해상도별 초당 요율에 image-to-video의 경우 입력 이미지당 소액의 수수료가 추가됩니다. 오디오를 꺼도 가격은 낮아지지 않습니다.

6. 검토: 콘텐츠 검토에 의해 차단된 작업도 `status` `completed`을(를) 반환하지만 동영상은 없으며, 응답에 `error.code: "moderation_blocked"`이(가) 포함되고 **여전히 과금됩니다**. 코드에서 이 필드를 확인하십시오. 이를 성공으로 처리하지 말고, 동일한 prompt로 무작정 재시도하지 마십시오.

7. 작업이 `completed` 상태가 되는 즉시 동영상을 다운로드할 수 있습니다. 링크를 유지하는 대신 즉시 자체 오브젝트 스토리지에 저장하십시오.

8. `APIYI_API_KEY` 환경 변수에서 키를 읽고 base\_url로 [https://api.apiyi.com/v1](https://api.apiyi.com/v1) 을(를) 사용하십시오. 절대 하드코딩하거나 git에 커밋하지 마십시오. 완료되면 실제로 2초 480p text-to-video 작업을 1회 실행하고 클립의 재생 시간, 해상도 및 호출 비용을 보여주십시오.

## 모델 및 요금

요금은 xAI의 정가와 동일하며 **생성된 동영상 초당** 기준으로 과금됩니다. 요율은 모델 및 해상도에 따라 달라집니다:

| 모델 | 480p | 720p | 1080p | 이미지-투-비디오 입력 이미지 |
| - | - | - | - | - |
| **`grok-imagine-video`** | \$0.05 / 초 | \$0.07 / 초 | 미지원 | \$0.002 / 이미지 |
| **`grok-imagine-video-1.5`** | \$0.08 / 초 | \$0.14 / 초 | \$0.25 / 초 | \$0.01 / 이미지 |
| **`grok-imagine-video-1.5-lite`** | \$0.02 / 초 | \$0.03 / 초 | \$0.14 / 초 | \$0.01 / 이미지 |

> [!NOTE]
>
> 모델 요금은 공식 사이트의 가격과 일치하며 공식 사이트의 가격 변동에 따라 변경될 수 있습니다. 위 표는 참고용일 뿐이며, 상단 내비게이션의 **모델 요금** 탭이 기준이 됩니다: [모델 요금](/en/models/index).

> [!NOTE]
>
> **과금 참고 사항 및 예시**
>
> * **비용 = 초 수 × 초당 요율 + 입력 이미지 수 × 이미지당 요금**. 예시: `grok-imagine-video`에서 1초 480p 이미지-투-비디오 작업의 경우 = 1 × \$0.05 + 1 × \$0.002 = **\$0.052**(당사 테스트 청구 내역과 일치).
> * **기본값도 과금됩니다**: `size` / `seconds`를 지정하지 않으면 작업이 480p로 8초 동안 실행되며, `grok-imagine-video` 기준 \$0.40가 부과됩니다.
> * **오디오는 별도로 과금되지 않습니다**: 동영상에는 기본적으로 오디오 트랙이 포함되며, 이를 비활성화해도 요금이 할인되지 않습니다.
> * **검토 차단 시에도 과금됩니다**: xAI는 모더레이션 시스템에 의해 차단된 동영상에 대해서도 요금을 청구하며, 당사 또한 동일한 기준으로 과금합니다. 자세한 내용은 [FAQ](#faq)를 참조하십시오.
> * [구간별 충전 보너스](/ko/faq/recharge-promotions)가 추가로 적용됩니다. 대규모 비즈니스 고객의 경우 영업팀에 문의하여 전용 요율을 안내받으실 수 있습니다.

## 그룹 설정

> [!WARNING]
>
> **Grok Imagine Video는 `Default` 그룹에 포함되어 있지 않습니다.** 이 모델은 [Grok Imagine 공식 이미지](/ko/api-capabilities/grok-imagine-image-official/overview)와 공유되는 \*\*`GrokOfficial` 그룹(xAI와 동일한 가격, 즉 위의 표 참조)\*\*에 속해 있으며, 접근 권한을 신청해야 합니다.

### 접근 권한 신청 대상

| 고객 유형 | 접근 권한 획득 방법 |
| - | - |
| **누적 소비 \$1,000 이상 기존 고객** | 사용 목적을 고객지원팀에 전달, 확인 후 활성화 |
| **기타 모든 고객** | 사용 목적 및 콘텐츠 검토 제어 방안을 첨부하여 신청, 승인 후 활성화 |

### 신청 방법

**1. WeCom 고객지원 문의**

[WeCom 고객지원](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec) 또는 이메일([hi@apiyi.com](mailto:hi@apiyi.com))로 신청해 주십시오. **`GrokOfficial`(Grok Imagine 공식)** 권한을 신청한다고 명시해 주시기 바랍니다.

**2. 사용 목적 및 검토 제어 방안 설명**

동영상의 용도, 최종 사용자, 그리고 귀사 측에서 실행하는 콘텐츠 검토 및 수동 점검 방식의 세 가지 항목을 포함해 주십시오. 구체적일수록 심사가 빨라집니다.

**3. 승인 후 Token 그룹 전환**

승인되면 계정에 `GrokOfficial`이(가) 활성화됩니다. [콘솔의 Token 페이지](https://api.apiyi.com/token)로 이동하여 이 채널에 사용하는 Token을 `GrokOfficial`(으)로 전환하고, 과금 방식을 `Pay-as-you-go Priority` 또는 `Pay-as-you-go`(으)로 설정하십시오.

> [!NOTE]
>
> **접근 권한이 부여되기 전 표시 내용**: `GrokOfficial` 그룹이 없는 Token은 \*\*`503`(현재 그룹에 사용 가능한 채널 없음)\*\*을 반환합니다. 재시도해도 해결되지 않으며, 먼저 그룹을 활성화해야 합니다.
>
> **`Pay-per-request` 과금 방식을 사용하지 마십시오**: 이 채널은 초당 과금되므로, 요청당 과금 Token은 라우팅될 수 없으며 동일하게 503을 반환합니다.

> [!NOTE]
>
> **규정 준수 안내**: 접근 권한이 부여된 후 생성된 콘텐츠에 대한 책임은 호출자에게 있습니다. 현지 법률 및 규정을 준수하십시오. 불법 콘텐츠, 타인의 초상권이나 지식재산권을 침해하는 콘텐츠, 미성년자에게 부적절한 콘텐츠를 생성해서는 안 됩니다. 일반 소비자 대상 배포의 경우 자체 검토 레이어를 추가하십시오. 배경 정보: [해외 모델 호출 규정 준수 안내](/ko/faq/overseas-model-compliance). 오남용이 발견될 경우 그룹 접근 권한이 회수됩니다.

## 기술 사양

| 항목 | 사양 |
| - | - |
| 모델 ID | `grok-imagine-video`, `grok-imagine-video-1.5`, `grok-imagine-video-1.5-lite` |
| 지원 기능 | 텍스트-동영상 생성, 이미지-동영상 생성(단일 입력 이미지) |
| 재생 시간 | `seconds` 1\~15초, **기본값 8초** |
| 해상도 | 480p(기본값) / 720p / 1080p(`grok-imagine-video`에서는 1080p 미지원) |
| 화면비 | `size`는 가장 가까운 `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3` 비율로 자동 조정되며, 이미지-동영상 생성은 입력 이미지를 따릅니다 |
| 오디오 | 기본 포함 |
| 생성 시간 | 480p 2초 기준 약 20~~25초, 이미지-동영상 생성 약 35~~50초, 1.5 기준 1080p 약 110초 소요 |
| 다운로드 | 작업이 `completed` 상태가 되는 즉시 `/v1/videos/{id}/content`에서 이용 가능 |
| 권장 폴링 주기 | 5\~10초마다 확인, 전체 최대 제한 시간 10분 |

## 엔드포인트

| 단계 | 메서드 | 경로 | 참고 사항 |
| - | - | - | - |
| ① 제출 | `POST` | `/v1/videos` | `application/json`; 이미지-동영상 생성의 경우 `multipart/form-data` 형식으로 파일을 업로드할 수도 있습니다 |
| ② 상태 확인 | `GET` | `/v1/videos/{id}` | `status` / `progress`을(를) 반환하며, 완료 시 `seconds`도 함께 반환합니다 |
| ③ 다운로드 | `GET` | `/v1/videos/{id}/content` | MP4를 반환합니다. Authorization 헤더가 필요합니다 |

> [!TIP]
>
> 기본 도메인은 `https://api.apiyi.com`, 보조 도메인은 `https://b.apiyi.com`입니다. 전체 코드 예제: [동영상 생성 API](/ko/api-capabilities/grok-imagine-video/video-generation).

### 엔드투엔드 흐름 (Python)

```python theme={null}
import os, time, requests

BASE = "https://api.apiyi.com/v1"
H = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}

# ① Submit: 720p landscape, 5 seconds
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "grok-imagine-video-1.5",
    "prompt": "a red paper boat drifting on a calm lake, gentle ripples, soft morning light",
    "seconds": "5",
    "size": "1280x720",
}, timeout=60).json()
vid = task["id"]

# ② Poll
for _ in range(60):
    time.sleep(8)
    job = requests.get(f"{BASE}/videos/{vid}", headers=H, timeout=60).json()
    if job["status"] in ("completed", "failed"):
        break

if job["status"] == "failed" or job.get("error"):
    # A moderation block also reports completed, but with error.code = moderation_blocked
    raise RuntimeError(job.get("error"))

# ③ Download the video and store it right away
mp4 = requests.get(f"{BASE}/videos/{vid}/content", headers=H, timeout=300)
open("out.mp4", "wb").write(mp4.content)
```

## 주요 파라미터

### `size` (해상도 및 가로세로 비율)

`size`은(는) `WIDTHxHEIGHT` 픽셀을 사용하며, 게이트웨이는 **더 짧은 변**을 기준으로 해상도 티어를 선택하고 **가로세로 비율**을 지원되는 가장 가까운 비율로 맞춥니다:

| `size` 예시 | 결과 |
| - | - |
| `"854x480"` | 480p, 16:9 (측정된 출력 848×480) |
| `"1280x720"` | 720p, 16:9 (측정된 출력 1280×720) |
| `"720x1280"` | 720p, 9:16 (측정된 출력 720×1280) |
| `"1920x1080"` | 1080p, 16:9 (1.5 / 1.5-lite 전용) |

`"480p"` / `"720p"` / `"1080p"`를 직접 전달하거나, `size`을(를) 생략하고 xAI 기본 필드인 `resolution`(`480p` / `720p` / `1080p`) 및 `aspect_ratio`(예: `9:16`)을(를) 함께 보낼 수도 있습니다. 둘 다 제공된 경우 `resolution` / `aspect_ratio`이(가) 우선 적용됩니다. 둘 다 지정하지 않으면 동영상은 **480p**로 생성됩니다.

> [!WARNING]
>
> `grok-imagine-video`은(는) 480p / 720p만 지원하며, 1080p급 `size`은(는) `400`: `grok-imagine-video resolution must be one of 480p, 720p`을(를) 반환합니다.

### `seconds` (재생 시간)

문자열(`"5"`) 또는 숫자(`5`) 형태의 **1\~15** 사이의 정수이며, **기본값은 8**입니다. 범위를 벗어난 값은 `400`: `duration must be an integer between 1 and 15`을(를) 반환합니다. 비용은 초 단위에 비례하므로 테스트 시에는 1\~2초를 사용하는 것이 좋습니다.

### `input_reference` (이미지 투 비디오)

입력 이미지 1개를 전달하면 작업을 이미지 투 비디오로 전환할 수 있습니다. 다음 세 가지 형식 중 어느 것이든 사용할 수 있습니다:

* 공개 이미지 URL: `"input_reference": "https://example.com/first-frame.jpg"`
* base64 데이터 URI: `"input_reference": "data:image/jpeg;base64,/9j/4AAQ..."`
* Multipart 파일 업로드: `-F "input_reference=@first-frame.jpg"`

이미지 투 비디오의 경우 `prompt`을(를) 사용하여 움직임과 카메라 워크를 설명하십시오(예: “고양이가 천천히 고개를 돌린다”). **출력 프레임은 입력 이미지를 따릅니다**. 입력 이미지는 장당 \$0.002(`grok-imagine-video`) 또는 \$0.01(1.5 / 1.5-lite)의 추가 비용이 발생합니다.

## 모범 사례

**1. 1\~2초 및 480p로 prompt 테스트**

과금은 초 단위로 이루어지므로 720p / 1080p로 최종 길이를 렌더링하기 전에 짧은 저해상도 클립으로 결과물을 확인하십시오. `grok-imagine-video-1.5-lite`은(는) 480p / 720p 요율이 가장 낮아 대량 탐색 작업에 적합합니다.

**2. 항상 size 및 seconds 전달**

해당 값을 생략하면 480p 및 8초로 지정되며, 이는 “왜 이렇게 비싼가요” 및 “왜 이렇게 흐릿한가요”라는 의문이 생기는 가장 흔한 원인입니다.

**3. 전체 제한 시간을 설정하고 5\~10초마다 폴링**

작업은 일반적으로 20초에서 2분 이내에 완료됩니다. 더 빠르게 폴링하더라도 얻을 수 있는 이점이 없습니다. 전체 대기 시간은 최대 10분으로 제한하고, 시간 초과 시 문제 해결을 위해 작업 ID를 기록하십시오.

**4. 모더레이션 차단 처리**

상태 응답에서 `error.code`을(를) 확인하십시오. `moderation_blocked`은(는) 작업이 차단되었고 동영상이 없으며 과금되었음을 의미합니다. 그대로 재시도하기보다는 내용을 수정하여 다시 제출하십시오.

**5. 동영상 즉시 저장**

`/content`에서 작업이 `completed` 상태가 되는 즉시 다운로드하십시오. 다운로드 링크를 장기간 보관하거나 최종 사용자에게 제공하지 마십시오.

## 오류 코드 및 재시도

| HTTP / 필드 | 의미 | 조치 방법 |
| - | - | - |
| `400` `invalid_request_error` | 잘못된 매개변수: 지원되지 않는 해상도, 1–15 범위를 벗어난 `seconds` 등. `message`에 상세 내용이 표시됩니다 | 안내된 내용에 따라 수정하십시오. 재시도하지 마십시오 |
| `429` | 요청 제한에 도달했거나 잔액이 부족합니다 | 지수 백오프로 재시도하고 잔액을 확인하십시오 |
| `503` | Token에 `GrokOfficial` 그룹이 없거나 요청당 과금 방식을 사용 중입니다 | **서비스 장애가 아닌 권한 문제입니다** — [그룹 설정](#group-setup)을 참고하십시오 |
| `status: failed` | 생성이 실패했습니다 | `error.message`을 확인하고 수정한 후 다시 제출하십시오 |
| `completed` + `error.code: moderation_blocked` | 콘텐츠 검열에 의해 차단되었습니다. 동영상이 생성되지 않았으며 과금되었습니다 | 다시 제출하기 전에 prompt 또는 입력 이미지를 변경하십시오 |

## 자주 묻는 질문

> **모든 호출에서 503이 반환됩니다 — 채널에 장애가 발생했습니까?**
>
> 거의 확실하게 권한 문제입니다. Token 그룹에 `GrokOfficial`이(가) 없거나 Token의 과금 모드가 요청당 결제인 경우입니다. 전자의 경우 [그룹 설정](#group-setup)을 통해 신청하시고, 후자의 경우 과금 모드를 `Pay-as-you-go Priority` 또는 `Pay-as-you-go`(으)로 전환하십시오.

> **동영상이 왜 480p 및 8초로 생성됩니까?**
>
> 해당 설정은 기본값입니다. `size` 및 `seconds`을(를) 지정하지 않으면 작업이 480p, 8초 기준으로 생성되고 과금됩니다. `size`(예: `"1280x720"`) 및 `seconds`을(를) 명시적으로 전달하십시오.

> **작업이 완료되었다고 표시되는데 다운로드할 동영상이 없습니까?**
>
> 상태 응답에서 `error.code: "moderation_blocked"`을(를) 확인하십시오. 해당 항목이 있다면 xAI의 콘텐츠 검토 정책에 의해 동영상이 차단된 것입니다. 작업 상태는 여전히 `completed`(으)로 보고되지만 동영상이 제공되지 않으며, **과금도 진행됩니다**(xAI는 차단된 동영상에 대해서도 비용을 청구합니다). prompt나 입력 이미지를 조정한 후 다시 제출하십시오.

> **오디오를 제외하면 더 저렴합니까?**
>
> 아닙니다. 동영상에는 기본적으로 오디오 트랙이 포함되며, xAI의 가격 정책에 따라 오디오를 꺼도 가격이 낮아지지 않습니다.

> **이미지-투-비디오 결과물 크기가 전송한 이미지 크기와 일치하지 않는 이유는 무엇입니까?**
>
> 이미지-투-비디오는 입력 이미지의 프레임을 따릅니다. 특정 화면 비율을 원하시면 제출 전에 입력 이미지를 해당 비율로 자르십시오.

> **동영상 편집, 확장 또는 다중 참조 이미지가 지원됩니까?**
>
> 본 채널은 현재 **텍스트-투-비디오** 및 **단일 입력 이미지를 사용하는 이미지-투-비디오**만 지원합니다. 동영상 편집, 확장 등의 기능은 아직 지원되지 않으며, 추후 지원 시 본 페이지에 업데이트될 예정입니다.

> **세 가지 모델 중 어떤 것을 선택해야 합니까?**
>
> * 1080p 필요 시 → `grok-imagine-video-1.5` (최고 품질) 또는 `grok-imagine-video-1.5-lite` (더 저렴함)
> * 적은 예산으로 480p / 720p 대량 작업 시 → `grok-imagine-video-1.5-lite` (초당 \$0.02 / \$0.03)
> * 이미 기본 모델을 사용 중이며 480p / 720p만 필요한 경우 → `grok-imagine-video`

## 관련 문서

* [Grok Imagine 동영상 생성 API](/ko/api-capabilities/grok-imagine-video/video-generation) - Playground가 포함된 제출 엔드포인트 레퍼런스
* [Grok Imagine 공식 이미지](/ko/api-capabilities/grok-imagine-image-official/overview) - 동일 그룹, 티어별 xAI와 동일한 가격 책정
* [Grok 모델 가이드](/ko/api-capabilities/grok/overview) - xAI 텍스트 모델
* [충전 보너스](/ko/faq/recharge-promotions)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.