Grok Imagine の画像生成
Grok Imagine で画像を生成・編集します。パラメータ、レスポンス、注意点をまとめています。
| 項目 | 値 |
|---|---|
| Base URL | https://api.hop-base.com/v1 |
| 画像を生成 | POST /v1/images/generations |
| 画像を編集 | POST /v1/images/edits |
| プラン | 「Grok スイート」 |
Grok Imagine の画像生成は同期呼び出しのみで、1 回のリクエストで画像の一時的なダウンロードリンクが返ります。
利用できるモデル
| モデル | モデル ID | ティア | 公式価格 |
|---|---|---|---|
| Grok Imagine Image | grok-imagine-image | 1k / 2k | $0.02/ 枚 |
| Grok Imagine Image 2.0 | grok-imagine-image-2.0 | 1k / 2k | $0.04〜/ 枚 |
| Grok Imagine Image Quality | grok-imagine-image-quality | 1k / 2k | $0.05〜/ 枚 |
3 つのモデルはリクエストパラメータがまったく同じで、単価だけが異なります。
リクエストパラメータ
生成
| パラメータ | 必須 | 型と制限 | デフォルト | 説明 |
|---|---|---|---|---|
model | 必須 | string、上表の 3 つの ID のいずれか | — | GET /v1/models の表記どおり |
prompt | 必須 | string、空不可 | — | 内容、構図、スタイル、編集指示 |
resolution | 任意 | 1k / 2k | 1k | 画素数のティアで課金ティア |
quality | 任意 | low / medium / auto | auto | Grok 独自のパラメータ |
aspect_ratio | 任意 | 16 種類、サイズの表を参照 | auto(1:1) | 形状を決める |
n | 任意 | 整数 1〜10 | 1 | 実際に返された枚数で課金 |
mask | 非対応 | — | — | 400 で拒否 |
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 | 必須 | 1〜5 枚(Quality は 1〜3 枚)、URL または Data URL | — | 超過分は拒否 |
imageは URL 文字列、文字列の配列、または{ "url": ... }で指定できます。xAI ネイティブのimages([{ "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 で実行した際の実測出力サイズは以下のとおりです。
aspect_ratio | 実測出力(1k) | 比率 |
|---|---|---|
1:1 | 1024×1024 | 1.0000 |
16:9 | 1280×720 | 1.7778 |
9:16 | 720×1280 | 0.5625 |
4:3 | 1152×864 | 1.3333 |
3:4 | 864×1152 | 0.7500 |
3:2 | 1248×832 | 1.5000 |
2:3 | 832×1248 | 0.6667 |
2:1 | 1408×704 | 2.0000 |
1:2 | 704×1408 | 0.5000 |
21:9 | 1568×672 | 2.3333 |
19.5:9 | 1248×576 | 2.1667 |
5:2 | 1600×640 | 2.5000 |
auto / 省略時 | 1024×1024 | 1.0000 |
9:19.5、20:9、9:20 も有効な値ですが、上表にはその実測サイズを記載していません。resolution: 2k は同じ形状を保ったまま画素数の予算を引き上げます。例えば 16:9 は 2816×1584、1:1 は 2048×2048 になります。
レスポンス
| フィールド | 型 | 説明 |
|---|---|---|
data | array | 生成された画像。実際の枚数分 |
data[].url | string | 画像の一時的なダウンロードリンク |
usage.cost_in_usd_ticks | integer | 公式の米ドル価格による計量値(単位は 100 億分の 1 米ドル)。そのまま保持される。課金額ではない |
usage.cost | number | このリクエストの課金額の人民元額(グループのレート適用後、usage.cost_usd と同じ課金額)。小数点以下最大 6 桁 |
usage.cost_usd | number | このリクエストで残高から実際に差し引かれた米ドル額。小数点以下最大 8 桁で、使用状況のこのレコードと同じ金額 |
usage.currency | string | usage.cost の通貨。常に CNY |
レスポンス例(URL はプレースホルダー、その他のメタデータは省略):
{
"data": [
{
"url": "https://example.com/generated-image.png"
}
],
"usage": {
"cost_in_usd_ticks": 200000000,
"cost": 0.0816,
"cost_usd": 0.012,
"currency": "CNY"
}
}同じ課金額はレスポンスヘッダー X-HopBase-Cost・X-HopBase-Cost-USD・X-HopBase-Currency でも返します。生成に約 40 秒以上かかる場合、HopBase は先に 200 のレスポンスヘッダーを送り、キープアライブの空白を書き込むため、ヘッダーには課金額が入りません。レスポンス本文の usage.cost_usd(米ドル、使用記録と一致)または usage.cost(人民元)で照合してください。課金されなかった失敗にはいずれのフィールドも付きません。詳しくは課金を参照してください。
画像は受け取ったらすぐにダウンロードして保存してください。レスポンスにトークン使用量は含まれません。空のレスポンスは画像が生成されなかったことを意味するため、空の 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 は一時的なものなので、すぐにダウンロードしてください。
- 編集の参照画像の上限はモデルごとに異なります:
grok-imagine-image・grok-imagine-image-2.0は最大 5 枚、grok-imagine-image-qualityは最大 3 枚です。動画には適用されません。 - 画像と動画は別々のプランで、動画を呼び出すにはキーに Grok ビデオのプランも含める必要があります。動画は Grok Imagine の動画を参照してください。
multipart 形式の編集で残るのは model、prompt、image、n、resolution、aspect_ratio、quality だけで、その他のフォーム項目は破棄されます。
xAI 公式編集ドキュメントにはファイルのバイト数や入力ピクセルの上限がありません。出力 resolution から推定したり、GPT Image の 25 MiB / 4 MiB 規則を流用したりしないでください。
適切に圧縮した画像を使用してください。公式の素材検証は引き続き適用されます。
よくあるエラー
| エラー | 対処 |
|---|---|
resolution must be 1k or 2k | 1k か 2k にする |
this model does not support the mask parameter | mask を削除する |
<model> accepts at most N reference images per edit, got M; remove K and try again | 参照画像を N 枚以内にする(Quality は 3 枚、ほかは 5 枚) |
prompt must not be empty | 空でない prompt を送る |
/v1/images/edits requires at least one reference image: send "image" ... or "images" ... | image または images で参照画像を送る(Quality は 1〜3 枚、ほかは 1〜5 枚) |
image must be a data URL or an http(s) URL | 裸の base64 を完全な Data URL にする |
image object is missing the url field | オブジェクトを { "url": ... } にする |
image models do not support Chat Completions, please use the Images API | /v1/images/generations を呼ぶ |
メッセージに content-moderated を含む 400 | プロンプトを書き換える。課金なし |
範囲外の n、quality、aspect_ratio はモデル側が独自のメッセージで拒否します。画像リクエストが失敗した場合は、HTTP ステータスと error を確認してください。
課金
課金は返された画像の枚数 × resolution ティアで、ピクセル寸法には依存しません。/v1/images/edits の参照画像は 1 枚ごとに別途課金され、審査で拒否されたリクエストは課金されません。grok-imagine-image は 2k も受け付け、1k ティアの単価で課金します。
レスポンスの usage.cost_in_usd_ticks は公式の米ドル計量値で、実際の課金額ではありません。usage.cost_usd がこのリクエストで残高から実際に差し引かれた金額(米ドル)で、usage.cost は同じ課金額の人民元額です。公式の計量値を課金額と取り違えず、突き合わせには usage.cost_usd またはコンソールの使用状況ページを使い、ティアごとの単価は上表のモデルカード、実際の適用レートはモデル広場で確認してください。
次のステップ
- 画像の概要: 画像シリーズの比較と共通ルール
- GPT Image、Gemini の画像生成、Seedream: ほかの画像シリーズ
- Grok Imagine の動画: Grok の動画タスクの送信とポーリング
- API リファレンス: 画像の生成、画像の編集
- トラブルシューティング: 失敗したリクエストを症状から調べる