Krea 3 API の使い方？5 分で最初の 1 枚を生成

TL;DR

• Krea 3（krea-3/text-to-image）はテキスト-to-画像モデルです。一文の説明から写実的な写真、イラスト、コンセプトアートを生成し、生成前にプロンプトを理解して拡張します。2 つのバリアント berry（品質優先、デフォルト）/ jam（速度優先）を同価格で切り替えられます。モデルページを開くだけで試せて、新規ユーザー登録で 200 クレジットがもらえます。
• 価格は 1 枚単位：Krea 3 は $0.036。同じファミリーにはより安価な Krea 2 Medium Turbo（krea-2-medium-turbo）$0.0215 もあります（完全な価格表は価格ページ参照）。
• 呼び出しは HiAPI の /v1/tasks エンドポイント経由：タスクを送信して taskId を取得し、結果を照会、成功したら output[0].url から画像をダウンロードします。

できること

• 一文のプロンプトでも完全な画面を生成：生成前に推論で拡張するため、a lighthouse だけでも時間・光・構図を補います。具体的に書けばその記述に沿います。
• berry / jam の 2 バリアントを 1 つの ID で：variant で切り替え、パラメータと価格は完全に同じ。同じ seed でも両者の構図と色調は異なるので、それぞれ一度ずつ実行して 2 つの案として選べます。
• 6 種のサイズプリセット（最大 1K）：正方形・縦・横の計 6 種（1024×1024 から 1024×576）、出力は PNG または JPEG。
• タイトル文字入りのポスターも生成可能：文字を引用符で囲めば、短いタイトルは通常正確です。

以下は berry の実際の成果物です：

Studio product photograph of a frosted glass perfume bottle with a brushed brass cap standing on a block of travertine, hard afternoon sunlight casting a long palm-leaf shadow across a warm beige wall, crisp reflections, high-end editorial look

（日本語の意味：スタジオ製品写真：つや消しガラスの香水瓶にブラッシュド真鍮のキャップ、トラバーチンの塊の上に立ち、午後の強い光がヤシの葉の長い影を暖かいベージュの壁に落とす、鮮明な反射、ハイエンドな雑誌の質感。サイズはデフォルトの square_hd。）

krea-3/text-to-image、berry、square_hd、1024×1024、$0.036。

このプロンプトで生成 →

2 つのモデルの選び方

	krea-3/text-to-image（Krea 3）	krea-2-medium-turbo（Krea 2 Medium Turbo）
1 枚あたり	$0.036	$0.0215
サイズ	6 種のプリセット（最大 1024×1024）、カスタム不可	aspect_ratio 8 種の比率、2.35:1 シネマワイドを含む
特有のパラメータ	variant（berry/jam）、reasoning_level（推論拡張）、negative_prompt（berry のみ）	creativity 4 段階（raw/low/medium/high）
プロンプト処理	生成前に推論で拡張、短い文でも完全な画面を生成	原文どおりに生成、書いた細かさどおり
適する用途	確定版の生成、短いプロンプトでの素早い探索、文字入りポスター	バッチ生成、ワイドな構図、予算重視の日常的な制作

2 つのモデルは組み合わせて使えます：Krea 2 で草稿の方向性を決め、Krea 3 で確定版を生成、草稿 1 枚 + 確定版 1 枚で $0.0575。シーン別のプロンプト選びはプロンプト大全を参照。

2 つの導入ルート

ブラウザ 3 ステップ：モデルページを開く → プロンプトを貼り付け、サイズを選択 → 生成をクリック、1 枚 $0.036。

API 3 ステップ：POST /v1/tasks で送信 → taskId を取得 → GET /v1/tasks/<taskId> で success を確認してダウンロード。

curl：最初の 1 枚

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "krea-3/text-to-image",
  "input": {
    "prompt": "Studio product photograph of a frosted glass perfume bottle with a brushed brass cap standing on a block of travertine, hard afternoon sunlight casting a long palm-leaf shadow across a warm beige wall, crisp reflections, high-end editorial look",
    "image_size": "square_hd",
    "variant": "berry",
    "reasoning_level": "medium"
  }
}'

Krea 2 Medium Turbo に切り替えるには model と input フィールドだけを変更します：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "krea-2-medium-turbo",
  "input": {
    "prompt": "Futuristic city skyline at dusk, neon reflections on wet streets, cinematic widescreen",
    "aspect_ratio": "2.35:1",
    "creativity": "low"
  }
}'

