画像生成

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

対応モデル

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

使い方

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

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://hai-api.hcloud.ltd/v1",
    api_key="hai_...",
)

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://hai-api.hcloud.ltd/v1/images/generations \
  -H "Authorization: Bearer hai_..." \
  -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 を受け付けます。
• n は 1 までです。複数枚が必要な場合はリクエストを分けてください。stream / response_format: url / output_format は対応していません（400 を返します）。
• 課金は生成された画像のトークン数（レスポンスの usage.completion_tokens）× 単価です。1K 画像 1 枚は 4,175 トークン前後（約 ¥3）です。プロンプトのテキストトークンには課金しません。生成に失敗した リクエストは課金されません。krea-2-turbo-uncensored は HAI 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://hai-api.hcloud.ltd/v1/images/generations \
  -H "Authorization: Bearer hai_..." \
  -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"
  }'

• 混雑時は生成キューの待ちが長くなり、完了まで十数分かかることがあります。HAI は応答ヘッダを先に返し、完了まで空白を送り続けて接続を保つので、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）にも対応していますが、HAI では参照画像（input_references）を受け付けません。prompt_expansion: false でプロンプトの自動拡張を止められます。
• レスポンスの usage は {"images": N} です（トークン数ではありません）。
• 利用規約の禁止事項（児童を性的に描写する表現・実在する人物の性的表現等）は、このモデルでも同じく禁止です。

ツールから使う

• ComfyUI
• Hermes Agent 用プラグイン