画像生成

テキストや参照画像から画像を作る /v1/images/generations の使い方です。

対応モデル

画像生成は /v1/images/generations です。テキスト生成とは別サーフェスのため、これらのモデル ID は GET /v1/models には含まれません(GET /v1/images/models で対応モデルと単価を確認できます)。トライアルキーは対象外です。

モデル IDモデル名仕様
krea-2-medium-turboKrea 2 Medium Turbo解像度 1K / 出力 PNG / 1 リクエスト 1 枚
アスペクト比 1:1 / 4:3 / 3:2 / 16:9 / 4:5 / 2:3 / 9:16
参照画像 最大 1 枚 / seed 指定可
精度 BF16
利用モデル krea/Krea-2-Turbo
krea-2-turbo-uncensoredKrea 2 Turbo Uncensored解像度 1K / 2K / 出力 PNG / 1 リクエスト 4 枚
アスペクト比 1:1 / 1:2 / 2:1 / 1:3 / 3:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 9:21 / 21:9
参照画像 最大 0 枚 / seed 指定可
精度 FP8
利用モデル ChrisColeTech/krea2-turbo-uncensored-v1.1-FP8
minimax-h3-imageMiniMax H3 Image解像度 1K / 2K / 4K / 出力 PNG / JPEG / 1 リクエスト 1 枚
アスペクト比 1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 16:9 / 9:16 / 21:9 / 9:21
参照画像 最大 1 枚 / seed 指定可
精度 FP8
利用モデル MiniMaxAI/MiniMax-H3-Image

使い方

OpenAI Images API 互換の形なので、OpenAI SDK の images.generate がそのまま使えます。画像は base64(b64_json)で同期に返ります(URL 配信はありません)。

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://api.router.hello.ai/v1",
    api_key="hello_...",
)

resp = client.images.generate(
    model="krea-2-medium-turbo",
    prompt="A red paper boat on a calm pond, soft morning light",
    size="1536x1024",  # 3:2。省略時は 1024x1024(1:1)
)
open("boat.png", "wb").write(base64.b64decode(resp.data[0].b64_json))
print(resp.usage.completion_tokens)  # 課金基礎の画像トークン数(例: 4175)
curl https://api.router.hello.ai/v1/images/generations \
  -H "Authorization: Bearer hello_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-2-medium-turbo",
    "prompt": "A red paper boat on a calm pond, soft morning light",
    "aspect_ratio": "16:9"
  }'

パラメータと課金

  • アスペクト比は aspect_ratio(16:9 等)か、 OpenAI 互換の size(1024x1024 / 1536x1024 / 1024x1536 等。約分した比が 対応表にあれば受け付けます)のどちらかで指定します。両方を送って 食い違うと 400 です。
  • 参照画像(image-to-image)は input_references に [{ "type": "image_url", "image_url": { "url": "https://…" } }] の形で渡します。https URL か data:image/…;base64, の data URL を受け付けます(minimax-h3-image は data URL のみ)。
  • n は 1 までです。複数枚が必要な場合はリクエストを分けてください。stream / response_format: url は対応していません(400 を返します)。output_format を受け付けるのは minimax-h3-image だけで、他のモデルでは 400 を返します。
  • 課金は生成された画像のトークン数(レスポンスの usage.completion_tokens)× 単価です。1K 画像 1 枚は 4,175 トークン前後(約 ¥3)です。プロンプトのテキストトークンには課金しません(minimax-h3-image はプロンプトにも課金します。下の節をご覧ください)。生成に失敗した リクエストは課金されません。krea-2-turbo-uncensored は ZDR Go Uncensored の定額枠(請求期間ごと 50 枚・繰越なし)でもご利用いただけます。他の画像モデルは定額プランの対象外で、 クレジットから消費します。詳細は定額プランのドキュメントをご覧ください。
  • OpenAI SDK の images.edit(/v1/images/edits)には対応していません。参照画像は input_references で渡してください。

Krea 2 Turbo Uncensored(FP8・1K / 2K・最大 4 枚)

