hiapi の API を使って画像の解像度を上げる方法：4K アップスケールのワークフロー

低解像度の商品画像、AI が生成した小さなサムネイル、あるいは古いスキャン資料があり、それを鮮明な 2K/4K 版にしたい場合でも、専用の超解像サービスを用意する必要はありません。hiapi の統合された /v1/tasks エンドポイントを使えば、複数の画像モデルに対して同じリクエストを送信できます。これらのモデルは既存の画像を受け取り、より高い解像度の設定でそれを描き直します。この記事では、完全に実行可能な流れを紹介します。タスクを送信し、ポーリング（またはコールバックの受信）で結果を取得し、その後アップスケールされたファイルをダウンロードします。

最初に正直に言っておきます。hiapi は現在、（まだ）ピクセルを保持する専用の超解像モデルを公開していません。ここで得られるのは生成的なアップスケールです。つまりモデルは、構図を保ちディテールを補うよう指示するプロンプトに従いつつ、より高い目標解像度で元画像を描き直します。写真やイラストにとっては、これは通常「画像の解像度を上げる」と呼ばれるものですが、可逆な補間ではないため、たとえば小さな文字が入ったスクリーンショットをビット単位で正確にピクセルスケーリングする必要がある場合には、これを使うべきではありません。

何を構築するか、そして事前に何を準備するか

これから作るのは、次の処理を行う小さなスクリプトです：

1. 既存の画像を指す参照をアップロードする（任意の公開 URL で構いません——ご自身の CDN、R2、S3 など）
2. 4K での再描画を要求する image-to-image タスクを送信する
3. タスクが完了するまでポーリングし、より高解像度の結果をダウンロードする

開始する前に：

• hiapi アカウントと API キーを、ダッシュボードの API Keys ページで作成してください。以下のすべてのリクエストには Authorization: Bearer sk-<your-key> が必要です——キーがなければこれらのエンドポイントは呼び出せません。
• アップスケールしたい画像を指す、公開アクセス可能な URL。hiapi のタスクワーカーはサーバー側で画像を取得するため、localhost のパスやプライベートなバケットは使えません——まず任意の公開ホストにアップロードしてください。
• Python 3.8+ と requests のインストール（pip install requests）。あるいは、シェルでテストしたいだけなら curl をそのまま使っても構いません。

最小限の実行可能なサンプル

