> ## 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 동영상 생성 API 레퍼런스

> Grok Imagine 동영상 생성 API 레퍼런스 및 실시간 테스트 — 텍스트-동영상 / 이미지-동영상, 비동기 3단계 프로세스, 1~15초, 480p / 720p / 1080p, xAI와 동일한 초당 요금 책정

> [!WARNING]
>
> **🔒 신청 시 부여되는 `GrokOfficial` 그룹 필요**: Grok Imagine Video는 `Default` 그룹에 속하지 않으므로 호출하기 전에(이 페이지의 Playground 포함) 접근 권한을 신청해야 합니다. 접근 권한이 없거나 요청당 결제 Token을 사용하는 경우 모든 호출에서 `503`이(가) 반환됩니다. [Grok Imagine Video 개요 - 그룹 설정](/ko/api-capabilities/grok-imagine-video/overview#group-setup)을 참고하십시오.

> [!NOTE]
>
> 오른쪽의 대화형 Playground를 통해 엔드포인트를 직접 테스트할 수 있습니다. **Authorization**에 API Key를 입력하고(형식: `Bearer sk-xxx`), `model`을(를) 선택한 후 `prompt` / `seconds` / `size`을(를) 입력하고 전송하십시오. 이미지 투 비디오(image-to-video)의 경우 `input_reference`을(를) 추가하십시오. **Playground는 1단계(제출)만 수행합니다** — 태스크 `id`을(를) 받은 후 아래 설명에 따라 폴링 및 다운로드를 진행하십시오.

> [!WARNING]
>
> **⚠️ 가장 흔히 발생하는 3가지 주의점**
>
> 1. **`size` / `seconds`이(가) 없으면 기본값은 480p 및 8초이며**, 해당 기준에 따라 과금됩니다.
> 2. **`grok-imagine-video`에는 1080p가 없습니다**: `1920x1080`은(는) 400을 반환하므로, 1080p를 사용하려면 `-1.5` 또는 `-1.5-lite`을(를) 사용하십시오.
> 3. **검토 차단 시에도 과금됩니다**: 차단된 태스크도 여전히 `completed`을(를) 보고하지만, `error.code: "moderation_blocked"`을(를) 포함하며 동영상이 없습니다.

> [!WARNING]
>
> **3단계 비동기 흐름 — 이 페이지에서는 1단계(제출)만 다룹니다**
>
> * **1단계(이 페이지)**: `POST /v1/videos` → 태스크 `id` + `status: "queued"` 반환
> * **2단계**: `status`이(가) `"completed"` 또는 `"failed"`이(가) 될 때까지 `GET /v1/videos/{id}` 폴링
> * **3단계**: `GET /v1/videos/{id}/content`에서 MP4 다운로드
>
> 제출 요청은 몇 초 내에 반환되며 동영상 생성이 완료될 때까지 대기하지 **않습니다**.

## 코드 예제

### Python (텍스트-동영상, 3단계 전체)

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

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

# Step 1: submit
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "grok-imagine-video-1.5",
    "prompt": "A lighthouse on the coast at dusk, slow push-in, waves lapping the rocks, seabirds calling, cinematic lighting",
    "seconds": "5",
    "size": "1280x720",      # 720p landscape; the default without it is 480p
}, timeout=60).json()
vid = task["id"]

# Step 2: poll
for _ in range(75):           # about 10 minutes at most
    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"] != "completed" or job.get("error"):
    # moderation_blocked: blocked by moderation, no video, but billed
    raise RuntimeError(job.get("error"))

