チュートリアル

krea-2-medium-turbo テキストから画像生成 API の使い方（curl + Python）

Oct 21, 2026

krea-2-medium-turbo は、Krea が hiapi 上で提供する高速・低コストなテキストから画像生成向けのティアです。プロンプトを 1 つ送信し、アスペクト比を選ぶだけで、非同期タスク API を通じてレンダリング済みの画像を 1 枚取得できます。本ガイドでは、/v1/tasks 向けにそのままコピー＆ペーストできる curl と Python のリクエスト例、正確な入力スキーマ、そして私が 2026-10-21 に実測した所要時間とエラー時の挙動を紹介します。そのうち 1 つの結果はドキュメントの記述と矛盾しています。

前提条件

hiapi の API キー（sk-...）が 1 つ必要です。API Keys コンソールで作成してください。各リクエストは Authorization: Bearer sk-<your-key> で認証します。これが唯一の前提です。モデルはサーバー側で動作するため、HTTP クライアント以外には何もインストールする必要はありません。

入力スキーマ

krea-2-medium-turbo は 5 つのフィールドを受け付けます。このうち必須なのは prompt と model だけです：

フィールド	必須	型	デフォルト	説明
`model`	はい	string	—	完全に `krea-2-medium-turbo` である必要があります。
`prompt`	はい	string	—	1〜5000 文字。
`aspect_ratio`	いいえ	enum	`1:1`	`1:1`、`4:3`、`3:2`、`16:9`、`2.35:1`、`4:5`、`2:3`、`9:16` のいずれか。
`creativity`	いいえ	enum	`low`	`raw`（最も字義どおり）→ `low` → `medium` → `high`（最も創造的）。
`seed`	いいえ	integer	—	任意。依存する前に、下記の seed に関する注意事項をお読みください。

input オブジェクトは厳格です（additionalProperties: false）。この表にないフィールドは、生成開始前に拒否されます。n / num_images はなく、resolution や size もなく、ネガティブプロンプト用のフィールドもありません。1 回のリクエストで返るのはちょうど 1 枚の画像で、出力サイズは aspect_ratio だけで決まります。hiapi 上で resolution（Seedream、Qwen-Image）や size を受け付ける他の画像 API を使ったことがある場合は、そうしたフィールドはここでは外してください。付けると 400 が返ります。

最小限の動作するリクエスト（curl）

タスク作成は即座に taskId を返し、画像はバックグラウンドでレンダリングされます。

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-2-medium-turbo",
    "input": {
      "prompt": "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
      "aspect_ratio": "2.35:1",
      "creativity": "medium",
      "seed": 42
    }
  }'

レスポンス：

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A" }, "message": "success" }

次に、終端状態に達するまで id でタスクをポーリングします：

curl -s "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A" \
  -H "Authorization: Bearer sk-<your-key>"

完了したタスクは次のようになります（明確化のためフィールドを一部省略しています）：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A",
    "model": "krea-2-medium-turbo",
    "status": "success",
    "storage": "temp",
    "created": 1792549655,
    "completed": 1792549681,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/xxxxxxxx/01M5E4J4FQVJNSDKQ29BRSMD0A-0.png",
        "artifactId": "280334",
        "expireAt": 1793154481
      }
    ]
  },
  "message": "success"
}

画像は data.output[0].url にあります。

Python での同じフロー

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-<your-key>",
    "Content-Type": "application/json",
}

def generate(prompt, aspect_ratio="1:1", creativity="low", seed=None):
    body = {
        "model": "krea-2-medium-turbo",
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "creativity": creativity},
    }
    if seed is not None:
        body["input"]["seed"] = seed

    created = requests.post(API, headers=HEADERS, json=body, timeout=30)
    created.raise_for_status()
    task_id = created.json()["data"]["taskId"]

    # タスクが終端状態に達するまでポーリングします。
    while True:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":                 # 注意：それでも HTTP 200 です。下記参照
            raise RuntimeError(f"generation failed: {data}")
        time.sleep(3)

url = generate(
    "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
    aspect_ratio="2.35:1",
    creativity="medium",
)
print(url)

本番環境での注意事項