最もすっきりした選択肢は seedream-5.0-lite/image-to-image です。この入力スキーマはちょうど 4 つのフィールドを要求します——prompt、image_urls、aspect_ratio、resolution——そして resolution は 2K または 4K しか受け付けません（このルートには 1K の設定がないので、誤って画像を縮小してしまう心配がありません）。

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_upscale_task(source_image_url: str) -> str:
    payload = {
        "model": "seedream-5.0-lite/image-to-image",
        "input": {
            "prompt": "Same image, preserved composition and colors, sharp fine detail, no artifacts",
            "image_urls": [source_image_url],
            "aspect_ratio": "1:1",   # match your source image's ratio
            "resolution": "4K",
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    body = resp.json()
    task_id = body["data"]["taskId"]
    return task_id

def wait_for_result(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_upscale_task("https://your-cdn.example.com/product-photo-small.jpg")
    result_url = wait_for_result(task_id)
    print("4K result:", result_url)

リクエストがどのようなものかだけ見たい場合は、curl で送信する同等のタスク作成呼び出しは次のとおりです：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-hiapi-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/image-to-image",
    "input": {
      "prompt": "Same image, preserved composition and colors, sharp fine detail, no artifacts",
      "image_urls": ["https://your-cdn.example.com/product-photo-small.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "4K"
    }
  }'

このリクエストについて、いくつか補足すべき点があります：

• image_urls は配列です。たとえこのモデルが最初の要素しか読まないとしてもです。裸の文字列をリストではなく渡すのは、400 エラーのよくある原因です。
• 出力 URL は期限切れになります。wait_for_result() が返したらすぐにバイト列をダウンロードして自分で保存してください——hiapi がホストするリンクを永続的なリソース URL として扱わないでください。
• 元画像が正方形でない場合は、aspect_ratio をそれに合わせて設定してください（4:3、16:9、9:16、3:2、2:3、21:9）。そうすればモデルが被写体を切り取ったりパディングしたりしません。

本番環境での実践

規模が大きくなる場合はポーリングよりコールバックを優先しましょう。アップスケールする画像が数枚を超える場合は、タスクごとにループで GET /v1/tasks/<id> を連打せず、callback オブジェクトを渡して hiapi に結果をプッシュさせましょう：

payload = {
    "model": "seedream-5.0-lite/image-to-image",
    "input": {...},
    "callback": {
        "url": "https://your-service.example.com/hooks/hiapi-task",
        "when": "final",
    },
}

Webhook はポーリングと同じタスクオブジェクト（status、output、error）を受け取ります——ネットワークのリトライで複数回配信される可能性があるため、その構造を防御的に検証してください。

ご自身の側でタスクごとに冪等性に優れたキーを用意しましょう。タスク API は現在、クライアント提供の冪等キーを受け付けません。そのため、タスクランナーが失敗した HTTP 呼び出しをリトライする可能性がある場合は、重複タスクを送信する前に、その元画像に対して既に taskId を保存していないか確認してください——そうしないと、こちら側の一時的なタイムアウトが、同じファイルを二重に課金されるアップスケールになってしまいます。

まったく異なる 2 種類のエラー形態を処理しましょう。形式が不正なリクエストボディは HTTP 400 を返し、フラットな {"code": 400, "error_code": "INVALID_REQUEST", "message": "..."} を伴います。API キーの欠落や誤りは HTTP 401 を返し、ネストされた {"error": {"code": "permission_denied", "message": "..."}} を伴います。まずステータスコードを確認し、それから分岐してください：

if resp.status_code == 401:
    raise RuntimeError(f"auth error: {resp.json()['error']['message']}")
if resp.status_code == 400:
    raise RuntimeError(f"bad request: {resp.json()['message']}")
resp.raise_for_status()

手元にある入力に応じてモデルを選びましょう。以下の 3 つのルートはすべて同じ /v1/tasks エンドポイント上にあり、異なるのは model 文字列と input フィールドだけです：

手元にあるもの	モデル	必須入力フィールド
既存の画像があり、クリーンな 2K/4K の再描画が欲しい	seedream-5.0-lite/image-to-image	prompt、image_urls、aspect_ratio、resolution（2K|4K）
既存の画像があり、品質とコストのトレードオフを取りたい	gpt-image-2/image-to-image@ext	prompt、image_urls、quality（low|medium|high）、resolution（1K|2K|4K）
元画像がない——テキスト記述からまったく新しい高解像度アセットを生成する	wan2.7-image/text-to-image	prompt（加えて任意の resolution と aspect_ratio）

2 行目の @ext サフィックスに注意してください——これはベースの gpt-image-2 モデル上のルートバリアントであり（hiapi は一部のモデルを複数のルートで、価格/品質設定を少し変えて公開しています）、独立したモデルファミリーではありません。それぞれの 1 リクエストあたりの正確な費用は、選択する解像度と品質設定によって決まるため、予算ロジックに数値をハードコードするのではなく、料金ページで最新の数値を確認してください。

送信前に検証しましょう。これら 3 つのモデルは未知の入力フィールドを黙って無視するのではなく、直接拒否します（additional properties 'x' not allowed）。また、resolution や aspect_ratio のような列挙型フィールドは大文字小文字と値に敏感です。ラッパーを構築する場合は、上記の正確な列挙値に従ってクライアント側で検証してください。そうすれば、タイポはリクエストを無駄に消費するのではなく、すぐに失敗します。

関連記事

• Wan 2.7 Image — テキストから画像生成 API、プロンプトだけでまったく新しい高解像度画像を生成します。
• GPT Image 2 API、上記の表で使用した、品質/解像度で段階分けされた代替手段。
• hiapi API 料金、モデルと設定ごとの現在の 1 リクエストあたりの費用を確認できます。
• hiapi ドキュメント、すべてのコールバックオプションを含むタスクライフサイクルの完全なリファレンス。

よくある質問

hiapi には専用の画像拡大ツールや超解像モデルがありますか？ ピクセルを保持する専用モデルはありません。上記のワークフローは汎用的な image-to-image モデルを使用し、より高い解像度の設定で画像を再生成します。これは写真やイラストにはよく効きますが、可逆なアップスケールではありません。

画像の内容を変えずに解像度を上げることはできますか？ モデルに構図・色・被写体を正確に保つようプロンプトで指示することで、かなり近い結果を得られます（「同じ画像、構図を変えず、要素を追加・削除せず、ディテールとシャープネスだけを増やす」）。ただしこれは補間ではなく生成的な再描画であるため、細かいテクスチャでは本物の可逆アップスケーラーと比べて微妙な差異がなお残ります。

生成できる最大解像度はどれくらいですか？ 上記 3 つのモデルはいずれも上限が 4K 解像度設定です。これより大きなサイズが必要な場合は、元画像をタイルに分割して各ブロックを個別にアップスケールするか、API 呼び出しの後にクライアント側でスケーリングするステップを追加する必要があります。

これを試すのに API キーは必要ですか？ はい——すべての /v1/tasks 呼び出しには Authorization: Bearer sk-<your-key> が必要です。タスク作成にキー不要のサンドボックスはありません。まずダッシュボードからキーを取得してください。

フォルダ内の画像をまとめて一括アップスケールできますか？ はい——画像 URL を繰り返し処理し、画像ごとにタスクを 1 つ送信し、その後各 taskId をポーリングするか、（量が多い場合はこちらの方が良い）コールバック URL を登録して、各タスク作成時に保存した taskId で結果をご自身のタスクに紐付けます。

なぜ私のリクエストは「additional properties not allowed」で失敗するのですか？ モデルのスキーマが認識しないフィールドを送信しています——たとえば resolution + aspect_ratio の代わりに size を使ったり、他のモデルの例から余計なパラメータをコピーしてきたりした場合です。各モデルが受け付ける正確なフィールド名については、上記の必須フィールドの表を確認してください。