hiapi API で seedream-4.5/image-to-image を使う方法：curl、Python、利用可能なリクエスト

seedream-4.5 で画像を編集するには、hiapi の統合タスク API に POST を1回送信し、少しポーリングしてから結果をダウンロードするだけです。本ガイドでは、動作する curl リクエストと seedream-4.5/image-to-image 向けの完全な Python スクリプトを提供し、正確な入力フィールドの説明（実際の API で検証済み）、複数参照画像の使い方、そして実際に遭遇するエラーについて解説します。

構築するものと必要なもの

目標：1枚または複数のソース画像と編集指示を seedream-4.5/image-to-image に送信し、完成した画像の URL を取得すること。

前提条件：

• hiapi API キー——コンソールから取得します。以下の各リクエストで Bearer トークンとして使用します。
• ソース画像は公開アクセス可能な URL 上にホストされている必要があります。API はサーバー側でそれらを取得します。ローカルファイルパスやプライベート URL は使用できません。

このモデルは非同期タスクエンドポイントで動作します：POST /v1/tasks でタスクを作成し、GET /v1/tasks/<taskId> でステータスを報告し、完成した画像は data.output[0].url に現れます。

入力フィールドの説明（検証済み）

seedream-4.5/image-to-image には4つの必須入力フィールドがあり、それ以外のフィールドは受け付けません——フィールドの説明は厳格で、未知のフィールドは400で拒否されます：

フィールド	型	制約
prompt	string	編集指示
image_urls	文字列の配列	公開 URL、最大14枚の画像
aspect_ratio	string	1:1、4:3、3:4、16:9、9:16、2:3、3:2、21:9 のいずれか
resolution	string	2K または 4K のみ

注目すべき点が2つあります：n パラメータは存在しません（1タスクにつき1出力——複数のバリエーションが必要な場合は複数のタスクを並行して作成してください）。また、seedream-5.0-pro の image-to-image（1K/2K を受け入れる）とは異なり、4.5 は 2K または 4K を要求します。ここで 1K を送信すると検証エラーが返されます。

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

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5/image-to-image",
    "input": {
      "prompt": "Turn this product shot into a clean studio photo on a seamless white background with soft shadows",
      "image_urls": ["https://your-cdn.example.com/source.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

作成に成功すると data.taskId にタスク ID が返されます。それをポーリングします：

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

data.status が success に達すると、画像 URL は data.output[0].url にあります。fail の場合は、理由が data.error にあります。

完全な Python スクリプト

SDK は不要です——requests とポーリングループだけで十分です：

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def edit_image(prompt: str, image_urls: list[str],
               aspect_ratio: str = "1:1", resolution: str = "2K") -> bytes:
    # 1. Create the task
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "seedream-4.5/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,   # public URLs, max 14
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,   # "2K" or "4K"
        },
    }, timeout=60)
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    # 2. Poll until terminal state
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}",
                            headers=HEADERS, timeout=30).json()["data"]
        if task["status"] == "success":
            url = task["output"][0]["url"]
            # 3. Output URLs expire -- download immediately
            return requests.get(url, timeout=120).content
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in 600s")

png = edit_image(
    "Turn this product shot into a clean studio photo on a seamless white background",
    ["https://your-cdn.example.com/source.jpg"],
)
with open("edited.png", "wb") as f:
    f.write(png)

ステップ3のコメントに注意してください：出力 URL には有効期限のタイムスタンプが付いています。タスクが成功したら、すぐにバイトデータを自身のストレージに永続化してください——返された URL を保存するだけで、明日も使えると期待してはいけません。

複数参照画像の編集

image_urls は1つのタスクで最大14枚の画像を受け付けます。これはスタイル転送や構図タスクの強力な武器です：編集したい画像と参照画像を渡し、プロンプトでそれらをどのように組み合わせるかを記述します。

{
  "model": "seedream-4.5/image-to-image",
  "input": {
    "prompt": "Apply the color grading and lighting style of the second image to the first image, keep the subject unchanged",
    "image_urls": [
      "https://your-cdn.example.com/subject.jpg",
      "https://your-cdn.example.com/style-reference.jpg"
    ],
    "aspect_ratio": "3:2",
    "resolution": "2K"
  }
}

