画像生成
テキストや参照画像から画像を作る /v1/images/generations の使い方です。
対応モデル
画像生成は /v1/images/generations です。テキスト生成とは別サーフェスのため、これらのモデル ID は GET /v1/models には含まれません(GET /v1/images/models で対応モデルと単価を確認できます)。トライアルキーは対象外です。
| モデル ID | モデル名 | 仕様 |
|---|---|---|
krea-2-medium-turbo | Krea 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-uncensored | Krea 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-image | MiniMax 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・英国・韓国・米国での利用は同ライセンスの対象地域外です。
| アスペクト比 | 1K | 2K | 4K |
|---|---|---|---|
1:1 | 1024×1024 1,024 tok / 約 ¥0.8 | 2048×2048 4,096 tok / 約 ¥3.3 | 4096×4096 16,384 tok / 約 ¥13.1 |
4:3 | 1184×896 1,036 tok / 約 ¥0.8 | 2368×1760 4,070 tok / 約 ¥3.3 | 4736×3552 16,428 tok / 約 ¥13.1 |
3:4 | 896×1184 1,036 tok / 約 ¥0.8 | 1760×2368 4,070 tok / 約 ¥3.3 | 3552×4736 16,428 tok / 約 ¥13.1 |
3:2 | 1248×832 1,014 tok / 約 ¥0.8 | 2496×1664 4,056 tok / 約 ¥3.2 | 5024×3360 16,485 tok / 約 ¥13.2 |
2:3 | 832×1248 1,014 tok / 約 ¥0.8 | 1664×2496 4,056 tok / 約 ¥3.2 | 3360×5024 16,485 tok / 約 ¥13.2 |
16:9 | 1376×768 1,032 tok / 約 ¥0.8 | 2720×1536 4,080 tok / 約 ¥3.3 | 5472×3072 16,416 tok / 約 ¥13.1 |
9:16 | 768×1376 1,032 tok / 約 ¥0.8 | 1536×2720 4,080 tok / 約 ¥3.3 | 3072×5472 16,416 tok / 約 ¥13.1 |
21:9 | 1568×672 1,029 tok / 約 ¥0.8 | 3136×1344 4,116 tok / 約 ¥3.3 | 6272×2688 16,464 tok / 約 ¥13.2 |
9:21 | 672×1568 1,029 tok / 約 ¥0.8 | 1344×3136 4,116 tok / 約 ¥3.3 | 2688×6272 16,464 tok / 約 ¥13.2 |