hiapi API で seedream-5.0-pro/image-to-image を利用する方法：curl、Python、そして実行可能なリクエスト例

Seedream 5.0 Pro は ByteDance のフラッグシップ画像モデルです。その image-to-image エンドポイントは、1 枚以上の参照画像とテキスト指示を受け取り、編集後の結果を返します。スタイルの再描画、背景の差し替え、商品写真のクリーンアップ、複数画像の合成などが可能です。hiapi 上では、統一された非同期の tasks API 上で動作します。まずタスクを作成し、その後ポーリング（またはコールバック受信）を行い、最後に出力をダウンロードします。以下の各パラメータ、列挙値、エラーメッセージはすべて、本ガイドの公開前に実際のオンライン API に対して検証済みです。

何を構築し、何を準備するか

目標：seedream-5.0-pro/image-to-image に参照画像を 1 枚と編集指示を送信し、編集後の画像を受け取ってローカルに保存します。

必要なものは 2 つです：

1. hiapi API キー —— コンソールから取得します。Authorization: Bearer sk-... リクエストヘッダに設定する必要があります。
2. 公開アクセス可能な画像 URL —— API はサーバー側で参照画像を取得するため、HTTPS でアクセスできる必要があります。自前のストレージバケットで生成した署名付き URL は問題なく使えますが、localhost やプライベートなパスは使えません。URL を取得できない場合は、サイレントに失敗するのではなく、標準化されたエラーが返されます。

パラメータ（検証済み）

モデル ID は seedream-5.0-pro/image-to-image で、GET /v1/models が返すものと完全に一致します。4 つの入力フィールドはすべて必須です：

フィールド	型	必須	値 / 説明
prompt	string	はい	編集指示。
image_urls	文字列配列	はい	1〜10 個の公開アクセス可能な画像 URL。画像が 1 枚でも常に配列にします。
aspect_ratio	string	はい	match_input_image、1:1、4:3、3:4、16:9、9:16、3:2、2:3、21:9
resolution	string	はい	1K または 2K

つまずきやすいポイントが 2 つあります：

• スキーマは厳格です。未知のフィールドは拒否されます——n、size、seed を送信すると 400 が返り、additional properties ... not allowed が付きます。hiapi 上の各モデルの入力スキーマはそれぞれ異なります（size を使うモデルもあれば、aspect_ratio を使うモデルもあります）ので、モデルファミリー間でフィールドをコピーしないでください。
• ここでの resolution は 1K/2K のみサポートします。他の seedream エンドポイントは異なる解像度セットを受け付けるため、当然と決めつけず、エンドポイントごとに確認する価値があります。

最小の実行可能な例：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-5.0-pro/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a seamless white background with soft shadows",
      "image_urls": ["https://your-bucket.example.com/product.jpg"],
      "aspect_ratio": "match_input_image",
      "resolution": "2K"
    }
  }'

作成に成功すると、タスク ID が data.taskId に返されます（レスポンスは簡略化しています）：

{ "data": { "taskId": "<your-task-id>" } }

タスクが終端状態になるまでポーリングします：

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status が最終的に success になれば、画像 URL は data.output[0].url にあります。fail の場合は、詳細が data.error.code と data.error.message に含まれます。

完全な Python スクリプト：作成、ポーリング、ダウンロード

標準ライブラリのみを使用します——何もインストールする必要はありません：

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


def call(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload is not None else None,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
        method="POST" if payload is not None else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


# 1. Create the edit task
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": "Restyle this living room as a Scandinavian interior, keep the layout and window positions",
        "image_urls": ["https://your-bucket.example.com/room.jpg"],
        "aspect_ratio": "match_input_image",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until terminal state
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Download immediately -- output URLs expire
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "edited.png")
print("saved edited.png")

本番環境での注意点

サーバー上ではポーリングよりもコールバックを優先しましょう。タスク作成時にトップレベルの callback オブジェクトを追加すると、hiapi は終端状態になったときにあなたのエンドポイントへ 1 回 POST します：

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

ハンドラーでは、コールバックを情報源ではなくシグナルとして扱ってください。コールバックからタスク ID を取り出し、自分で GET /v1/tasks/<id> を再リクエストしてから、それに基づいて行動します。スクリプト、notebook、単発タスクではポーリングが依然として適切です——間隔は 5 秒程度に保ちましょう。

リトライを冪等にしましょう。タスク作成時に、自分のソース画像 → taskId のマッピングを保存します。ポーリングの途中でプロセスがクラッシュした場合は、編集を再送信するのではなく、保存済みの taskId に再関連付けしてください——再送信すると 2 つ目の課金タスクが発生します。

出力はすぐにダウンロードしましょう。data.output[0].url の URL には有効期限があります（期限切れ時刻付き）。バイトをダウンロードして自分のバケットに保存してください。ユーザー向けコンテンツでタスク出力 URL を直接ホットリンクしないでください。

実際に遭遇するエラー：

• 401 と permission_denied —— API キーが欠落しているか形式が誤っています。リクエストヘッダが正確に Authorization: Bearer sk-... であるか確認してください。
• 400 と INVALID_REQUEST —— 入力スキーマ違反です。エラーメッセージは正確で、例えば resolution: value must be one of '1K', '2K' や image_urls: maxItems: got 11, want 10 のようになります。
• image_urls must be an array —— 裸の文字列を渡しています。画像が 1 枚でもリストでラップしてください。

次のステップ

• モデルページ：seedream-5.0-pro/image-to-image —— 機能と現在のステータス。
• 画像 1 枚あたりの価格は料金ページに掲載されています。
• 高並列パイプライン向けのより安価な編集ソリューション：seedream-5.0-lite の image-to-image を使う方法。
• モデル間での選択：2026 年のベスト image-to-image API では、3 つのモデルで同じ編集タスクを比較しています。
• 完全な API リファレンス：hiapi ドキュメント。

よくある質問

参照画像は最大何枚まで送信できますか？ image_urls に最大 10 個の URL です。この制限はサーバー側で強制されます——11 枚の画像は maxItems: got 11, want 10 を返します。

出力で入力画像のアスペクト比を維持できますか？ はい——aspect_ratio を match_input_image に設定してください。編集や再描画では通常これが望ましい設定です。16:9 のような明示的な比率を選ぶのは、意図的に構図を変更したい場合だけにしましょう。

seedream-5.0-pro image-to-image は 4K をサポートしていますか？ いいえ。このエンドポイントは 1K と 2K のみを受け付けます。それ以外の値をリクエストすると、許可される値の一覧とともに 400 が返されます。

画像 URL は公開されている必要がありますか？ hiapi のサーバーが HTTPS 経由で取得できる必要があります。署名付き URL（S3、R2、GCS）は問題なく機能し、バケット自体をプライベートに保つことができます。

seedream-5.0-pro image-to-image の画像 1 枚あたりの費用はいくらですか？ 料金は正常に生成された画像に対して課金され、解像度によって異なります——現在の料金については料金ページをご確認ください。

seedream-5.0-lite image-to-image との違いは何ですか？ Pro はフラッグシップ層で、より困難で高忠実度な編集向けです。lite はより高速で安価な大量処理向けの選択肢です。リクエスト構造は似ているため、最も明確な判断方法は、同じ編集タスクを両方で実行してみることです——lite ガイドから始めて、結果を自分の参照画像と比較してください。