resp = client.images.generate(
    model="krea-2-turbo-uncensored",
    prompt="A lighthouse on a cliff at dusk, cinematic",
    size="1536x1024",                 # 3:2。aspect_ratio="21:9" なども可
    n=2,                              # 最大 4
    extra_body={"resolution": "2K"},  # 既定 1K。1K / 2K は同額
)
for i, d in enumerate(resp.data):
    open(f"out{i}.png", "wb").write(base64.b64decode(d.b64_json))
print(resp.usage)  # {"images": 2}(課金は 1 枚 ¥10 × 枚数)
curl https://api.router.hello.ai/v1/images/generations \
  -H "Authorization: Bearer hello_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-2-turbo-uncensored",
    "prompt": "A lighthouse on a cliff at dusk, cinematic",
    "size": "1536x1024",
    "n": 2,
    "resolution": "2K"
  }'
  • 混雑時は生成キューの待ちが長くなり、完了まで十数分かかることがあります。ZDR router は応答ヘッダを先に返し、完了まで空白を送り続けて接続を保つので、OpenAI SDK の既定設定のままで受け取れます。プロキシやクライアントで独自に短いタイムアウトを設定している場合は延ばしてください。
  • 生成開始後に接続が切れても、生成が完了すれば課金されます。生成に失敗した場合は課金されません。そのため、生成開始後の失敗は HTTP 200 のまま本文に {"error": …} が入る形で返ります。
  • OpenAI SDK の自動再試行は同じリクエストとして扱い、二重に課金しません。SDK 以外から再試行する場合は Idempotency-Key ヘッダを付けてください。
  • 同時に生成中にできるのは 1 ユーザー 4 リクエストまでです(超えると 429)。
  • resolution は 1K / 2K。size はアスペクト比の指定にだけ使われ、出力のピクセル数は指定値と一致しません(縦横は 16 px 単位で、1K の 1:1 は 1488×1488、2K の 16:9 は 2720×1520)。
  • API で提供するのは text-to-image のみです。重みは編集(image-to-image)にも対応していますが、ZDR router では参照画像(input_references)を受け付けません。prompt_expansion: false でプロンプトの自動拡張を止められます。
  • レスポンスの usage は {"images": N} です(トークン数ではありません)。
  • 利用規約の禁止事項(児童を性的に描写する表現・実在する人物の性的表現等)は、このモデルでも同じく禁止です。

MiniMax H3 Image(FP8・1K / 2K / 4K)

resp = client.images.generate(
    model="minimax-h3-image",
    prompt="A weathered lighthouse on a basalt cliff at dusk, long exposure, "
           "warm light in the lantern room, waves breaking below, 35mm photo",
    size="5472x3072",                 # 4K の 16:9。下の表の寸法をそのまま指定できます
    output_format="jpeg",             # 既定は png。4K は jpeg を推奨
)
open("lighthouse.jpg", "wb").write(base64.b64decode(resp.data[0].b64_json))
print(resp.usage)  # prompt_tokens(プロンプト)と completion_tokens(画像)
curl https://api.router.hello.ai/v1/images/generations \
  -H "Authorization: Bearer hello_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-image",
    "prompt": "A weathered lighthouse on a basalt cliff at dusk, long exposure, 35mm photo",
    "aspect_ratio": "16:9",
    "resolution": "4K",
    "output_format": "jpeg"
  }'
