Skip to main content

概要

Grok Imagine 2 は xAI の 最新の第2世代 画像モデルです。第1弾からパラメータ制御と編集の両面で大きく進化しており、アスペクト比と解像度が実際に反映され、2K ティアが利用でき、1回の呼び出しで最大 10 枚の画像を返し、参照編集では元画像がきちんと保持されます。 APIYI では 2 種類のバリエーションを提供しています: grok-imagine-image(標準)と grok-imagine-image-quality(高品質)です。どちらも同じエンドポイントとパラメータを共有しており、違いは出力忠実度と価格だけです。
主な特徴: リクエストごとの一律料金(1K と 2K は同額)、実際に反映される 5 種類のアスペクト比 x 2 種類の解像度ティア、1回の呼び出しで最大 10 枚、そしてアートスタイル、構図、配色、被写体の同一性を保持する高忠実度の参照編集です。1K 画像の生成には約 9 秒かかります。
モデル ID には 2 が含まれていません。 製品名は Grok Imagine 2 ですが、呼び出すモデル名は grok-imagine-imagegrok-imagine-image-quality です — 存在しないモデルなので 503 を返す grok-imagine-2-image は書かないでください。
📌 まずこれを読んでください: 参照画像は編集エンドポイント /v1/images/edits でのみ動作します — テキストから画像生成では使えません。image / image_url / images/v1/images/generations に渡すと 200 でごく普通の画像 が返りますが、参照は 静かに破棄され、それでも課金されます — いかなるエラーも発生しません。下記の エンドポイント をご覧ください。
すべての画像 API は 同期式 です。非同期タスク ID はないため、クライアントが切断されると結果は失われますが、リクエストは課金されたままになります。十分に長いタイムアウトを設定してください — 画像 API のベストプラクティス をご覧ください。

テキストから画像生成 API

テキスト prompt から画像を生成し、ライブテスト用のインタラクティブなプレイグラウンドを備えています。

画像編集 API

参照画像と指示をアップロードし、1〜3 枚の画像融合とプレイグラウンドを利用できます。

APIYIでGrok Imagine 2を使う理由

OpenAI互換フォーマット

標準の/v1/images/generationsおよび/v1/images/editsエンドポイントです。リクエストボディとレスポンスフィールドはOpenAI Images APIと一致しているため、公式のOpenAI SDKをそのまま利用でき、移行作業は不要です。

同時実行数の上限なし

RPM/RPD の厳しい上限はありません。100 RPMで余裕をもって計測済みで、チャネル容量にも十分な余裕があるため、バッチワークロードは線形にスケールします — クォータ申請や独自のスロットリングは不要です。

一律料金、予測しやすいコスト

画像ごとに固定価格で、解像度に依存しません — 2K画像は1Kと同じ料金です。正確な画像枚数で予算を組めて、チャージ特典を重ねるとさらに安くできます。

グローバルアクセス、障壁なし

海外サーバーやプロキシは不要です。 中国本土のデータセンター、家庭用ブロードバンド、海外ノードのいずれもapi.apiyi.comへ直接接続できます。

充実したモデルエコシステム

ほかにも利用できます: Nano Banana 2, GPT-Image-2, Seedream, FLUX, さらに Grok テキストモデルもあります。

専門サポート

当社チームは画像生成ワークロードに深く取り組んでおり、PoC から本番展開までエンタープライズ顧客をサポートできます。

主な機能

2つの解像度帯

1k 約1メガピクセル、2k 4.2〜4.5メガピクセル(16:9で2816x1584) — 同一価格

5種類のアスペクト比

1:1 / 16:9 / 9:16 / 4:3 / 3:4、実測ピクセル寸法が完全に一致します

1回あたり最大10枚

nは1〜10を受け付け、1回のリクエストで複数画像を返します — バッチ選択に最適です

高速な生成

1Kで約9秒、2Kで15〜17秒で、負荷下でもレイテンシーは安定しています — 100 RPMでも快適に動作します

真の参照編集

指定した内容だけを変更し — アートスタイル、構図、パレット、被写体の同一性はそのまま維持されます

マルチ画像融合

編集エンドポイントは1〜3枚の参照画像を受け付けます。たとえば、画像Aの被写体を画像Bのシーンとスタイルに配置できます

2つのレスポンス形式

url 直接リンクまたは b64_json 生の base64、両方のエンドポイントでサポートされています

OpenAI SDK対応

client.images.generate()client.images.edit() はそのまま使えます — 手動のHTTP実装は不要です

価格

