画像

Lovely Router は OpenAI Images API（POST /v1/images/generations と POST /v1/images/edits）を提供しています。OpenAI SDK の接続先を https://lovelyrouter.com/v1 にし、Lovely Router のキーを使ってください。リクエストは OpenAI の定義どおりにそのまま渡されるため、下記の制限を除き、OpenAI の Images API リファレンスがそのまま当てはまります。

モデル#

GPT Image モデルは生成と編集に対応し、参考画像も使えます。z-image-turbo-nsfw-v2 は生成のみです。quality は GPT Image 2.5 モデルと z-image-turbo-nsfw-v2 には効きません。

画像モデルは Images API にだけ応答します。Chat Completions に送ると、/v1/images/generations を案内する 404 が返ります。GPT Image モデルは gpt-value、z-image-turbo-nsfw-v2 は creative-hosted のチャネルグループで提供されるため、別のグループに紐づいたキーでは使えません。

画像を生成する#

curl https://lovelyrouter.com/v1/images/generations \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor painting of a red fox in a snowy birch forest at dawn",
    "size": "1024x1024",
    "quality": "medium"
  }' | jq -r '.data[0].b64_json' | base64 --decode > fox.png

レスポンスの例（一部省略）:

{
  "created": 1792064388,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…" }],
  "background": "auto",
  "model": "gpt-image-2",
  "output_format": "png",
  "quality": "medium",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 19,
    "input_tokens_details": { "text_tokens": 19, "image_tokens": 0 },
    "output_tokens": 1756,
    "output_tokens_details": { "image_tokens": 1756, "text_tokens": 0 },
    "total_tokens": 1775
  }
}

画像は常に b64_json に base64 で返ります。response_format: "url" は無視されます。画像の生成には通常 40 秒〜2 分かかり、さらにキューでの待ち時間が加わるため、HTTP クライアントのタイムアウトは 10 分以上にしてください（ゲートウェイは 9 分以内に応答します）。3840×2160 の PNG は約 14 MB、base64 にすると約 18 MB です。接続を保持せずに送信して後で受け取るには、画像ジョブを使ってください。

サイズと品質#

• size: 1024x1024、1536x1024、1024x1536、2048x2048、3840x2160、または任意の WIDTHxHEIGHT。両辺が 16 の倍数で、長辺が 3840 ピクセル以下かつ短辺の 3 倍以下、総ピクセル数が 655,360〜8,294,400 である必要があります。auto はモデルに任せます。
• quality: low、medium、high、auto（デフォルト）。料金はどの品質でも同じです。
• output_format: png（デフォルト）、jpeg、webp。output_compression（0〜100）は jpeg と webp に適用されます。
• background: transparent は png と webp で使えます。

複数枚をまとめて生成する#

n（1〜10）を指定すると、1 回のリクエストで同じプロンプトの画像を複数枚受け取れます。生成でも編集でも使えます。画像はまとめて data に入って返ります。

result = client.images.generate(
    model="gpt-image-2",
    prompt="A watercolor painting of a red fox in a snowy birch forest at dawn",
    n=4,
)
for i, image in enumerate(result.data):
    with open(f"fox-{i + 1}.png", "wb") as f:
        f.write(base64.b64decode(image.b64_json))

• 1 枚ごとに 1 枚分の料金がかかるので、4 枚なら 4 倍です。送信時に n 枚分の料金が確保され、実際に受け取った枚数分だけ課金されます。
• 画像は、チャネルごとにできるだけ少ないモデル呼び出しで作られます。GPT Image モデルでは n: 4 でもたいてい 1 枚とほぼ同じ時間で終わります。ホスト型モデルは同じ GPU で 1 枚ずつ順に作ります。
• 一部の画像を作れなかった場合は、できた分を受け取り、その分だけ支払います。このとき画像ジョブは status: "succeeded"、error.type が "incomplete" となり、メッセージに足りない枚数が示されます。
• 1 枚ごとに、1 アカウントで同時に順番待ちまたは生成中にできる 20 件に数えられます。

画像を編集する#

GPT Image 2.5 を含め、どのモデルでも編集できます。1 枚以上の画像（任意で mask も）を multipart/form-data で POST /v1/images/edits に送ります。モデル、プロンプト、その他のオプションは生成と同じです。複数の画像をもとに作らせる場合は参考画像を参照してください。

curl https://lovelyrouter.com/v1/images/edits \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=gpt-image-2 \
  -F image=@fox.png \
  -F prompt="Make it night with a full moon" \
  -F quality=medium | jq -r '.data[0].b64_json' | base64 --decode > fox-night.png

GPT Image 2.5 では、model に gpt-image-2.5-flare または gpt-image-2.5-sunburst を指定し、quality は省略してください（これらのモデルでは無視されます）。

curl https://lovelyrouter.com/v1/images/edits \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=gpt-image-2.5-flare \
  -F image=@fox.png \
  -F prompt="夜にして、満月を加えて" | jq -r '.data[0].b64_json' | base64 --decode > fox-night.png

編集の料金は生成と同じです。

参考画像#

商品、ロゴ、人物、スタイルなど、最大 16 枚の画像をモデルに渡せます。各画像から何を使うかはプロンプトで指定してください。画像はそれぞれ image[] ファイルとして送ります。OpenAI SDK にリストを渡すと、この形式で送信されます。