# 参照画像を元に編集する
ref = base64.b64encode(open("boat.png", "rb").read()).decode()
resp = client.images.generate(
    model="minimax-h3-image",
    prompt="Make the paper boat blue, keep everything else unchanged",
    size="1024x1024",
    extra_body={"input_references": [f"data:image/png;base64,{ref}"]},
)
  • 解像度は resolution(1K / 2K / 4K。既定 1K)と aspect_ratio の組で指定します。size に下の表の寸法を書いても同じ指定になります (表に無い寸法はアスペクト比だけが使われ、解像度は resolution か既定の 1K です)。 返る画像は表の寸法と一致します。
  • 課金は画像のトークン数 × ¥800 / 1M と、 プロンプトのトークン数 × ¥600 / 1M の合計です。 画像のトークン数は出力の幅 × 高さ ÷ 1,024 で、リクエストの時点で決まります。レスポンスの usage.completion_tokens が画像、usage.prompt_tokens がプロンプトのトークン数です。 参照画像を渡した場合はその分が加わります(後述)。
  • プロンプトは 4,096 トークンまで、かつ 32,768 文字までです(どちらかを超えると 400)。短い指示より、画面全体を具体的に書いた英語の説明文のほうが意図どおりになります。
  • output_format は png(既定)か jpeg です。4K の PNG はレスポンスが 60 MB を超えることがあるので、4K では jpeg を推奨します(数 MB)。実際の形式はレスポンスの data[0].media_type に入ります。
  • 生成は 1 件ずつ処理します。所要時間の目安は 1K / 2K が 5 秒前後、4K が 25 秒前後で、混雑時は順番待ちが加わります。待ちが 60 秒を超えたリクエストは 429(Retry-After 付き)を返します。
  • n は 1 だけです。seed を指定すると同じプロンプト・同じ寸法から同じ画像が返ります。 未指定のときは毎回異なる画像になります。
  • 参照画像を 1 枚渡すと、その画像を元にプロンプトに沿って編集します(input_references)。受け付けるのは data:image/png;base64, か data:image/jpeg;base64, の data URL だけで、https の URL は 400 を返します。画像は各辺 128〜8,192 px、縦横比 4:1 までで、リクエスト本文(base64 にした後の大きさ)は 12 MB までです。出力の寸法は参照画像に合わせず、resolution と aspect_ratio の指定どおりになります。
  • 参照画像には ¥400 / 1M で課金します。トークン数は、短辺が 1,024〜2,048 px に収まるように拡大・縮小した寸法を 32 px 単位に揃えた幅 × 高さ ÷ 1,024 です(1024×1024 以下の正方形は 1,024 トークン、2048×2048 以上の正方形は 4,096 トークン。短辺が最初から範囲内の画像は拡大・縮小せず、32 px に満たない端数を切り捨てます)。レスポンスの usage.prompt_tokens_details.image_tokens に入り、usage.prompt_tokens はプロンプトと参照画像の合計になります。
  • 生成の途中で接続が切れても、生成が完了すれば課金されます。生成に失敗した場合は課金されません。
  • このモデルは MiniMax-H3-Image Community License Agreement の利用制限(第 V 条と Exhibit A の Acceptable Use Policy)の対象です。ZDR router の利用規約に加えて、この制限が適用されます。EU・英国・韓国・米国での利用は同ライセンスの対象地域外です。
アスペクト比1K2K4K
1:11024×1024
1,024 tok / 約 ¥0.8
2048×2048
4,096 tok / 約 ¥3.3
4096×4096
16,384 tok / 約 ¥13.1
4:31184×896
1,036 tok / 約 ¥0.8
2368×1760
4,070 tok / 約 ¥3.3
4736×3552
16,428 tok / 約 ¥13.1
3:4896×1184
1,036 tok / 約 ¥0.8
1760×2368
4,070 tok / 約 ¥3.3
3552×4736
16,428 tok / 約 ¥13.1
3:21248×832
1,014 tok / 約 ¥0.8
2496×1664
4,056 tok / 約 ¥3.2
5024×3360
16,485 tok / 約 ¥13.2
2:3832×1248
1,014 tok / 約 ¥0.8
1664×2496
4,056 tok / 約 ¥3.2
3360×5024
16,485 tok / 約 ¥13.2
16:91376×768
1,032 tok / 約 ¥0.8
2720×1536
4,080 tok / 約 ¥3.3
5472×3072
16,416 tok / 約 ¥13.1
9:16768×1376
1,032 tok / 約 ¥0.8
1536×2720
4,080 tok / 約 ¥3.3
3072×5472
16,416 tok / 約 ¥13.1
21:91568×672
1,029 tok / 約 ¥0.8
3136×1344
4,116 tok / 約 ¥3.3
6272×2688
16,464 tok / 約 ¥13.2
9:21672×1568
1,029 tok / 約 ¥0.8
1344×3136
4,116 tok / 約 ¥3.3
2688×6272
16,464 tok / 約 ¥13.2

ツールから使う