課金に関する注意事項
  • 解像度に依存しません: 1k2k は同じ料金です — 2K でも追加料金はかかりません。
  • 画像ごと: n=4 は、prompt の長さにかかわらず 4 画像分として課金されます。
  • 編集の料金はテキストから画像生成と同じです/v1/images/edits に追加料金はありません。
  • usage ブロックは照合に使用できません: prompt_tokens は常に 1000 x n であり、プレースホルダーです。代わりにコンソールの課金記録を使用してください。

グループ設定

Grok Imagine 2 は Default グループ(1.0x レート倍率) で動作し、上の価格表と一致します。Group の切り替えは不要です。 推奨の Token 課金モデル: Pay-as-you-go Priority. このファミリーはリクエストごとに課金され、Pay-as-you-go Priority と Pay-per-request の両方で正しくルーティングされます。Pay-as-you-go Priority を選ぶと、1つの Token でプラットフォーム上の他の token 課金モデルもカバーできます。
すでに Token が他の画像モデルをカバーしている場合は、Default を主グループのままにしておけば問題ありません。このファミリーには専用のグループも追加設定も不要です。

技術仕様

エンドポイント

✅ 編集エンドポイントでは multipart/form-data のファイルアップロードが必要です/v1/images/edits に JSON を送信すると、常に 400 が返ります:
これは、上流ベンダーのドキュメントから統合している場合に特に重要です — そのドキュメントでは、公開画像 URL を含む JSON 本文が説明されていますが、これは APIYI ゲートウェイ経由では 動作しません代わりにこのページに従ってください: -F "[email protected]" を使ってファイルをアップロードします。完全な例は 画像編集 API をご覧ください。ファイルフィールド名は image または image[] にする必要があります。images / image_file は 415 を返します。
⚠️ 参照画像は絶対にテキストから画像生成エンドポイントに送信しないでください/v1/images/generationsimage / image_url / images を受け取っても、エラーは返しません。200 を返して、参照を完全に無視し、プロンプトだけから新しい画像を生成します — しかも課金は通常どおり発生しますエラーシグナルがないため、通常は出力が入力とまったく関係ないことに気づいたときに初めて表面化します。参照画像を使うワークフローでは必ず /v1/images/edits を使用してください。
メインドメイン https://api.apiyi.com、バックアップ https://vip.apiyi.com。チャット形式の生成(/v1/chat/completions)は動作しますが、推奨される方法ではありません — 下の FAQ をご覧ください。

GPT-Image-2 からの移行

すでに GPT-Image-2 を統合している場合、エンドポイントと呼び出し規約は同一/v1/images/generations + /v1/images/edits、OpenAI SDK 互換)です — ただし パラメータ体系が異なる ため、モデル名を差し替えるだけでは動作しません。変更が必要な点は以下のとおりです。

パラメータ対応表

最も起こしやすい 3 つのミス

1. デフォルトのレスポンス形式が逆になっています — 最も見落とされやすい変更点GPT-Image-2 は b64_json のみを返しますurl はありません)が、Grok Imagine 2 は デフォルトで url を返します。パーサーが resp.data[0].b64_json を読む場合、移行後は None / undefined を受け取ることになります。次の 2 つの対処法のどちらかを選びます。
  • 既存のコードを維持する"response_format": "b64_json" を明示的に渡す
  • 直接リンクに切り替えるdata[0].url を読み取り、ダウンロードする
また、GPT-Image-2 の usage には 実際の token 数 が含まれますが、Grok Imagine 2 の usageプレースホルダー(常に 1000 x n)です。usage を基にした課金集計スクリプトは、移行後に誤った数値を出力します。
2. size はエラーではなく静かに失敗しますGPT-Image-2 は厳密に検証し、無効な入力には通常 400 を返します。Grok Imagine 2 は寛容で、sizequalitystyle のような OpenAI 形式のフィールドは 黙って無視され、不正な aspect_ratio / resolution の値は 黙ってデフォルト値にフォールバックしますそのため、model だけを変更して size: "1536x1024" を削除し忘れると、リクエストは 200 を返して 1024x1024 の正方形画像を生成します — しかも、そのパラメータが無視されたことを示すものは何もありません。移行後は、最初の呼び出しで出力ピクセル寸法を確認しaspect_ratio / resolution が実際に反映されたことを確かめてください。
3. 参照画像はもはやテキストから画像生成のエンドポイントに送れませんこの落とし穴はこのモデル特有です。参照画像を /v1/images/generations に送ると 200 が返り、参照は黙って破棄され、それでも課金されます。参照画像を使う呼び出しはすべて /v1/images/editsmultipart/form-data を使う必要があります — 上の エンドポイント を参照してください。

変更前と変更後