返却された taskId が照会用の識別子です。

Python：送信、ポーリング、ダウンロード

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "krea-3/text-to-image",
    "input": {
        "prompt": "Studio product photograph of a frosted glass perfume bottle with a brushed brass cap standing on a block of travertine, hard afternoon sunlight casting a long palm-leaf shadow across a warm beige wall, crisp reflections, high-end editorial look",
        "image_size": "square_hd",
        "variant": "berry",
        "reasoning_level": "medium",
    },
}

# 送信：Idempotency-Key を付けると、ネットワークリトライでタスクが重複作成されない
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# ポーリング：queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # 一時的なアドレス、できるだけ早くダウンロードして保存
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:  # 拡張子は実際に返された形式に合わせて命名
        f.write(img.content)
    print("saved")

パラメータ表（krea-3/text-to-image）

フィールド	必須	値	説明
prompt	はい	1–5000 文字	画面の説明；具体的に書くほど記述に沿う
image_size	いいえ	square_hd / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9、デフォルト square_hd	サイズプリセット、最大 1024×1024；auto とカスタム幅・高さは不可
variant	いいえ	berry / jam、デフォルト berry	berry は品質優先、jam は速度優先；同価格
reasoning_level	いいえ	low / medium、デフォルト medium	プロンプト推論拡張の程度；短いプロンプトは medium、具体的に書くなら low
negative_prompt	いいえ	1024 文字以下	出現させたくない内容；berry のみ有効
output_format	いいえ	png / jpeg、デフォルト png	出力形式
seed	いいえ	整数 0–2147483647	同じバリアント内でのみ再現；berry と jam は互いに再現しない

Krea 2 Medium Turbo はフィールドが異なります：prompt（必須）、aspect_ratio（8 種、デフォルト 1:1）、creativity（raw/low/medium/high、デフォルト low）、seed。リクエストボディに表外のフィールドがあると直接 400 になります。

遭遇するエラー（API 原文）

やったこと	返却
image_size に auto を渡した	400 invalid input: image_size: value must be one of 'square_hd', 'square', 'portrait_4_3', 'portrait_16_9', 'landscape_4_3', 'landscape_16_9'
表外のフィールド（例：num_images）を渡した	400 invalid input: <root>: additional properties 'num_images' not allowed
prompt が空	400 invalid input: prompt: minLength: got 0, want 1
variant のスペルミス	400 invalid input: variant: value must be one of 'berry', 'jam'
残高不足	402 insufficient account balance; top up and retry

パラメータ検証を通らなかったリクエストは課金されません。同じ Idempotency-Key での再送信は 409（処理中）または 422（パラメータ不一致）を返すので、新しい key で再試行してください。

公開前の注意

• コールバック：リクエストボディのトップレベルに "callback": {"url": "https://..."} を渡すと、タスクが終了状態になったときにあなたのサービスへ通知され、ポーリングを省けます。
• 速やかに転送保存：output[0].url は一時的なアドレスなので、取得したらすぐにダウンロードして自分のストレージに保存してください。
• サイズは 6 種のみ：2.35:1 のシネマワイドやより多くの比率が必要なら、Krea 2 Medium Turbo の aspect_ratio を使ってください。
• seed はバリアント内でのみ再現：berry と jam で同じ seed を使うと異なる画像になります。シリーズ画像を作るなら variant + seed を固定してください。

よくある質問

短いプロンプトでも生成できますか？

できます。モデルが推論で拡張するので、a lighthouse の一文でも完全な画面を生成できます。細部を制御したいならプロンプトを具体的に書いてください。

berry と jam の違いは速度だけですか？

速度だけではありません。同じ seed でも両者の構図と色調は異なり、画質は同等なので、2 つの案としてそれぞれ実行してから選んでください。

negative_prompt は両方のバリアントに有効ですか？

berry のみ有効で、jam に渡しても効果はありません。

一度に何枚生成できますか？

一度に 1 枚のみです。複数枚必要ならタスクを複数送信するか、seed を変えて再実行してください。

$10 で何枚生成できますか？

Krea 3 は 1 枚 $0.036 なので約 277 枚です。新規ユーザー登録で 200 クレジットがもらえます（1 ドル = 2,000 クレジット）。

次のステップ：香水瓶のプロンプトを使ってモデルページで 1 枚試して、その後シーンに合わせてプロンプト大全のテンプレートを参考にしてください。