> ## 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におけるGrok Imagine公式チャネルの完全ガイド：grok-imagine-image / grok-imagine-image-quality / grok-imagine-image-2.0。xAIと同価格で、解像度（1k / 1.5k / 2k）および品質ティア（low / medium）に応じて課金され、画像1枚あたり$0.02〜0.08です。利用には申請制のGrokOfficialグループが必要です。

## 概要

**Grok Imagine Official**は、xAIの画像モデル向けの**公式チャンネル**です。リクエストはAPIYIによって公式xAI APIへリレーされ、**価格はxAIの定価と一致**し、課金は解像度と品質ティアに従い、パラメータ検証はアップストリームと同一です。

利用可能なモデルは、標準の`grok-imagine-image`、高品質な`grok-imagine-image-quality`、そして最新の\*\*`grok-imagine-image-2.0`\*\*（`low` / `medium`品質ティアあり）の3つです。

> [!WARNING]
>
> **🔒 このチャンネルには`GrokOfficial`グループが必要であり、申請制で提供されます**
>
> Grok Imagine Officialは`Default`グループには含まれていません。このファミリのコンテンツ安全性ポリシーはプラットフォーム上の他のモデルと大きく異なるため、コンプライアンスリスクを抑制する目的で、アクセス権は**限定的**に付与しています：
>
> * **累計利用額が\$1,000以上の既存のお客様**：サポートにお問い合わせの上、ユースケースをご説明いただければ、確認後に有効化いたします
> * **その他すべてのお客様**：[WeComサポート](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec)から申請し、**ユースケース**と**コンテンツモデレーション対策**をご説明ください。承認後に有効化いたします
>
> `GrokOfficial`グループのないTokenでは\*\*`503`\*\*が返されます — これは障害ではなく、権限の問題です。詳細は下記の[グループ設定](#group-setup)をご覧ください。

> [!TIP]
>
> **公式かリバースか？** 本ページは公式チャンネルです。価格はxAIと同一で、ティアごとに課金され、`grok-imagine-image-2.0`を含み、**現在はテキストからの画像生成のみに対応しており、1回の呼び出しにつき1画像となります**。**画像編集や1回の呼び出しでの複数画像生成**、または解像度を問わない低額の一律料金（1画像あたり\$0.02 / \$0.045）が必要な場合は、[Grok Imagine Reverse](/ja/api-capabilities/grok-imagine-image/overview)をご利用ください。比較の詳細は[公式とリバースの比較](#official-vs-reverse)をご覧ください。

> [!NOTE]
>
> すべての画像APIは**同期式**です。非同期タスクIDは存在しないため、クライアントが切断された場合、結果は失われますがリクエストの課金は発生します。当社のテストでは、`grok-imagine-image-2.0`の`medium`品質および2Kでの生成には約60〜80秒かかりますので、このモデルには長めのタイムアウト時間を設定してください。詳細は[画像APIの注意事項とベストプラクティス](/ja/api-capabilities/image-api-best-practices)をご覧ください。

> **[テキスト画像生成 API](/ja/api-capabilities/grok-imagine-image-official/text-to-image)**
>
> テキストpromptから画像を生成します。対話型のPlaygroundも用意されています。

> **[Grok Imagine Video](/ja/api-capabilities/grok-imagine-video/overview)**
>
> 同じ`GrokOfficial`グループ — テキストからの動画生成および画像からの動画生成に対応し、秒単位で課金されます。

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

このプロジェクトにGrok Imagine Officialのtext-to-imageを統合／トラブルシューティングしてください。

コードを書く前にドキュメントを読んでください：このページのプレーンテキスト版を取得するには [https://docs.apiyi.com/en/api-capabilities/grok-imagine-image-official/overview.md](https://docs.apiyi.com/en/api-capabilities/grok-imagine-image-official/overview.md) を取得してください。パラメータの詳細については、同様にtext-to-imageページのURLに`.md`を追加してください。

要件：

1. モデルを1つ選択してください：`grok-imagine-image`（標準）、`grok-imagine-image-quality`（高品質）、または`grok-imagine-image-2.0`（より新しく、2つの`quality`ティアあり）。tokenグループには`GrokOfficial`が含まれている必要があり、そうでない場合はすべての呼び出しが503を返します。

2. タイムアウト：安全マージンとしてクライアントのタイムアウトを360秒に設定してください。`grok-imagine-image`は約8秒、`-quality`は約7〜12秒かかりますが、`grok-imagine-image-2.0`を`medium`および2Kで実行した場合は60〜80秒かかります。画像APIは同期処理です。クライアントが切断された場合、結果は失われますが、リクエストの課金は発生します。リバースプロキシ、ゲートウェイ、サーバーレスランタイムの制限も引き上げてください。

3. エンドポイント：text-to-imageには`/v1/images/generations`（JSON）のみを使用してください。**このエンドポイントに参照画像を送信しないでください**（`image` / `image_url`など）— これらは警告なしに破棄されます。このチャンネルではまだ画像編集を提供していません。編集には`/en/api-capabilities/grok-imagine-image/overview`のリバースチャンネルを使用してください。

4. サイズ：出力は`resolution`（`1k` / `1.5k` / `2k`、小文字）と`aspect_ratio`（例：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`）で制御してください。**`size`は送信しないでください** — 解像度ティアにマッピングされていないため、画像はデフォルトの1kで出力されます。許可されたセット以外の値を指定すると、警告なしのフォールバックは行われず、422が返されます。

5. 品質：`grok-imagine-image-2.0`のみが`quality`を持ちます。`low`（デフォルト）または`medium`のみを送信し、`auto`や`high`は決して送信しないでください（`high`は400を返します）。他の2つのモデルには`quality`は不要です — 忠実度を選択するにはモデルを選んでください。

6. 生成数：常に`n` = 1を送信してください。複数枚の画像が必要な場合は、`n`を使用するのではなく、複数のリクエストを並行して送信してください。

7. レスポンス処理：デフォルトは`url`ですが、`response_format: "b64_json"`を送信することもできます。URLを使用する場合は、リンクを保持するのではなく、すぐにサーバーへ画像をダウンロードして保存してください。`usage`フィールドはプレースホルダーであり（`prompt_tokens`は常に画像数の1000倍になります）、**照合には使用できません** — コンソールの課金記録を確認してください。

8. `APIYI_API_KEY`環境変数からキーを読み取り、base\_urlとして[https://api.apiyi.com/v1](https://api.apiyi.com/v1) を使用してください。決してハードコードしたり、gitにコミットしたりしないでください。完了したら、実際にtext-to-imageの呼び出しを1回実行し、その出力とその呼び出しにかかった費用を表示してください。

## モデルと料金

料金はxAIの定価に準拠しており、**画像ごと**に課金されます。階層は`resolution`（2.0の場合はさらに`quality`）によって設定されます：

| モデル | 品質ティア | `1k` | `1.5k` | `2k` |
| - | - | - | - | - |
| **`grok-imagine-image`** | — | \$0.02 | \$0.02 | \$0.02 |
| **`grok-imagine-image-quality`** | — | \$0.05 | \$0.06 | \$0.07 |
| **`grok-imagine-image-2.0`** | `low`（デフォルト） | \$0.04 | \$0.05 | \$0.06 |
| **`grok-imagine-image-2.0`** | `medium` | \$0.06 | \$0.07 | \$0.08 |

> [!NOTE]
>
> モデルの料金は公式サイトに準拠しており、公式サイトの変更に伴って改定される場合があります。上記の表は参考用であり、トップナビゲーションの**モデル料金**タブの情報が正式なものとなります：[モデル料金](/en/models/index)。

> [!NOTE]
>
> **課金に関する注記**
>
> * **デフォルト値**：`resolution`のデフォルトは`1k`です。`grok-imagine-image-2.0`のデフォルトは`quality: low`であり、画像1枚あたり\$0.04となります。
> * **画像ごと、1回の呼び出しにつき1枚**：このチャネルでは`n=1`のまま維持し、さらに画像が必要な場合は並行して呼び出してください。
> * **失敗したリクエストは課金されません**：パラメータエラー（422 / 400）、グループ権限の不足（503）、その他のエラーレスポンスは無料です。
> * **`usage`との照合は行わないでください**：`prompt_tokens`は常にプレースホルダーである`1000 × image count`となります。コンソールの課金記録が正式なものとなります。
> * さらに[段階制チャージボーナス](/ja/faq/recharge-promotions)が適用されます。大量利用の法人のお客様は、専用料金について営業担当までお問い合わせください。

## 公式 vs リバース

APIYIはGrok Imagine向けに公式チャンネルとリバースチャンネルの両方を提供しています。**これらはグループ、課金、および機能面で異なります**:

| 項目 | **公式**（本ページ） | [**リバース**](/ja/api-capabilities/grok-imagine-image/overview) |
| - | - | - |
| グループ | `GrokOfficial`（申請制） | `Grok_imagine_Reverse`（申請制） |
| 課金 | **xAIの定価と同等**、解像度 × 品質ティアによる従量課金 | 解像度に関係なく、画像1枚あたりの定額制 |
| モデル | `grok-imagine-image` / `-quality` / **`-2.0`** | `grok-imagine-image` / `-quality` |
| 解像度ティア | `1k` / `1.5k` / `2k` | `1k` / `2k` |
| テキストからの画像生成 | ✅ | ✅ |
| 画像編集 / 複数画像の融合 | 未提供 | ✅ 1〜4枚の参照画像 |
| 1回のリクエストでの複数画像生成 | 未提供（`n=1`） | ✅ `n` 最大10枚 |
| パラメータ検証 | **厳格**: 範囲外の値は422を返却 | 寛容: 無効な値は通知なくデフォルトにフォールバック |

> [!TIP]
>
> **選び方**: `grok-imagine-image-2.0`が必要な場合、xAI独自の条件での課金を希望する場合、またはタイポに対して明示的にエラーを返したい場合 → 公式。画像編集、1回のリクエストでの複数画像生成、または2K出力に対する最安価格を求める場合 → リバース。両方のグループを保持し、それぞれ独自のTokenで呼び出すことも可能です。

## グループの設定

> [!WARNING]
>
> **Grok Imagine Official は `Default` グループには含まれていません。** 本機能は **`GrokOfficial` グループ（xAI と同価格、上記の表を参照）** に属しており、アクセス申請が必要です。

### 利用可能な対象

| お客様の種別 | アクセス権の取得方法 |
| - | - |
| **累計利用額が \$1,000 以上のお客様** | ユースケースを添えてサポートへご連絡ください。確認後に有効化されます |
| **その他のお客様** | ユースケースおよびコンテンツモデレーション対策を添えて申請してください。承認後に有効化されます |

### 申請手順

**1. WeCom サポートへの連絡**

[WeCom サポート](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec) またはメール（[hi@apiyi.com](mailto:hi@apiyi.com)）にて申請してください。**`GrokOfficial`（Grok Imagine Official）** の申請である旨をお知らせください。

**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-image`, `grok-imagine-image-quality`, `grok-imagine-image-2.0` |
| エンドポイント | `POST /v1/images/generations` (`application/json`) |
| 解像度ティア | `1k`（デフォルト）/ `1.5k` / `2k` |
| アスペクト比 | 一般的: `1:1`（デフォルト）/ `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3` |
| 品質ティア | `grok-imagine-image-2.0` のみ: `low`（デフォルト）/ `medium` |
| 1回あたりの生成画像数 | `n=1` |
| レスポンス形式 | `url`（デフォルト）または `b64_json` |
| パラメータ検証 | 厳格 — 範囲外の `resolution` / `aspect_ratio` は 422 を返します |
| レイテンシ | `grok-imagine-image` は約8秒、`-quality` は 1k で約7秒・2k で約12秒、`-2.0` `low` は約15〜17秒、`medium` 2K は約60〜80秒 |
| 推奨クライアントタイムアウト | ≥ 360秒 |

## 主要パラメータ

### `resolution` および `aspect_ratio`（出力サイズ）

これらは組み合わさって出力ピクセル数を決定します。いくつかの実測結果は以下のとおりです：

| モデル | リクエスト | 実際の出力 |
| - | - | - |
| `grok-imagine-image` | `1k` + `3:2` | 1248×832 (JPEG) |
| `grok-imagine-image-quality` | `2k` + `9:16` | 1584×2816 (PNG、約6.7 MB) |
| `grok-imagine-image-2.0` | `1.5k` + `16:9` + `medium` | 1792×1008 |

> [!WARNING]
>
> **`size` ではなく `resolution` を使用してください**
>
> このチャネルでは、OpenAI スタイルの `size`（`"2048x2048"` など）が解像度ティアにマッピングされません。`size` を渡してもエラーは発生しませんが、画像はデフォルトの `1k` で生成され課金されます。2K の場合は、明示的に `resolution: "2k"` を渡してください。

> [!NOTE]
>
> **誤りは明確にエラーになります**: 逆方向のチャネルとは異なり、ここでのパラメータ検証は xAI に準拠しています。`resolution: "4k"` や `aspect_ratio: "5:7"` などの範囲外の値は **422** を返し、課金されません。422 が返された場合は、まずこれら2つのパラメータのスペルを確認してください（すべて小文字: `1k` / `1.5k` / `2k`）。

### `quality`（`grok-imagine-image-2.0` のみ）

| 値 | 説明 |
| - | - |
| `low` | デフォルト、より高速 |
| `medium` | より高忠実度、画像1枚あたり \$0.02 追加、2Kで約60〜80秒 |

`high` を渡すと 400（`This model only supports the following quality value(s): low, medium, auto`）が返されます。**`low` または `medium` のみを送信してください** — `auto` は送信しないでください。`grok-imagine-image` および `grok-imagine-image-quality` は `quality` を受け取らず、モデル自体が忠実度を設定します。

### `n`（画像枚数）

このチャネルでは**常に `n=1` を送信してください**。一度に複数の画像を生成する場合は、複数のリクエストを並行して送信してください。レイテンシは安定しているため、同時実行数は線形にスケールします。

## ベストプラクティス

**1. 1kで探索し、2kで仕上げる**

方向性を決めるために`1k`でpromptを数回実行し、その後`2k`で最終レンダリングを行います。`grok-imagine-image-2.0`を`medium`かつ2Kで実行すると1分以上かかるため、試行錯誤には不向きです。

**2. クライアントのタイムアウトを360秒に設定する**

画像APIは同期型です。タイムアウトが60秒の場合、2.0 `medium`で多くの誤ったタイムアウトが発生する原因となり、クライアント側で切断されたリクエストも課金されます。

**3. 構図にはpromptではなくaspect\_ratioを使用する**

このパラメーターは実際に反映されます。promptに「横構図」と記述するよりも、`aspect_ratio: "16:9"`を使用する方がはるかに確実です。

**4. URLの結果をすぐに保存する**

返却された画像リンクは、サーバー上ですぐに独自のストレージへダウンロードしてください。リンクを直接参照し続けたり、エンドユーザーにそのまま渡したりしないでください。

**5. 編集にはリバースチャンネルに切り替える**

このチャンネルではまだ画像編集を提供していません。参照画像を基にした編集や複数画像の合成には、`/v1/images/edits`を[Grok Imagine Reverse](/ja/api-capabilities/grok-imagine-image/overview)で使用してください。

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

| HTTP | 意味 | 対処方法 |
| - | - | - |
| `400` | 無効な`quality`（`high`など）。メッセージに許可されている値が一覧表示されます | `low` / `medium`に変更してください。リトライはしないでください |
| `422` | 許可されたセット外の`resolution` / `aspect_ratio` | スペルと大文字・小文字を確認してください。リトライはしないでください |
| `429` | レート制限への到達または残高不足 | 指数バックオフを用いてリトライし、残高を確認してください |
| `503` | Tokenに`GrokOfficial`グループがないか、Tokenがリクエスト単位の課金を使用しています | **権限の問題であり、サービス障害ではありません** — リトライしても解決しません。[グループ設定](#group-setup)を参照してください |

> [!NOTE]
>
> **クライアント側へのアドバイス**: `400` / `422`は確定的なエラーです — リトライしても無意味なため、代わりにアラートを発報してください。リトライする価値があるのは`429`およびネットワークレベルのタイムアウトのみで、指数バックオフを用いて最大3回まで試行してください。エラーレスポンスは課金されません。

## FAQ

> **すべての呼び出しが503を返します — チャンネルがダウンしていますか？**
>
> ほぼ確実に権限の問題です。2つの可能性があります：
>
> 1. **Tokenグループに`GrokOfficial`がない**: このチャンネルは申請に基づいて付与されます。[グループ設定](#group-setup)を参照してください。
> 2. **Tokenの課金モードがリクエスト課金になっている**: このチャンネルは従量課金制であり、リクエスト課金のTokenからはルーティングできません。課金モードを`Pay-as-you-go Priority`または`Pay-as-you-go`に切り替えてください。

> **size: 2048x2048 を渡しましたが — なぜ出力が依然として1Kなのですか？**
>
> このチャンネルは`size`を解像度階層にマッピングしないため、画像はデフォルトの`1k`で生成および課金されます。代わりに`resolution: "2k"`を使用し、`aspect_ratio`でフレーミングを制御してください。

> **画像の編集や、参照画像の受け渡しはできますか？**
>
> このチャンネルは**現在画像編集を提供していません**。`/v1/images/generations`に参照画像を送信してもエラーは発生しませんが、参照画像は無視され、promptのみから新しい画像が生成されます。
>
> 編集や複数画像の合成を行うには、[Grok Imagine Reverse](/ja/api-capabilities/grok-imagine-image/overview)へのアクセスを取得してください。こちらの`/v1/images/edits`では1〜4枚の参照画像を受け付けることができます。

> **なぜ n=1 なのですか？一度に複数の画像を取得するにはどうすればよいですか？**
>
> このチャンネルは現在、単一画像の出力のみを提供しています。複数の画像を取得するには、それぞれ`n=1`を指定して複数のリクエストを並行して送信してください。ワークフロー上、1回の呼び出しで複数の画像がどうしても必要な場合は、[Grok Imagine Reverse](/ja/api-capabilities/grok-imagine-image/overview)（`n`最大10件）をご利用ください。

> **grok-imagine-image-2.0 は他の2つとどのように異なりますか？**
>
> `grok-imagine-image-2.0`はxAIのより新しい画像モデルであり、`quality`階層（`low` / `medium`）が追加されています。`medium`はより詳細な描写が可能ですが、低速です（2Kで約60〜80秒）。`grok-imagine-image`は最も安価で、どの解像度でも料金は均一です。`grok-imagine-image-quality`は解像度ごとの階層型価格設定により、より高い忠実度を提供します。
>
> まずはパイプラインを`grok-imagine-image`または2.0 `low`で動作させ、品質の必要性に応じて上位階層に移行してください。

> **請求内容をusageのtoken数と照合することはできますか？**
>
> **できません。** `usage.prompt_tokens`は常に`1000 × image count`であり、実際の課金とは関係のないプレースホルダーです。このチャンネルは解像度と品質階層に応じて画像ごとに課金されます。コンソールの課金記録が正式なものとなります。

> **公式のOpenAI SDKを使用できますか？**
>
> はい。エンドポイントはOpenAI Images APIと互換性があります。`base_url`を`https://api.apiyi.com/v1`に指定し、非標準フィールドは`extra_body`に入れてください：
>
> ```python theme={null}
> from openai import OpenAI
> client = OpenAI(api_key="sk-your-api-key", base_url="https://api.apiyi.com/v1")
>
> resp = client.images.generate(
>     model="grok-imagine-image-2.0",
>     prompt="a red wooden boat on an alpine lake at dawn",
>     n=1,
>     extra_body={"resolution": "2k", "aspect_ratio": "16:9", "quality": "medium"},
>     timeout=360,
> )
> print(resp.data[0].url)
> ```

## 関連ドキュメント

* [Grok Imagine 公式テキスト画像生成API](/ja/api-capabilities/grok-imagine-image-official/text-to-image) - Playground付きAPIリファレンス
* [Grok Imagine Video](/ja/api-capabilities/grok-imagine-video/overview) - 同じグループ、テキスト動画生成および画像動画生成
* [Grok Imagine Reverse](/ja/api-capabilities/grok-imagine-image/overview) - 画像1枚あたりの定額料金、編集および1回の呼び出しでの複数画像生成に対応
* [画像APIの注意事項とベストプラクティス](/ja/api-capabilities/image-api-best-practices) - タイムアウト、切断、圧縮に関する一般的なアドバイス
* [チャージボーナス](/ja/faq/recharge-promotions)


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