ポーリングまたはコールバックを使う。 上記のループは 3 秒ごとにポーリングするので、低い同時実行数なら問題ありません。本番環境では、作成リクエストに callback.url を付けて when: "final" を設定すれば、ポーリングの代わりに hiapi が完了したタスクを POST してくれます。コールバックの規約はタスク API ドキュメントを参照してください。
生成失敗でも HTTP 200 が返る。 ポーリングエンドポイントの HTTP ステータスコードは、リクエストが成功したかどうかを表し、画像が成功したかどうかを表すものではありません。レンダリング失敗は 200 と data.status: "fail" で返ります。HTTP ステータスコードではなく data.status で分岐してください。そうしないと失敗を成功として扱ってしまいます。
出力 URL は一時的。 結果は temp.hiapi.ai 上の "storage": "temp" に保存され、expireAt タイムスタンプが付き、およそ 7 日後に期限切れになります（私の実行では 604,800 秒）。タスクが完了したらすぐにバイトをダウンロードして再ホスト（自前の bucket/CDN）してください。本番ページで temp.hiapi.ai の URL を直接ホットリンクしないでください。
料金は 1 枚あたりの単一固定レートで、アスペクト比やクリエイティビティのレベルには依存しません。解像度の段階を考慮する必要はありません。数値をハードコードせず、料金ページで現在の数字を確認してください。

私が実際にテストした内容（2026-10-21）

以下はすべてドキュメントではなく、実際の呼び出しから得たものです：

所要時間と解像度。 2.35:1 のリクエストは約 26 秒で完了し（created → completed の差）、返された PNG は 1568 × 672 px でした。つまり 2.35:1 は確かにシネマスコープ風のクロップで、正方形に近いものではありません。タスクはレンダリングと一時ストレージへのファイル移動の間、中間状態 handling → archiving → success を経由します。
enum の検証はサーバー側で強制される。 "aspect_ratio": "21:9"（もっともらしいがサポートされていない値）を送ると、即座に 400 が返ります：invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:2', '16:9', '2.35:1', '4:5', '2:3', '9:16'。エラーメッセージはフィールドを明示し、有効な値を列挙するので、プログラムで処理しやすいです。
未知のフィールドは無視されず 400 が返る。 "resolution": "2K" は invalid input: <root>: additional properties 'resolution' not allowed を返し、"n": 2 も n について同じエラーを返します。これが additionalProperties: false ルールの効果です。他のモデルからリクエストボディをコピーすると、余分なフィールドが呼び出し全体を妨げます。
私のテストでは、seed は完全に同じ画像を再現できませんでした。 同じプロンプト、seed: 42、aspect_ratio: 2.35:1、creativity: medium を 2 回続けて送信しました。どちらも有効な 1568 × 672 の画像が返りましたが、明らかに異なる場面でした（片方は白い塔、もう片方は赤白の縞模様の塔）。ファイルサイズも異なり（1.30 MB 対 1.51 MB）、ハッシュも異なりました。このフィールドは受け入れられ、再現可能とドキュメントに記述されていますが、ピクセル単位の正確な再現は保証ではなくベストエフォートとみなしてください。特定の画面が必要な場合は、得られた結果を保存し、seed で再リクエストしないでください。

FAQ

どのアスペクト比をリクエストできますか？ 8 つあります：1:1（デフォルト）、4:3、3:2、16:9、2.35:1、4:5、2:3、9:16。それ以外の値は 400 を返します。

1 回の呼び出しで複数の画像を生成できますか？ できません。n フィールドはなく、スキーマは未知のプロパティを拒否するため、リクエストごとにちょうど 1 枚の画像が生成されます。複数枚を生成するには、リクエストをループで送信してください（任意で異なる seed を使用）。

creativity は何をするのですか？ モデルがプロンプトにどれだけ字義的に従うかを制御します。raw は文言に最も忠実、high は最も解釈の自由度が高く、low（デフォルト）と medium はその間です。

krea-2-medium-turbo は画像から画像生成や編集に対応していますか？ いいえ、テキストから画像生成のみに対応しています。スキーマには image_urls / 入力画像フィールドはありません。既存の画像を変換する必要がある場合は、hiapi 上の専用の編集/画像から画像生成モデルを使用してください。

出力 URL はどのくらい有効ですか？ 一時ストレージから提供され、期限切れになります（私のテストではおよそ 7 日後）。タスクが完了したらすぐに画像をダウンロードして再ホストしてください。

重要なポイント

krea-2-medium-turbo はテキストから画像生成のみに対応：prompt と model が必須で、aspect_ratio、creativity、seed は任意です。
input オブジェクトは厳格です（additionalProperties: false）。resolution、size、n はいずれも 400 を返し、各呼び出しでちょうど 1 枚の画像が返ります。
aspect_ratio 2.35:1 は 1568x672 px でレンダリングされ、所要時間は約 26 秒です。出力 URL は temp.hiapi.ai にあり、およそ 7 日後に期限切れになります。
レンダリング失敗でも HTTP 200 と data.status 'fail' が返ります。HTTP ステータスコードではなく status フィールドで分岐してください。
テストでは、同じプロンプトと同じ seed でも異なる画像が生成されたため、seed による正確な再現に頼らないでください。欲しい結果は保存しておきましょう。