どちらを使うべきでしょうか? マスクインペインティング、ピクセル単位で正確なカスタムサイズ、または最大 16 件の参照の融合が必要なら、GPT-Image-2 のままにしてください。予測しやすい料金(1 画像あたりの定額、2K の追加料金なし)、1回の呼び出しで複数画像n、最大 10 枚)、または編集時の高いソース忠実度が必要なら、Grok Imagine 2 を選んでください。2つは共存できます — 同じ token で両方を呼び出せます。

主要パラメータ

aspect_ratioresolution(出力サイズ)

これらを合わせて実際の出力ピクセル数が決まります。計測値はリクエストと完全に一致します:
両方のパラメータはテキストから画像生成にのみ適用されます。 /v1/images/edits ではエラーなく受け付けられますが、効果はありません。編集後の出力は常に入力参照画像の寸法に一致します(1280x720 in、1280x720 out)。出力サイズを変更するには、アップロード前に参照画像をトリミングまたはリサイズしてください。
バリデーションは緩く、タイプミスでもエラーは発生しません。 aspect_ratio の enum 外の値(例: 5:721:9)や resolution(例: 1K1024x1024)は静かにデフォルトにフォールバックし、それでも画像が返されます。無効な response_format も同様に url にフォールバックします。したがって、出力が想定どおりでない場合は、まずパラメータ名のスペルを確認してくださいただし例外として resolution: "4k"503 model_service_unavailable を返します。つまりそのティアはサポートされていないという意味であり、チャネルが停止しているわけではありません — 1k / 2k に戻してください。

n(1回の呼び出しあたりの画像数)

1-10 を受け付けます。返される data 配列の長さは n に等しく、各画像に課金されます。0 は静かに 1 として扱われ、11 以上は 400 を返します。

ベストプラクティス

1

最初に決めてください:生成か編集か?

参照画像なし → /v1/images/generations。参照画像が1枚でもある場合、たとえ1ピクセルの微調整でも → /v1/images/edits。間違ったエンドポイントを選んでもエラーは出ず、予期しない画像が返るだけです。
2

クライアントのタイムアウトを360秒に設定してください

画像APIは同期処理です。2K は 15〜17 秒かかり、ピーク時やコールドスタート時にはさらに長くなることがあります。60秒のタイムアウトでは、課金対象のままのリクエストが不要に失敗してしまいます。
3

構図は prompt ではなく aspect_ratio で制御してください

このパラメータは実際に効くので、aspect_ratio: "16:9" のほうが prompt で「横長の構図」と指示するよりはるかに信頼できます。
4

解像度の段階は帯域幅で選んでください

2K は 1枚あたり 5〜6 MB のロスレスPNG、1K は 220〜300 KB のJPEGです — およそ20倍の差があります。モバイルや一括転送では 1K を推奨します。どちらの段階もコストは同じなので、選択基準は純粋に品質と帯域幅です。
5

編集時は「他はすべて変更しないでください」と伝えてください

「マフラーを赤に変えて、他はすべてまったく同じにしてください」のような指示は非常によく効きます — モデルはこの制約に強く従い、画像の残りの部分を保持します。
6

融合するときは画像を明示的に参照してください

image[] のアップロード順が「画像1 / 画像2 / 画像3」を意味します。「画像1の被写体を画像2のシーンに入れてください」と書くほうが、モデルに推測させるよりはるかに確実です。
7

再現性を seed に頼らないでください

このファミリーはseedをサポートしていないため、同じ prompt でも呼び出しごとに結果が変わります。再生成できると期待するのではなく、残したい画像は保存しておいてください。
8

バッチ処理はそのまま並行実行してください

同時実行数の制限はありません — 100 RPM でも余裕で動作します。チャネル容量にも十分余裕があるため、シリアルキューを作ったり追加のクォータを要求したりする必要はありません。

エラーコードと再試行

クライアント向けガイダンス: 400415 は決定的なので、再試行しても無意味です。代わりにアラートを上げてください。再試行する価値があるのは 429 とネットワーク層のタイムアウトのみで、その場合は指数バックオフを行い、試行回数は最大 3 回にしてください。400 invalid_request は「bad parameter」と「content blocked」の両方をカバーしており、レスポンスボディでは両者を区別できません。実用的な目安はレイテンシです: moderation のブロックは約 5〜6 秒で返ってきます。成功した生成(約 9 秒)より速いです。これは、ブロックが生成開始前に発生するためです。

よくある質問

