> ## 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/秒）。OpenAI Videos 互換。申請制の GrokOfficial グループが必要です。

## 概要

**Grok Imagine Video** は、xAI の動画モデル向けの**公式チャネル**です。リクエストは APIYI によって公式の xAI API へリレーされ、**価格は xAI の定価と同一**で、課金は生成された秒数と解像度に基づいて行われます。API は OpenAI Videos 互換の非同期タスクエンドポイント（`/v1/videos`）であり、**テキストからの動画生成**および**画像からの動画生成**をサポートし、すべての動画に音声トラックが付属します。

以下の3つのモデルが利用可能です：

* **`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](/ja/api-capabilities/grok-imagine-video/video-generation)**
>
> テキストからの動画生成 / 画像からの動画生成タスクを送信できます。インタラクティブな Playground も備えています。

> **[Grok Imagine 公式画像](/ja/api-capabilities/grok-imagine-image-official/overview)**
>
> 同じ `GrokOfficial` グループ — ティア別で xAI と同一価格の画像生成。

## AI エージェントに統合を任せる

このプロジェクトに Grok Imagine の動画生成（テキストから動画 + 画像から動画）を統合 / トラブルシューティングしてください。

コードを書く前にドキュメントをお読みください：このページのプレーンテキスト版を取得するには [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. モデルを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` のマルチパートでファイルをアップロードします。出力フレームは入力画像に追従します。

5. 課金：生成秒数 × 解像度ごとの秒単価に加え、画像から動画の場合は入力画像ごとに少額の手数料が発生します。音声をオフにしても価格は下がりません。

6. モデレーション：コンテンツモデレーションによってブロックされたタスクも `status` `completed` となりますが、動画は存在せず、レスポンスには `error.code: "moderation_blocked"` が含まれ、**課金も通常どおり発生します**。コード内でこのフィールドをチェックし、成功として扱わないようにし、同じプロンプトで無差別に再試行しないでください。

7. タスクが `completed` になるとすぐに動画をダウンロードできます。リンクを保持し続けるのではなく、直ちに独自のオブジェクトストレージへ保存してください。

8. キーは `APIYI_API_KEY` 環境変数から読み取り、base\_url として [https://api.apiyi.com/v1](https://api.apiyi.com/v1) を使用してください。決してハードコードしたり git にコミットしたりしないでください。完了したら、実際に2秒の 480p テキストから動画のジョブを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]
>
> **課金に関する注意事項と計算例**
>
> * **コスト = 秒数 × 1秒あたりの料金 + 入力画像数 × 1枚あたりの料金**。例：`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)を参照してください。
> * さらに[段階的なチャージボーナス](/ja/faq/recharge-promotions)が適用されます。大口の法人のお客様は、専用の価格設定についてセールス担当までお問い合わせいただけます。

## グループの設定

> [!WARNING]
>
> **Grok Imagine Videoは`Default`グループには含まれていません。** 本機能は[Grok Imagine公式画像](/ja/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点を記載してください。具体的であるほど、審査がスムーズに進みます。

**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]
>
> **コンプライアンスに関する注意事項**: アクセス権が付与された後、生成されたコンテンツに対する責任は呼び出し元に帰属します。現地の法規制を遵守し、違法なコンテンツ、他者の肖像権や知的財産権を侵害するコンテンツ、または未成年者に不適切なコンテンツを生成しないでください。一般消費者向けに配信する場合は、独自のモデレーション層を追加してください。背景情報：[海外モデル呼び出しに関するコンプライアンス注意事項](/ja/faq/overseas-model-compliance)。不正利用が確認された場合、グループへのアクセス権を取り消します。

## 技術仕様

| 項目 | 仕様 |
| - | - |
| モデルID | `grok-imagine-video`, `grok-imagine-video-1.5`, `grok-imagine-video-1.5-lite` |
| 機能 | テキストからの動画生成、画像からの動画生成（入力画像1枚） |
| 再生時間 | `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`。image-to-videoでは`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](/ja/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枚渡すことで、タスクを画像から動画生成（image-to-video）に切り替えることができます。以下の3つの形式のいずれも利用可能です：

* 公開画像URL: `"input_reference": "https://example.com/first-frame.jpg"`
* base64データURI: `"input_reference": "data:image/jpeg;base64,/9j/4AAQ..."`
* マルチパートファイルアップロード: `-F "input_reference=@first-frame.jpg"`

画像から動画生成では、動きやカメラワーク（「猫がゆっくりと頭を回す」など）を記述するために`prompt`を使用します。**出力フレームは入力画像に従います**。入力画像1枚につき、追加で\$0.002（`grok-imagine-video`）または\$0.01（1.5 / 1.5-lite）の費用がかかります。

## ベストプラクティス

**1. 1〜2秒かつ480pでプロンプトをテストする**

課金は秒単位で行われるため、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. 動画をすぐに保存する**

ジョブが`completed`になったら、速やかに`/content`からダウンロードしてください。ダウンロードリンクを長期間保持したり、エンドユーザーに直接渡したりしないでください。

## エラーコードとリトライ

| 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または入力画像を変更してください |

## FAQ

> **すべての呼び出しで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の価格設定では音声をオフにしても料金は下がりません。

> **Image-to-Videoの出力サイズが送信したサイズと一致しないのはなぜですか？**
>
> Image-to-Videoは入力画像のフレームに準拠します。特定のアスペクト比にしたい場合は、送信前に入力画像をその比率にトリミングしてください。

> **動画の編集、延長、または複数の参照画像には対応していますか？**
>
> 現在このチャンネルでは、**Text-to-Video**および**1枚の入力画像によるImage-to-Video**に対応しています。動画の編集や延長などの機能はまだ提供されていません。提供が開始され次第、このページを更新します。

> **3つのモデルのうち、どれを選ぶべきですか？**
>
> * 1080pが必要な場合 → `grok-imagine-video-1.5`（最高品質）または`grok-imagine-video-1.5-lite`（より安価）
> * 予算を抑えて480p / 720pを一括生成したい場合 → `grok-imagine-video-1.5-lite`（1秒あたり\$0.02 / \$0.03）
> * すでにベースモデルを利用中で、480p / 720pのみが必要な場合 → `grok-imagine-video`

## 関連ドキュメント

* [Grok Imagine 動画生成 API](/ja/api-capabilities/grok-imagine-video/video-generation) - Playground付きの送信エンドポイントリファレンス
* [Grok Imagine 公式画像](/ja/api-capabilities/grok-imagine-image-official/overview) - 同一グループ、ティアごとにxAIと同じ価格設定
* [Grok モデルガイド](/ja/api-capabilities/grok/overview) - xAI テキストモデル
* [チャージボーナス](/ja/faq/recharge-promotions)


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