概要
Grok Imagine 2 は xAI の 最新の第2世代 画像モデルです。第1弾からパラメータ制御と編集の両面で大きく進化しており、アスペクト比と解像度が実際に反映され、2K ティアが利用でき、1回の呼び出しで最大 10 枚の画像を返し、参照編集では元画像がきちんと保持されます。 APIYI では 2 種類のバリエーションを提供しています:grok-imagine-image(標準)と grok-imagine-image-quality(高品質)です。どちらも同じエンドポイントとパラメータを共有しており、違いは出力忠実度と価格だけです。
2 が含まれていません。 製品名は Grok Imagine 2 ですが、呼び出すモデル名は grok-imagine-image と grok-imagine-image-quality です — 存在しないモデルなので 503 を返す grok-imagine-2-image は書かないでください。テキストから画像生成 API
画像編集 API
APIYIでGrok Imagine 2を使う理由
OpenAI互換フォーマット
/v1/images/generationsおよび/v1/images/editsエンドポイントです。リクエストボディとレスポンスフィールドはOpenAI Images APIと一致しているため、公式のOpenAI SDKをそのまま利用でき、移行作業は不要です。同時実行数の上限なし
一律料金、予測しやすいコスト
グローバルアクセス、障壁なし
api.apiyi.comへ直接接続できます。充実したモデルエコシステム
専門サポート
主な機能
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回のリクエストで複数画像を返します — バッチ選択に最適です高速な生成
真の参照編集
マルチ画像融合
2つのレスポンス形式
url 直接リンクまたは b64_json 生の base64、両方のエンドポイントでサポートされていますOpenAI SDK対応
client.images.generate() と client.images.edit() はそのまま使えます — 手動のHTTP実装は不要です価格
- 解像度に依存しません:
1kと2kは同じ料金です — 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 課金モデルもカバーできます。
技術仕様
エンドポイント
GPT-Image-2 からの移行
すでに GPT-Image-2 を統合している場合、エンドポイントと呼び出し規約は同一(/v1/images/generations + /v1/images/edits、OpenAI SDK 互換)です — ただし パラメータ体系が異なる ため、モデル名を差し替えるだけでは動作しません。変更が必要な点は以下のとおりです。
パラメータ対応表
最も起こしやすい 3 つのミス
変更前と変更後
主要パラメータ
aspect_ratio と resolution(出力サイズ)
これらを合わせて実際の出力ピクセル数が決まります。計測値はリクエストと完全に一致します:
aspect_ratio の enum 外の値(例: 5:7、21:9)や resolution(例: 1K、1024x1024)は静かにデフォルトにフォールバックし、それでも画像が返されます。無効な response_format も同様に url にフォールバックします。したがって、出力が想定どおりでない場合は、まずパラメータ名のスペルを確認してください。ただし例外として resolution: "4k" は 503 model_service_unavailable を返します。つまりそのティアはサポートされていないという意味であり、チャネルが停止しているわけではありません — 1k / 2k に戻してください。n(1回の呼び出しあたりの画像数)
1-10 を受け付けます。返される data 配列の長さは n に等しく、各画像に課金されます。0 は静かに 1 として扱われ、11 以上は 400 を返します。
ベストプラクティス
最初に決めてください:生成か編集か?
/v1/images/generations。参照画像が1枚でもある場合、たとえ1ピクセルの微調整でも → /v1/images/edits。間違ったエンドポイントを選んでもエラーは出ず、予期しない画像が返るだけです。クライアントのタイムアウトを360秒に設定してください
構図は prompt ではなく aspect_ratio で制御してください
aspect_ratio: "16:9" のほうが prompt で「横長の構図」と指示するよりはるかに信頼できます。解像度の段階は帯域幅で選んでください
編集時は「他はすべて変更しないでください」と伝えてください
融合するときは画像を明示的に参照してください
image[] のアップロード順が「画像1 / 画像2 / 画像3」を意味します。「画像1の被写体を画像2のシーンに入れてください」と書くほうが、モデルに推測させるよりはるかに確実です。再現性を seed に頼らないでください
seedをサポートしていないため、同じ prompt でも呼び出しごとに結果が変わります。再生成できると期待するのではなく、残したい画像は保存しておいてください。バッチ処理はそのまま並行実行してください
エラーコードと再試行
400 と 415 は決定的なので、再試行しても無意味です。代わりにアラートを上げてください。再試行する価値があるのは 429 とネットワーク層のタイムアウトのみで、その場合は指数バックオフを行い、試行回数は最大 3 回にしてください。400 invalid_request は「bad parameter」と「content blocked」の両方をカバーしており、レスポンスボディでは両者を区別できません。実用的な目安はレイテンシです: moderation のブロックは約 5〜6 秒で返ってきます。成功した生成(約 9 秒)より速いです。これは、ブロックが生成開始前に発生するためです。よくある質問
なぜ、ベンダーのドキュメントでは JSON と示されているのに、/v1/images/edits に JSON を送ると 400 が返るのですか?
なぜ、ベンダーのドキュメントでは JSON と示されているのに、/v1/images/edits に JSON を送ると 400 が返るのですか?
multipart/form-data のみを受け付けるのに対し、上流のベンダーのドキュメントは公開画像 URL を含む JSON 本文を説明しているためです。両者は異なります。このサイトのドキュメントに従ってください。正しい形式はファイルアップロードです:参照画像を text-to-image に送ったのに 200 が返り、結果が無関係なのはなぜですか?
参照画像を text-to-image に送ったのに 200 が返り、結果が無関係なのはなぜですか?
/v1/images/generations は image / image_url / images を黙って無視し、prompt だけから生成し、通常どおり課金されます。エラーの兆候がないため、「編集が壊れている」と結論づけてしまいがちです。参照画像を使うワークフローでは必ず /v1/images/edits を使う必要があります。なぜ resolution / aspect_ratio は編集エンドポイントに影響しないのですか?
なぜ resolution / aspect_ratio は編集エンドポイントに影響しないのですか?
resolution や aspect_ratio を渡してもエラーにはならず、何も起こりません。出力サイズを変えたい場合は、アップロード前に参照画像をトリミングまたはリサイズしてください。なぜレスポンスに revised_prompt がないのですか?
なぜレスポンスに revised_prompt がないのですか?
revised_prompt を返さず、respect_moderation や model のようなフィールドも返しません。各 data[] エントリーは response_format に応じて url か b64_json のどちらか一方 を含みます。両方は入りません。レスポンスをパースする際に、これらのフィールドが存在すると仮定しないでください。usage の token 数で billing を突き合わせることはできますか?
usage の token 数で billing を突き合わせることはできますか?
usage.prompt_tokens は実際の prompt 長に関係なく常に 1000 x n で、これはプレースホルダーです。このファミリーは画像ごとの定額でリクエスト単位課金です。実際の課金額は APIYI コンソールの課金記録をご利用ください。なぜ 1K は JPEG なのに 2K は PNG なのですか?サイズがかなり違います
なぜ 1K は JPEG なのに 2K は PNG なのですか?サイズがかなり違います
resolution: 1k は JPEG(約 220-300 KB)を返し、resolution: 2k はロスレス PNG(約 5-6 MB)を返します。おおよそ 20 倍の差があります。URL の拡張子、HTTP Content-Type、実際のバイト列は互いに整合しているので、Content-Type を基準に安全に分岐できます。帯域に敏感なシナリオ(モバイル、バルク転送)では 1k を優先してください。どちらの階層も同じ料金なので、判断基準は純粋に品質です。resolution: 4k で 503 が返ります。チャネルが落ちているのですか?
resolution: 4k で 503 が返ります。チャネルが落ちているのですか?
4k はこのファミリーでサポートされていない階層であり、ゲートウェイは 503 model_service_unavailable を返します。コード上は障害に見えますが、実際はパラメータの問題です。そのため、再試行しても解決しません。1k か 2k に戻してください。サポートされているのは 1k と 2k のみです。なぜ無効なパラメータでエラーではなく、間違った画像が返るのですか?
なぜ無効なパラメータでエラーではなく、間違った画像が返るのですか?
aspect_ratio(例: 5:7)、resolution(例: 1K、1024x1024)、および response_format(例: base64)はすべて黙ってデフォルトにフォールバックし、400 ではなく画像を返します。そのため、出力が期待と違うときは、まずパラメータ名の綴りを確認してください。特に、resolution の値は小文字の 1k / 2k です。1 回の呼び出しで何枚の画像を生成できますか?
1 回の呼び出しで何枚の画像を生成できますか?
n は 1-10 を受け付け、返される data 配列の長さは n と同じです。各画像は課金対象です。0 は黙って 1 として扱われ、11 以上では 400 invalid_request が返ります。seed ベースの再現性はサポートされていますか?
seed ベースの再現性はサポートされていますか?
seed を渡してもエラーにはなりませんが、効果はありません。つまり、同じ prompt と同じ seed でも、呼び出しごとに異なる画像が返ります。再生成しようとするのではなく、再利用したい画像は保存してください。公式の OpenAI SDK で呼び出せますか?
公式の OpenAI SDK で呼び出せますか?
base_url を https://api.apiyi.com/v1 に向けるだけです:aspect_ratio と resolution は標準の OpenAI SDK フィールドではないため、extra_body で渡してください。同時実行数の制限はありますか?バッチ生成はスロットリングされますか?
同時実行数の制限はありますか?バッチ生成はスロットリングされますか?
timeout です。画像 API は同期処理なので、まだ正常に処理中で課金対象にもなっているリクエストを途中で切らないよう、クライアントの timeout を 360 秒 に設定してください。コンテンツモデレーションはどのように動作し、ブロックをどう検知しますか?
コンテンツモデレーションはどのように動作し、ブロックをどう検知しますか?
400 invalid_request を返すため、レスポンスボディだけでは見分けられません。実用的な目安はレイテンシです。モデレーションによるブロックは約 5-6 秒で返り(ブロックが生成より先に起こります)、成功した画像は約 9 秒かかります。モデレーション結果にはある程度のランダム性もあるため、境界線上のコンテンツは再試行ごとに同じ挙動にならないことがあります。1 回の試行だけで結論を出さないでください。パラメータが正しいことを確認しても 400 が続く場合、prompt がモデレーションを引き起こした可能性が高いです。表現を見直してください。/v1/chat/completions ിലൂടെ画像を生成できますか?
/v1/chat/completions ിലൂടെ画像を生成できますか?
content は markdown の画像リンクです:/v1/images/generations と /v1/images/edits)— より豊富なパラメータ、より安定したレスポンス形状、そしてこのドキュメントとの整合性があります。関連ドキュメント
- Grok Imagine 2 テキストから画像への API - Playground付きのエンドポイントリファレンス
- Grok Imagine 2 画像編集 API - 編集とマルチイメージ融合のリファレンス
- Grok モデルガイド - xAIのテキストモデル
- 画像生成 API ベストプラクティス - タイムアウト、切断、圧縮
- API マニュアル
- チャージキャンペーン