# Step 3: download and store right away
mp4 = requests.get(f"{BASE}/videos/{vid}/content", headers=H, timeout=300)
open("out.mp4", "wb").write(mp4.content)
```

### Python (이미지-동영상, base64 입력 이미지)

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

H = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}
img = base64.b64encode(open("first-frame.jpg", "rb").read()).decode()

task = requests.post("https://api.apiyi.com/v1/videos", headers=H, json={
    "model": "grok-imagine-video",
    "prompt": "the cat slowly turns its head and blinks",
    "seconds": "3",
    "input_reference": f"data:image/jpeg;base64,{img}",   # a public image URL works too
}, timeout=60).json()
print(task["id"])  # then poll and download as above; the output frame follows the input image
```

### cURL

```bash theme={null}
# Step 1: submit text-to-video (1.5-lite, 2 seconds at 480p)
curl -X POST "https://api.apiyi.com/v1/videos" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5-lite",
    "prompt": "a red paper boat drifting on a calm lake, gentle ripples",
    "seconds": "2",
    "size": "854x480"
  }'

# Image-to-video can also upload a local file with multipart
curl -X POST "https://api.apiyi.com/v1/videos" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=grok-imagine-video" \
  -F "prompt=the cat slowly turns its head" \
  -F "seconds=2" \
  -F "input_reference=@first-frame.jpg"

# Step 2: check status
curl "https://api.apiyi.com/v1/videos/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-your-api-key"

# Step 3: download the video
curl -o out.mp4 "https://api.apiyi.com/v1/videos/task_xxxxxxxx/content" \
  -H "Authorization: Bearer sk-your-api-key"
```

### Node.js (fetch)

```javascript theme={null}
import fs from 'node:fs';

const BASE = 'https://api.apiyi.com/v1';
const H = { 'Authorization': `Bearer ${process.env.APIYI_API_KEY}`, 'Content-Type': 'application/json' };

const task = await fetch(`${BASE}/videos`, {
    method: 'POST',
    headers: H,
    body: JSON.stringify({
        model: 'grok-imagine-video-1.5-lite',
        prompt: 'A serene Japanese garden with cherry blossoms drifting, koi pond, golden hour',
        seconds: '4',
        size: '720x1280'          // 720p portrait
    })
}).then(r => r.json());

let job;
for (let i = 0; i < 75; i++) {
    await new Promise(r => setTimeout(r, 8000));
    job = await fetch(`${BASE}/videos/${task.id}`, { headers: H }).then(r => r.json());
    if (['completed', 'failed'].includes(job.status)) break;
}
if (job.status !== 'completed' || job.error) throw new Error(JSON.stringify(job.error));

const mp4 = await fetch(`${BASE}/videos/${task.id}/content`, { headers: H });
fs.writeFileSync('out.mp4', Buffer.from(await mp4.arrayBuffer()));
```

## 파라미터 빠른 참조

| 파라미터 | 타입 | 필수 여부 | 기본값 | 설명 |
| - | - | - | - | - |
| `model` | string | ✅ | — | `grok-imagine-video` / `grok-imagine-video-1.5` / `grok-imagine-video-1.5-lite` |
| `prompt` | string | 텍스트 기반 동영상 생성 시 필수 | — | 장면, 피사체, 동작, 카메라, 조명 등이며, 이미지 기반 동영상 생성 시에는 움직임을 설명합니다 |
| `seconds` | string / integer | ❌ | `8` | 1\~15초이며, 범위를 벗어나면 400을 반환합니다 |
| `size` | string | ❌ | 480p | `WIDTHxHEIGHT` 픽셀 단위입니다. 짧은 변을 기준으로 해상도가 설정되며 가장 가까운 화면비로 자동 조정됩니다. `480p` / `720p` / `1080p`도 사용할 수 있습니다 |
| `resolution` / `aspect_ratio` | string | ❌ | — | xAI 고유 필드입니다. `size`와 함께 전송될 경우 이 필드가 우선 적용됩니다 |
| `input_reference` | string / file | ❌ | — | 이미지 기반 동영상 생성을 위한 입력 이미지: 공개 URL, data URI 또는 multipart 파일 |

**초당 가격** (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).

## 응답 예시

**제출 (1단계)**:

```json theme={null}
{
  "id": "task_xxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "grok-imagine-video-1.5-lite",
  "status": "queued",
  "progress": 0,
  "created_at": 1792320668
}
```

**완료 (2단계 폴링 결과)**:

```json theme={null}
{
  "id": "task_xxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "grok-imagine-video-1.5-lite",
  "status": "completed",
  "progress": 100,
  "seconds": "2",
  "created_at": 1792320668,
  "completed_at": 1792320715
}
```

**모더레이션에 의해 차단됨**: `status`은(는) 여전히 `completed`이지만, 추가 `error` 필드가 존재하며 다운로드할 동영상이 없습니다:

```json theme={null}
{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "completed",
  "error": { "code": "moderation_blocked", "message": "..." }
}
```

## 관련 문서

* [Grok Imagine 동영상 개요](/ko/api-capabilities/grok-imagine-video/overview) - 요금, 그룹 신청, 파라미터, FAQ
* [Grok Imagine 공식 이미지](/ko/api-capabilities/grok-imagine-image-official/overview) - 동일 그룹 내 이미지 생성


## OpenAPI

````yaml api-reference/grok-imagine-video-openapi-en.yaml POST /v1/videos
openapi: 3.1.0
info:
  title: Grok Imagine Video Generation API
  description: >
    xAI Grok Imagine video official channel — an OpenAI Videos-compatible async
    task API for text-to-video and image-to-video, priced the same as xAI per
    second.


    - Three models: `grok-imagine-video` (480p \$0.05/s, 720p \$0.07/s),
    `grok-imagine-video-1.5` (\$0.08 / \$0.14 / \$0.25 per second),
    `grok-imagine-video-1.5-lite` (\$0.02 / \$0.03 / \$0.14 per second)

    - `seconds` 1–15, **default 8**; without `size` the **default is 480p**

    - Image-to-video: add `input_reference` (image URL or base64 data URI); each
    input image costs an extra \$0.002 (video) / \$0.01 (1.5 / lite)

    - **Async task endpoint**: this call only submits; poll `GET
    /v1/videos/{id}` and download from `GET /v1/videos/{id}/content`

    - A task blocked by moderation still reports `completed` with `error.code:
    moderation_blocked`, has no video, and is billed


    **Authentication**: add `Authorization: Bearer YOUR_API_KEY` to the request
    headers


    **API Key setup**: the Token group must include **`GrokOfficial`** (granted
    on application) with billing mode **Pay-as-you-go Priority** or
    **Pay-as-you-go**; without access, or with a pay-per-request Token, calls
    return 503


    **Get an API Key**: create a Token in the [APIYI
    console](https://api.apiyi.com/token)
  version: 1.0.0
servers:
  - url: https://api.apiyi.com
    description: Primary endpoint
security:
  - bearerAuth: []
paths:
  /v1/videos:
    post:
      tags:
        - Video Generation
      summary: Submit a video generation task (text-to-video / image-to-video)
      description: >
        Submit a Grok Imagine video generation task (async); returns the task
        `id` and `status: "queued"`.


        - Required: `model`; text-to-video also needs `prompt`

        - Optional: `seconds` (default 8), `size` (default 480p),
        `input_reference` (makes it image-to-video)

        - **The response has no video**; poll `GET /v1/videos/{id}` until
        `status: "completed"`, then download the MP4 from `GET
        /v1/videos/{id}/content`

        - Typical time: about 20–25 s for 2 s at 480p, 35–50 s for
        image-to-video, about 110 s for 1080p on 1.5
      operationId: generateGrokImagineVideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrokImagineVideoRequest'
            example:
              model: grok-imagine-video-1.5-lite
              prompt: >-
                a red paper boat drifting on a calm lake, gentle ripples, soft
                morning light
              seconds: '2'
              size: 854x480
      responses:
        '200':
          description: Task submitted; returns the task id and queued status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrokImagineVideoTask'
        '400':
          description: >-
            Invalid parameters (resolution not supported by the model, seconds
            outside 1–15, missing prompt, etc.); `message` explains
        '401':
          description: Unauthorized - invalid API Key
        '429':
          description: Rate limit hit or insufficient balance
        '503':
          description: >-
            Token lacks the `GrokOfficial` group, or uses pay-per-request
            billing
      security:
        - bearerAuth: []
components:
  schemas:
    GrokImagineVideoRequest:
      type: object
      required:
        - model
      properties:
        model:
          type: string
          description: >
            Model ID (billed per second × resolution rate):

            - `grok-imagine-video` — 480p \$0.05/s, 720p \$0.07/s, **no 1080p**

            - `grok-imagine-video-1.5` — 480p \$0.08, 720p \$0.14, 1080p \$0.25
            per second

            - `grok-imagine-video-1.5-lite` — 480p \$0.02, 720p \$0.03, 1080p
            \$0.14 per second
          enum:
            - grok-imagine-video
            - grok-imagine-video-1.5
            - grok-imagine-video-1.5-lite
          default: grok-imagine-video-1.5-lite
        prompt:
          type: string
          description: >-
            Prompt: scene + subject + action + camera + lighting. Required for
            text-to-video; for image-to-video it describes motion and camera
          example: >-
            a red paper boat drifting on a calm lake, gentle ripples, soft
            morning light
        seconds:
          type: string
          description: >
            Duration from 1 to 15 seconds, as a string or a number; **default
            8**. Out-of-range values return 400. Cost scales with seconds — use
            1–2 seconds while testing.
          example: '2'
        size:
          type: string
          description: >
            Output size in `WIDTHxHEIGHT` pixels: the **shorter side** sets the
            resolution (≥1080 is 1080p, ≥720 is 720p, otherwise 480p) and the
            aspect ratio snaps to the nearest supported one.

            You can also pass `480p` / `720p` / `1080p` directly. **Without it,
            the default is 480p.**


            - `854x480` — 480p landscape (measured 848×480)

            - `1280x720` / `720x1280` — 720p landscape / portrait

            - `1920x1080` / `1080x1920` — 1080p (1.5 / 1.5-lite only)
          enum:
            - 854x480
            - 480x854
            - 1280x720
            - 720x1280
            - 1920x1080
            - 1080x1920
          default: 854x480
        input_reference:
          type: string
          description: >
            Input image for image-to-video: a public image URL or a
            `data:image/jpeg;base64,...` data URI. Passing it makes the job
            image-to-video, and the output frame follows the input image.

            Each input image costs an extra \$0.002 (`grok-imagine-video`) or
            \$0.01 (1.5 / 1.5-lite).
          example: https://example.com/first-frame.jpg
    GrokImagineVideoTask:
      type: object
      properties:
        id:
          type: string
          description: Task ID for polling and download
          example: task_xxxxxxxxxxxxxxxx
        object:
          type: string
          description: Always `video`
          example: video
        model:
          type: string
          example: grok-imagine-video-1.5-lite
        status:
          type: string
          description: >
            Task status:

            - `queued` — submitted, waiting

            - `in_progress` — generating

            - `completed` — done, download from `/v1/videos/{id}/content`; with
            `error.code: moderation_blocked` it was blocked and has no video

            - `failed` — failed
          enum:
            - queued
            - in_progress
            - completed
            - failed
          example: queued
        progress:
          type: integer
          description: >-
            Progress 0–100, coarse-grained; not suitable for a precise progress
            bar
          example: 0
        seconds:
          type: string
          description: Video duration, returned once done
        created_at:
          type: integer
          description: Task creation Unix timestamp (seconds)
        completed_at:
          type: integer
          description: Task completion Unix timestamp (seconds), returned once done
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API Key from the APIYI console (Token group must include GrokOfficial)

````

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