順序はプロンプトにとって意味がありますが、API にとっては意味がありません——画像を位置で参照してください（「1枚目の画像」「2枚目の画像」）。そうすればモデルはどちらがどちらかを認識できます。

本番環境での注意点

ポーリングの代わりにコールバックを使用する。 スクリプト以外のあらゆる場面では、タスク作成時にルートレベルの callback オブジェクトを追加し、ポーリングループを完全にスキップしてください：

{
  "model": "seedream-4.5/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

タスクが完了すると、hiapi はタスクの最終状態をあなたの URL に POST します。ポーリングは CLI ツールや notebook には適していますが、Web バックエンドではコールバックが正しい選択です。そうしないと、2K 編集に必要な数十秒間ずっとワーカープロセスを占有することになります。

冪等性。 タスク作成は冪等ではありません——ネットワークタイムアウト後に作成を再試行すると、2つのタスクが生成され（そして課金され）る可能性があります。taskId を取得した瞬間に保存し、再試行時には新しいタスクを作成する前にアクティブなタスクが既に存在しないか確認してください。

エラー処理。 最初に遭遇する2種類の失敗：

• 401 permission_denied——キーが間違っているか、そのキーにこのモデルへのアクセス権がありません。レスポンスボディは {"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "request_id": "..."}} のような形式です。サポートに連絡する際は request_id を添えてください。
• 400 INVALID_REQUEST——フィールドの説明違反で、正確なメッセージが返されます：resolution の値が誤っている、image_urls が14枚を超えている、未知のフィールドがある、または image_urls が配列でない。これらはタスク実行前に捕捉されるため、費用は発生しません。

失敗したタスクはタスク自体に status: "fail" と error オブジェクトを付けて報告します——上記の Python スクリプトが行っているように、これを HTTP エラーとは別のケースとして処理してください。

料金

画像1枚あたりの費用は解像度によって異なります。現在の料金は料金ページでご確認ください。検証段階で拒否されたリクエスト（400）はタスクを開始しないため、統合中のフィールド説明の誤りは無料です。

関連記事

• seedream-4.5/image-to-image モデルページ——プレイグラウンド、料金、完全なパラメータリファレンス
• seedream-4.5/text-to-image——同じシリーズ、プロンプトのみの生成
• seedream-5.0-pro image-to-image ガイド——より新しいティア、解像度の列挙値が異なる
• hiapi ドキュメント——タスク API リファレンスと認証

よくある質問

URL の代わりにローカルファイルや base64 画像を渡せますか？ いいえ。image_urls は公開アクセス可能な URL の配列である必要があります——プラットフォームはサーバー側でそれらを取得し正規化します。まず自身のストレージ（S3、R2、任意の CDN）にアップロードしてから、URL を渡してください。

seedream-4.5 image-to-image は何枚の参照画像をサポートしますか？ 1タスクあたり最大14枚です。超過すると400が返され、メッセージに image_urls: maxItems が含まれます。

resolution を 1K に設定すると 400 が返るのはなぜですか？ 4.5 image-to-image エンドポイントは 2K または 4K のみを受け付けます。1K オプションは seedream-5.0-pro の image-to-image に属します——ティアシリーズが異なれば列挙値も異なります。

1つのリクエストで複数のバリエーションを生成できますか？ いいえ——フィールドの説明に n パラメータはなく、未知のフィールドは拒否されます。バリエーションごとにタスクを作成し並行して実行してください。各タスクは1つの出力のみを返します。

結果 URL の有効期間はどのくらいですか？ 出力 URL には署名と有効期限が付いています。タスク成功後すぐに画像をダウンロードして自身で保存してください。タスク出力へのホットリンクは避けてください。

HTTP エラーと失敗したタスクの違いは何ですか？ HTTP エラー（400/401）は、リクエストがタスクにすらならなかったことを意味します——ペイロードまたはキーを修正して再送信してください。status: "fail" で終了したタスクは受け入れられたものの完了できなかったものです。理由はタスクの error オブジェクトにあり、一時的な失敗の場合は同じ入力で再試行するのが通常は正しい対処です。