Managed Inference and Agents API の /v1/images/generations

Table of Contents [expand]

リクエストボディパラメータ
リクエストヘッダー
応答形式
リクエストの例
応答の例

この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。

最終更新日 2025年09月04日(木)

/v1/images/generations エンドポイントは、説明的なテキストプロンプトに基づいて画像を生成します。アスペクト比や画像フォーマットを制御し、再現性を高めるためにシードを指定することもできます。任意のパラメータを使用すると、特定の要素を除外するためのネガティブプロンプトを提供するなどして、出力をさらに改善することができます。

リクエストボディパラメータ

パラメータを使用して、生成する画像のサイズや形式などの詳細を制御します。

必須パラメータ

フィールド	型	説明	例
model	文字列	使用する画像生成モデルの ID	`"stable-image-ultra"`
prompt	文字列	生成する画像を説明するテキストプロンプト (最大長 10,000 文字)	`"A beautiful sunset over the mountains."`

任意のパラメータ

フィールド	型	説明	デフォルト	例
aspect_ratio	列挙<文字列>	生成される画像のアスペクト比を制御します。次のいずれか: `"16:9"`、`"1:1"`、`"21:9"`、`"2:3"`、`"3:2"`、`"4:5"`、`"5:4"`、`"9:16"`、`"9:21"`	`"1:1"`	`"16:9"`
negative_prompt	文字列	画像で避けるべきキーワードやフレーズ (たとえば、`"crowded"` は混雑したシーンを防ぐのに役立ちます)。最大長: 10,000文字	`""`	`"crowded"`
output_format	列挙<文字列>	出力画像の形式次のいずれか: `"jpeg"`、`"png"`	`"png"`	`"jpeg"`
size	列挙<文字列>	出力画像のサイズ (ピクセル単位) 次のいずれか: `"1344x768"`、`"1024x1024"`、`"1536x640"`、`"832x1216"`、`"1216x832"`、`"896x1088"`、`"1088x896"`、`"768x1344"`、`"640x1536"`	`"1024x1024"`	`"640x1536"`
seed	数値	画像を生成するためのベースとして使用される開始値 (すべてのパラメータが同じままであれば、同じシードで生成された画像は同一になる一方、異なるシードで生成された画像は似ているものの同一にはなりません)。範囲:`0` (ランダム) ～ `4294967295`	`0`	`123`
allow_ignored_params	ブール値	エラーをスローする代わりに、リクエスト内のサポートされていないパラメータを無視します	`false`	`true`

リクエストヘッダー

次の例では、モデルリソースに "DIFFUSION" のエイリアスがあると仮定します (これは、--as DIFFUSION フラグを使用してモデルリソースを作成したことを意味します)。

ヘッダー	型	説明
`Authorization`	文字列	AI アドオンの ‘DIFFUSION’ の値 (API ベアラートークン)

すべての推論の curl リクエストには、指定されたモデルの Heroku 推論キーを含む Authorization ヘッダーを含める必要があります。

応答形式

リクエストが成功すると、API は次の構造で JSON オブジェクトを返します。

フィールド	型	説明
created	整数	画像が作成された時点の UNIX タイムスタンプ
data	オブジェクトの配列	生成される画像のリスト (長さは常に 1)

データオブジェクト

data 配列内の各オブジェクトには以下が含まれます。

フィールド	型	説明
b64_json	文字列	(オプション) 生成される画像、`base64` でエンコード
revised_prompt	文字列	OpenAI 形式の応答との互換性のために含めます常に: `""`

リクエストの例

/v1/images/generations curl リクエストの例を見てみましょう。

まず、このコマンドを使用して、Heroku 環境変数をローカル変数として設定します。

eval $(heroku config -a $APP_NAME --shell | grep '^DIFFUSION_' | sed 's/^/export /' | tee >(cat >&2))

次に、curl リクエストを送信します。

curl $DIFFUSION_URL/v1/images/generations \
 -H "Authorization: Bearer $DIFFUSION_KEY" \
 -d @- <<EOF
{
  "model": "$DIFFUSION_MODEL_ID",
  "prompt": "A surreal landscape with glowing mushrooms under a night sky."
}
EOF

以下は同じリクエストですが、コンピューター上で base64 を解析して画像を開くように変更されています。

curl $DIFFUSION_URL/v1/images/generations \
 -H "Authorization: Bearer $DIFFUSION_KEY" \
 -d @- <<EOF | jq -r '.data[0].b64_json' | base64 --decode > "x.png"
{
  "model": "$DIFFUSION_MODEL_ID",
  "prompt": "A surreal landscape with glowing mushrooms under a night sky."
}
EOF

open x.png

応答の例

{
  "created": 1745612037,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": ""
    }
  ]
}

Categories