Recraft Creative Upscale API の使い方：curl、Python、そして実際の1回の実行

TL;DR

• recraft/creative-upscale は画像を拡大し、そのテクスチャとディテールを描き直します。リクエストボディは image_url の1フィールドだけです。プロンプトもスケール設定もありません。
• 統一された /v1/tasks フローで動作します：POST で taskId を取得し、GET /v1/tasks/<taskId> をポーリングし、data.output[0].url からダウンロードします。
• 私たちの実行では、1254×1254 の PNG が約 60 秒後に 4096×4096 の WebP、約 19.8 MB として返りました。待ち時間とファイルサイズを見込んでおいてください。

必要なもの

コンソールから hiapi API キーを取得し、公開アクセス可能な画像 URL を用意します。モデルページに入力制限が記載されています：PNG 推奨、最大 20 MB、各辺 256–4096 px、最大 16 MP。

文字、ロゴ、製品のディテールをそのまま保つ必要がある場合は、Recraft Crisp Upscale を使用してください。Creative Upscale は描き直すため、小さな要素が変化する可能性があります。

最小限の curl リクエスト

export HIAPI_KEY=sk-your-key

curl -s https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft/creative-upscale",
    "input": { "image_url": "https://example.com/old-illustration.png" }
  }'

レスポンスはタスクハンドルです：

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

data.status が success になるまでポーリングします：

curl -s https://www.hiapi.ai/v1/tasks/tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD \
  -H "Authorization: Bearer $HIAPI_KEY"

Python：送信、ポーリング、保存

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def upscale(image_url: str, out_path: str) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30, json={
        "model": "recraft/creative-upscale",
        "input": {"image_url": image_url},
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        time.sleep(5)
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # transient network error: keep polling the SAME taskId
        if d["status"] == "success":
            url = d["output"][0]["url"]
            with open(out_path, "wb") as f:
                f.write(requests.get(url, timeout=120).content)
            return task_id
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(f"task {task_id} failed: {d}")
    raise TimeoutError(f"task {task_id} still running; re-poll it, do not resubmit")

upscale("https://example.com/old-illustration.png", "upscaled.webp")

本番環境では2つの点が重要です。第一に、タイムアウト後に絶対に再送信しないでください：送信するたびに新しい課金タスクが作成されるため、taskId を保持して再ポーリングしてください。第二に、ファイルをすぐに保存してください；出力 URL には expireAt があり、ホストは一時的なものです。

本番環境での注意点

• バッチタスクにはコールバックを使用します。 ポーリングする代わりに、タスクボディに callback: {"url": "...", "when": "final"} を渡すことで、タスク終了時に hiapi から呼び出させることができます。taskId を重複排除キーとして扱ってください。
• 5 秒間隔のポーリングで十分です。 1つのタスクに約1分かかるため、より速いポーリングはリクエストを増やすだけです。
• 送信前に URL を検証してください。 プラットフォームは不正な形式の URL を事前に拒否します（下記参照）が、アクセスできない https:// URL は別種の失敗であり、こちら側で素早い HEAD リクエストによって事前に捕捉するのが最善です。

実際の1回の実行で見られたこと

モデルページのサンプル入力画像（1254×1254 の山小屋の PNG）を使って、実際のリクエストを1回実行しました。

項目	観察結果
送信レスポンス	{"code":200,"data":{"taskId":"tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD"}}
ステータス遷移	handling → archiving → success
created から completed までの時間	61 秒（1792721625 → 1792721686）
出力	画像1枚、WebP、https://temp.hiapi.ai/.../...-0.webp、約7日後の expireAt 付き
入力サイズ	1254×1254 PNG、2.7 MB
出力サイズ	4096×4096 WebP、約 19.8 MB

その実行から知っておくべきこと：

1. archiving 段階ではまだ output がありません。 タスクは結果がストレージに移動される前に、数回のポーリングで completed と status: "archiving" を報告します。status == "success" のときだけ output[0].url が付随するので、最初に completed タイムスタンプを見た時点で URL を読んではいけません。
2. 結果はきれいな2倍ではありません。 1254 px の入力が 4096 px になり、各辺で約 3.3 倍です。モデルページにも同じ組み合わせが示されており、スケールフィールドは公開されていないため、出力サイズはこちらではなくモデルが決めると想定してください。ちょうど2倍が必要なら、Crisp Upscale がその約束に沿ったエンドポイントです。
3. 出力ファイルは大きいです。 画像1枚で 19.8 MB あり、20 MB の入力制限を超えるためそのまま再入力できません。サイズを調整せずに出力に対して2回目の処理を連鎖させないでください。
4. ディテールはシャープ化されるだけでなく描き直されます。 モデルページのこの画像ペアについての説明では、構図、光、色はほぼ保たれる一方、丸太、石積み、手すりが描き直され、小さな要素（例えばポーチ脇の木）が変化するとされています。ブランド資産を差し替える前に出力を確認してください。
5. 誤った URL は素早く失敗します。 "image_url": "not-a-url" を送ると即座に HTTP 400 が返ります：{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: image_url: 'not-a-url' does not match pattern '^https?://'"}。このパターンが私たちが検証した唯一のチェックです；256 px の最小値や 16 MP の上限はテストしていません。

タスクを1回しか実行していないため、61 秒という数字は単一サンプルであり、ベンチマークではありません。

Creative Upscale か Crisp Upscale か？

どちらも image_url を1つだけ受け取り、プロンプトは不要です。違いはピクセルの扱い方と価格にあります。

	Creative Upscale	Crisp Upscale
モデル id	recraft/creative-upscale	recraft/crisp-upscale
動作	拡大し、テクスチャとディテールを描き直す	幅と高さを2倍にし、コンテンツと文字を保持する
最適な用途	古いイラスト、小さいサイズや低解像度のアート画像	製品写真、文字入りのポスター、デザイン資産
価格	画像1枚あたりはるかに高い；料金を参照	Crisp の料金記事を参照

Creative Upscale の画像1枚あたりの価格は Crisp よりはるかに高いため（最新の数字は料金ページで比較してください）、ディテールを本当に再生成したい場合にのみ使用してください。モデルをまたぐ汎用的な解像度ワークフローについては、hiapi で画像解像度を上げるを参照してください。

関連

• Recraft Creative Upscale モデルページ
• Recraft Crisp Upscale API ガイド
• Recraft Remove Background API ガイド：まず拡大し、次に被写体を切り抜く
• hiapi API で画像解像度を上げる
• hiapi の料金

FAQ

プロンプトは必要ですか？ いいえ。モデルページには単一画像の入力が記載されており、プロンプトやその他の設定はありません。私たちのリクエストは image_url のみを使用しました。

出力サイズは選べますか？ API では選べません。スケールフィールドはなく、1254 px の入力が 4096 px で返りました。

文字やロゴは保持されますか？ 保証はありません。ディテールは再生成され、小さな要素が変化する可能性があるため、文字を含む資産には Crisp Upscale を使用してください。

どのような出力形式が得られますか？ 私たちの実行では WebP で、期限切れになる一時的な URL から配信されるため、すぐにダウンロードしてください。

どのくらい時間がかかりますか？ 私たちの単回実行では約1分でした；クライアントはこの程度の待ち時間を見込んで構築してください。