> ## 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の概要 - グループ設定](/ja/api-capabilities/grok-imagine-video/overview#group-setup)を参照してください。

> [!NOTE]
>
> 右側のインタラクティブなPlaygroundを使用すると、エンドポイントを直接テストできます。**Authorization**にAPI Keyを入力し（形式: `Bearer sk-xxx`）、`model`を選択して、`prompt` / `seconds` / `size`を入力して送信します。画像から動画への生成には`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ファイル |

**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)。

## レスポンス例

**送信（ステップ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 Video 概要](/ja/api-capabilities/grok-imagine-video/overview) - 料金、グループ適用、パラメータ、FAQ
* [Grok Imagine 公式画像](/ja/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.