curl https://lovelyrouter.com/v1/images/edits \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=gpt-image-2.5-flare \
  -F "image[]=@mug.png" \
  -F "image[]=@table.jpg" \
  -F prompt="1 枚目の画像のマグカップを 2 枚目の木のテーブルに置く、朝の光" \
  | jq -r '.data[0].b64_json' | base64 --decode > mug-on-table.png

JSON で送り、画像を URL または base64 の data: URL で指定することもできます。

curl https://lovelyrouter.com/v1/images/edits \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "同じキャラクターが手を振っている、フラットなイラスト",
    "images": [
      {"image_url": "https://example.com/character.png"},
      {"image_url": "data:image/png;base64,iVBORw0KGgo..."}
    ]
  }' | jq -r '.data[0].b64_json' | base64 --decode > waving.png

• image には URL 1 つまたは URL のリストも指定でき、mask には 1 つ指定できます。file_id による指定には対応していません。
• URL はリクエストの受信時に 1 回だけダウンロードされます。公開されていて、20 秒以内に応答する必要があります。
• 入力画像は PNG、JPEG、WebP で、合計 50 MB までです。
• 入力画像を含む POST /v1/images/generations へのリクエストは編集として処理されます。

料金#

GPT Image モデルは 1 枚 $0.04、z-image-turbo-nsfw-v2 は 1 枚 $0.03 で、サイズや品質にかかわらず、生成でも編集でも同じです。レスポンスの usage は参考情報で、料金には影響しません。チャネルグループの倍率が適用されます（gpt-value と creative-hosted は ×1.00）。

GET /v1/models では、現在の料金が pricing.per_image（米ドル）として表示されます。すべての呼び出しは料金とともにログに表示されます。

画像を送信すると、その料金が残高から確保され、画像の完了時に解放されます。n を指定したときは n 枚分の料金が確保され、受け取った枚数分だけ課金されます。リクエストが拒否された場合、ジョブがキャンセルされた場合、画像が生成されなかった場合は課金されません。画像がいったん生成されると、受け取る前にクライアントが切断しても課金されます。

リクエストの順番待ち#

画像のリクエストはすべてキューに入り、処理能力が空き次第開始されます。そのため、まとめて届いたリクエストも失敗せずに順番を待ちます。POST /v1/images/generations と POST /v1/images/edits は、画像ができるまで最長 9 分間接続を保持します。それまでに完了しない場合は 504 を返し、ジョブ id を x-lovely-image-job ヘッダーとメッセージに含めます。画像の生成は続き、完了時に課金され、GET /v1/images/jobs/{id} で取得できます。

• 1 アカウントにつき、順番待ちまたは生成中の画像は同時に 20 件までです（n を指定したリクエストは 1 枚ずつ数えます）。20 件を超えるリクエストは、いずれかが完了するまで 429 を返します。
• 30 分以内に開始できない画像は 429 で失敗し、課金されません。
• すべてのレスポンスに x-lovely-request-id ヘッダー（ジョブ id）が付き、ログの呼び出しと対応します。

画像ジョブ#

画像ジョブは、接続を保持したままにしない同じリクエストです。送信してから、ポーリングまたはロングポーリングします。一括生成や、クライアントが数分待てない場合に使ってください。

curl https://lovelyrouter.com/v1/images/jobs \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model": "gpt-image-2", "prompt": "A watercolor painting of a red fox in a snowy birch forest at dawn", "size": "1536x1024"}'

ボディには POST /v1/images/generations と同じフィールドを指定します。入力画像を付けると、POST /v1/images/edits と同様に編集になります。multipart/form-data の image ファイルでも、JSON の images でもかまいません。wait（0〜300 秒、ボディまたは ?wait=）を付けると、応答する前にジョブを待ちます。時間内に終われば 200、そうでなければ 202 が返ります。

その後、完了を待ちます。wait はジョブが終わるか時間切れになるまでリクエストを保持します。

curl "https://lovelyrouter.com/v1/images/jobs/img_8c1f0e2a9b7d4f3e6a5c2b1d?wait=60" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

完了したジョブは status: "succeeded" となり、charge_usd と、画像の url、content_type、bytes、size、usage を含む result を持ちます。result.images にはジョブの全画像がそれぞれの url、content_type、bytes とともに並びます。n が 2 以上のとき、1 枚目は /content、残りは /content/1、/content/2 … にあります。同じキーでその URL から画像ファイルをダウンロードします。

curl -o fox.png https://lovelyrouter.com/v1/images/jobs/img_8c1f0e2a9b7d4f3e6a5c2b1d/content \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Playground は画像ジョブを使っています。Images に切り替えると、コードを書かずにプロンプトや編集を試せます。

制限#

• 1 リクエストにつき最大 10 枚（n）。それ以上必要なときは、複数のリクエストやジョブを送ってください。
• ストリーミング非対応。stream: true は 400 を返します。部分画像（partial images）はまだ利用できません。
• バリエーション非対応。POST /v1/images/variations（DALL·E 2 専用）は 404 を返します。
• 画像の送信にはキーの 1 分あたりのリクエスト数の制限が適用されます。1 アカウントにつき、順番待ちまたは生成中の画像は同時に 20 件までです。