Grok Imagine の画像生成

Grok Imagine の画像生成は同期呼び出しのみで、1 回のリクエストで画像の一時的なダウンロードリンクが返ります。

利用できるモデル

3 つのモデルはリクエストパラメータがまったく同じで、単価だけが異なります。

リクエストパラメータ

生成

quality、aspect_ratio、n はゲートウェイではなくモデルが検査します。grok-imagine-image-quality はモデル ID であって quality フィールドの値ではありません。

size は GPT Image のパラメータであり、Grok の画像生成では使用しません。形状は aspect_ratio、画素数のティアは resolution で決まります。GPT Image から移行する場合は size を削除し、quality を上記の 3 つの値のいずれかにマッピングしてください。

編集

/v1/images/edits は生成パラメータに加えて、参照画像を image で受け取ります。

• image は URL 文字列、文字列の配列、または { "url": ... } で指定できます。
• 各画像は公開 HTTP(S) URL または完全な Data URL(data:image/png;base64,…)です。
• 裸の base64、asset://、file_id は受け付けません。
• OpenAI SDK でローカルファイルを multipart の image または繰り返しの image[] として送ることもできます。

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "背景を夕暮れの海辺に変え、被写体はそのまま残す",
    "image": ["https://example.com/source.png"],
    "aspect_ratio": "3:2",
    "resolution": "1k"
  }'

縦横比と実際の出力サイズ

aspect_ratio が形状を決め、resolution が画素数の予算を決めます(1k で約 100 万画素、2k で約 400 万画素)。grok-imagine-image を resolution: 1k で実行した際の実測出力サイズは以下のとおりです。

9:19.5、20:9、9:20 も有効な値ですが、上表にはその実測サイズを記載していません。resolution: 2k は同じ形状を保ったまま画素数の予算を引き上げます。例えば 16:9 は 2816×1584、1:1 は 2048×2048 になります。

レスポンス

レスポンス例(URL はプレースホルダー、その他のメタデータは省略):

{
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}

画像は受け取ったらすぐにダウンロードして保存してください。レスポンスにトークン使用量は含まれません。空のレスポンスは画像が生成されなかったことを意味するため、空の data 配列を成功と見なさないでください。

例

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "日差しの差し込む窓辺で眠る茶トラ猫、雑誌写真風",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1
  }'

aspect_ratio と resolution は OpenAI SDK の組み込みパラメータではないため、Python では extra_body に入れます。

注意事項

• 同期のみです。ストリーミングには対応しておらず、Prefer: respond-async も送らないでください。
• 画像の resolution は 1k と 2k のみで、4K ティアはなく、動画の 480p / 720p / 1080p も使えません。
• 返される URL は一時的なものなので、すぐにダウンロードしてください。
• 編集の参照画像は最大 2 枚で、これは HopBase の画像編集の制限であり動画には適用されません。
• 画像と動画は別々のプランで、キーは共通ではありません。動画は Grok Imagine の動画を参照してください。

よくあるエラー

範囲外の n、quality、aspect_ratio はモデル側が独自のメッセージで拒否します。画像リクエストが失敗した場合は、HTTP ステータスと error を確認してください。

課金

課金は返された画像の枚数 × resolution ティアで、ピクセル寸法には依存しません。/v1/images/edits の参照画像は 1 枚ごとに別途課金され、審査で拒否されたリクエストは課金されません。grok-imagine-image は 2k も受け付け、1k ティアの単価で課金します。

レスポンスの usage.cost_in_usd_ticks は実際の課金額ではありません。突き合わせにはコンソールの使用状況ページを使い、ティアごとの単価は上表のモデルカード、実際の適用レートはモデル広場で確認してください。

次のステップ

• 画像の概要: 画像シリーズの比較と共通ルール
• GPT Image、Gemini の画像生成、Seedream: ほかの画像シリーズ
• Grok Imagine の動画: Grok の動画タスクの送信とポーリング
• API リファレンス: 画像の生成、画像の編集
• トラブルシューティング: 失敗したリクエストを症状から調べる