これは、APIYI ゲートウェイの編集エンドポイントが multipart/form-data のみを受け付けるのに対し、上流のベンダーのドキュメントは公開画像 URL を含む JSON 本文を説明しているためです。両者は異なります。このサイトのドキュメントに従ってください。正しい形式はファイルアップロードです:
その利点は、画像ホスティングが不要なことです。公開 URL を用意するよりも、ローカルファイルを直接アップロードするほうが簡単です。完全な例は Image Editing API をご覧ください。
これは想定どおりの挙動で、このモデルで最もよくある落とし穴です。/v1/images/generationsimage / image_url / images黙って無視し、prompt だけから生成し、通常どおり課金されますエラーの兆候がないため、「編集が壊れている」と結論づけてしまいがちです。参照画像を使うワークフローでは必ず /v1/images/edits を使う必要があります。
編集後の出力サイズは入力した参照画像に従います。入力が 1280x720 なら出力も 1280x720、入力が 1024x1024 なら出力も 1024x1024 です。ここで resolutionaspect_ratio を渡してもエラーにはならず、何も起こりません。出力サイズを変えたい場合は、アップロード前に参照画像をトリミングまたはリサイズしてください。
このファミリーは revised_prompt を返さず、respect_moderationmodel のようなフィールドも返しません。各 data[] エントリーは response_format に応じて urlb64_json のどちらか一方 を含みます。両方は入りません。レスポンスをパースする際に、これらのフィールドが存在すると仮定しないでください。
いいえ。 usage.prompt_tokens は実際の prompt 長に関係なく常に 1000 x n で、これはプレースホルダーです。このファミリーは画像ごとの定額でリクエスト単位課金です。実際の課金額は APIYI コンソールの課金記録をご利用ください。
これは上流側の挙動です。resolution: 1k は JPEG(約 220-300 KB)を返し、resolution: 2k はロスレス PNG(約 5-6 MB)を返します。おおよそ 20 倍の差があります。URL の拡張子、HTTP Content-Type、実際のバイト列は互いに整合しているので、Content-Type を基準に安全に分岐できます。帯域に敏感なシナリオ(モバイル、バルク転送)では 1k を優先してください。どちらの階層も同じ料金なので、判断基準は純粋に品質です。
いいえ。 4k はこのファミリーでサポートされていない階層であり、ゲートウェイは 503 model_service_unavailable を返します。コード上は障害に見えますが、実際はパラメータの問題です。そのため、再試行しても解決しません1k2k に戻してください。サポートされているのは 1k2k のみです。
このファミリーの検証は緩めです。無効な aspect_ratio(例: 5:7)、resolution(例: 1K1024x1024)、および response_format(例: base64)はすべて黙ってデフォルトにフォールバックし、400 ではなく画像を返します。そのため、出力が期待と違うときは、まずパラメータ名の綴りを確認してください。特に、resolution の値は小文字の 1k / 2k です。
n1-10 を受け付け、返される data 配列の長さは n と同じです。各画像は課金対象です0 は黙って 1 として扱われ、11 以上では 400 invalid_request が返ります。
いいえ。 seed を渡してもエラーにはなりませんが、効果はありません。つまり、同じ prompt と同じ seed でも、呼び出しごとに異なる画像が返ります。再生成しようとするのではなく、再利用したい画像は保存してください。
はい。どちらのエンドポイントも OpenAI の画像 API と互換です。base_urlhttps://api.apiyi.com/v1 に向けるだけです:
aspect_ratioresolution は標準の OpenAI SDK フィールドではないため、extra_body で渡してください。
同時実行数の制限はありません。 100 RPM でも余裕で計測でき、429 もキュー拒否もなく、十分なチャネル容量に支えられています。直列キューを組んだり、追加のクォータを要求したりせず、並列に呼び出せます。実際に重要なのは timeout です。画像 API は同期処理なので、まだ正常に処理中で課金対象にもなっているリクエストを途中で切らないよう、クライアントの timeout を 360 秒 に設定してください。
このファミリーにはコンテンツモデレーションが適用されます。ブロックされたリクエストは、パラメータエラーとまったく同じエラーコードとメッセージ400 invalid_request を返すため、レスポンスボディだけでは見分けられません。実用的な目安はレイテンシです。モデレーションによるブロックは約 5-6 秒で返り(ブロックが生成より先に起こります)、成功した画像は約 9 秒かかります。モデレーション結果にはある程度のランダム性もあるため、境界線上のコンテンツは再試行ごとに同じ挙動にならないことがあります。1 回の試行だけで結論を出さないでください。パラメータが正しいことを確認しても 400 が続く場合、prompt がモデレーションを引き起こした可能性が高いです。表現を見直してください。
はい。ただし、推奨ルートではありません。このエンドポイントは標準的な chat 構造を返し、その content は markdown の画像リンクです:
これは Chatbox や LobeChat のような会話型クライアントに向いています。プログラムによる統合には、Images API を使用してください/v1/images/generations/v1/images/edits)— より豊富なパラメータ、より安定したレスポンス形状、そしてこのドキュメントとの整合性があります。

関連ドキュメント