チュートリアル

hiapi API で seedream-5.0-lite の画像から画像を生成する方法

Jul 7, 2026

このチュートリアルでは、hiapi の統合タスク API を通じて seedream-5.0-lite の画像から画像生成モードを呼び出す方法を説明します。リクエスト構造の正確な理解、すぐに実行できる curl コマンド、バックエンドに組み込める Python スクリプト、そしてこのモデルが強制する一方で他のモデルにはないバリデーションの落とし穴を取り上げます。

この記事を読み終えれば、1 つまたは複数の参照画像 URL と編集プロンプトを受け取り、すぐにダウンロード可能な生成画像 URL を返すスクリプトが手に入ります。

準備するもの

hiapi アカウントと API キー。hiapi コンソールで取得できます。
パブリック HTTPS URL でホストされた 1 枚以上の参照画像。このモデルは 1 リクエストで最大 14 枚の参照画像を受け付けます。これがマルチ参照画像ワークフローで役立つ理由です——ある画像の主体と別の画像のスタイルやシーンを融合できます。
編集や変換を記述するテキストプロンプト（最低 3 文字——そう、API はこれを検証します）。

すべてのリクエストは統合タスクエンドポイントに送信され、キーは Authorization ヘッダーに含めます：

POST https://api.hiapi.ai/v1/tasks
Authorization: Bearer sk-<your-key>
Content-Type: application/json

リクエスト構造（およびこのモデルの要件）

モデル ID は seedream-5.0-lite/image-to-image です——/v1/models に記載されているとおりにそのまま渡してください。このモデルの input スキーマは厳格で、4 つのフィールドすべてが必須です：

フィールド	型	説明
`prompt`	string	編集指示。最小長 3。
`image_urls`	string[]	1〜14 枚の参照画像 URL。
`aspect_ratio`	string	`1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`2:3`、`3:2`、`21:9` のいずれか。
`resolution`	string	`2K` または `4K` のみ。このモデルには 1K の選択肢がありません。

プラットフォーム上の他のモデルから移行してきた人がよく踏む 2 つの罠があります：

resolution は 2K または 4K のみを受け付けます。共有のタスク送信コードがデフォルトで "1K" を設定している場合（他の多くの画像モデルではこれが機能します）、このモデルは 400 で拒否します。
余分なフィールドは無視されず、拒否されます。size、n、またはスキーマ外のものを送信すると 400 INVALID_REQUEST と additional properties '<field>' not allowed が返されます。タスク API はモデルごとに input を検証します——別のモデルのペイロードを盲目的に再利用しないでください。

最小の実行可能な例：curl

タスクを作成します：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/image-to-image",
    "input": {
      "prompt": "Replace the background with a sunlit Tokyo street at golden hour, keep the subject unchanged",
      "image_urls": ["https://your-cdn.example.com/subject.png"],
      "aspect_ratio": "3:2",
      "resolution": "2K"
    }
  }'

送信に成功すると、data にタスク ID が返されます：

{"code": 200, "data": {"taskId": "task_abc123..."}}

結果をポーリングします：

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

実行中は data.status が pending/processing です。完了すると "success" になり、画像が data.output に現れます：

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [{"url": "https://.../result.png", "expireAt": "..."}]
  }
}

出力 URL は短時間だけ有効です（expireAt に注意）。直ちにバイトをダウンロードして自分で保存してください——ホットリンクしたり、元の URL を永続化したりしないでください。

マルチ参照画像：複数の画像を渡す

複数の参照画像を融合するには——たとえば製品画像とスタイル参照画像を組み合わせる場合——image_urls により多くの URL を追加し、プロンプトで各画像が何を提供するかを説明するだけです：

{
  "model": "seedream-5.0-lite/image-to-image",
  "input": {
    "prompt": "Place the product from the first image into the scene from the second image, matching its lighting and color grade",
    "image_urls": [
      "https://your-cdn.example.com/product.png",
      "https://your-cdn.example.com/scene-reference.jpg"
    ],
    "aspect_ratio": "1:1",
    "resolution": "2K"
  }
}

上限は 14 個の URL です。15 個目は 400 INVALID_REQUEST: image_urls: maxItems: got 15, want 14 を返します。実際には、厳選された 2〜4 枚の参照画像と、各画像の役割を明確に割り当てたプロンプト（「画像 1 の主体を保ち、画像 2 の配色を採用する」）の方が、緩く関連する多数の画像よりもはるかに制御可能な編集結果をもたらします。

単一画像に対する正確で的を絞った編集——背景の変更、服装の変更、オブジェクトの削除——には、1 つの参照 URL を使い、何を変更し何を保持するか（「顔とポーズは変えないでください」）を同時に指定します。Seedream モデルは保持指示によく従うため、明確に指定することが精密な編集と完全な再解釈を分ける鍵となります。

本番運用可能な Python：送信、ポーリング、ダウンロード

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-5.0-lite/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,  # this model: "2K" or "4K" only
        },
    }, timeout=60)
    body = resp.json()
    if resp.status_code != 200 or not (body.get("data") or {}).get("taskId"):
        raise RuntimeError(f"create failed [{resp.status_code}]: {body}")
    task_id = body["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().get("data") or {}
        if task.get("status") == "success":
            outputs = task.get("output") or []
            if not outputs or not outputs[0].get("url"):
                raise RuntimeError(f"task {task_id} succeeded but returned no output URL")
            # 3. Download immediately — the URL expires
            img = requests.get(outputs[0]["url"], timeout=120)
            img.raise_for_status()
            return img.content
        if task.get("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} still running after 600s")


if __name__ == "__main__":
    png = edit_image(
        "Replace the background with a minimalist studio backdrop, keep the subject unchanged",
        ["https://your-cdn.example.com/subject.png"],
        aspect_ratio="3:2",
    )
    with open("edited.png", "wb") as f:
        f.write(png)
    print(f"saved edited.png ({len(png)} bytes)")

ポーリングの代わりにコールバックを使う

ポーリングはスクリプトやワーカーキューでは問題ありません。Web バックエンドでは、タスク作成時にコールバックを登録し、hiapi に終状態をプッシュさせます——callback オブジェクトはリクエストの最上位にあり、model の隣に置きます：

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

"when": "final" を使用すると、タスクが success または fail になったときに 1 回だけ POST を受け取ります。ハンドラには 2 つのルールがあります：

冪等にします。タスク ID を処理キーとして使用し、重複配信された webhook が二重処理を引き起こさないようにします。送信時にタスク ID を保存し、コールバックを「取得して完了する」通知として扱い、唯一の真実の情報源とはしないでください。
照合パスを維持します。コールバックが発火したときにエンドポイントがダウンしている場合、未完了の ID を定期的にスキャンして GET /v1/tasks/<id> を実行することで取りこぼしを捕捉できます。

コールバックが届かないように思われる場合は、hiapi タスクのコールバックが発火しない理由にある一般的な障害モードを可能性の高い順に確認してください。

エラー処理：本当に重要な 3 つの失敗

作成時の 401 permission_denied——キーがそのモデルを使用できません。レスポンスボディは次のようになります：

{"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "type": "hiapi_error"}}

コンソールでキーのモデル権限を確認するか、画像モデルが有効化されたキーを使用してください。

作成時の 400 INVALID_REQUEST——input がそのモデルのスキーマと一致しません。メッセージは違反するフィールドをすべて一度に列挙します（例：resolution: value must be one of '2K', '4K'; <root>: additional properties 'size' not allowed）。そのため完全に読み、すべてのフィールドを一度に修正してください。これらは永続的なエラーです——同じペイロードで再試行しても永遠に失敗します。

タスクの status: "fail"——作成は成功しましたが生成に失敗しました（バックエンドが取得できない参照 URL、コンテンツポリシー、上流の容量）。タスクの error.code と error.message が原因を説明します。400 とは異なり、一部は一時的なものであり、バックオフを伴う再試行が 1 回だけ価値があります。

また、存在しないまたは期限切れのタスク ID を GET すると 404 task not found が返ることを知っておくべきです——照合スキャンではこれを「まだ待機中」ではなく終状態として扱ってください。

次に読むべきもの

seedream-5.0-lite/image-to-image モデルページ——プレイグラウンドと画像ごとの課金。
hiapi の料金——すべての画像モデルの現在の料率。
2026 年ベスト画像から画像 API——同じ編集タスクにおける seedream と gpt-image-2 などの比較。
gpt-image-2 画像から画像チュートリアル——同じタスク API で異なる input スキーマ。ペイロードがモデル間で汎用できない理由をよく示しています。
hiapi ドキュメント——完全なタスク API リファレンス。

FAQ

seedream-5.0-lite 画像から画像に何枚の参照画像を渡せますか？ image_urls 配列は最大 14 枚です。最小 1 枚——このフィールドは必須なので、純粋なテキストから画像の呼び出しには seedream-5.0-lite/text-to-image を使用してください。

他のモデルでは 1K が使えるのに、なぜ「value must be one of '2K', '4K'」が返るのですか？ タスク API の入力スキーマはモデルごとに定義されています。seedream-5.0-lite の画像から画像モードは 2K と 4K の出力のみを提供し、他のモデルは 1K の選択肢を提供します。確認せずに別のモデルのペイロードを再利用しないでください。

参照画像を URL ではなく base64 で送信できますか？ このモデルのスキーマは image_urls——URL の配列——を受け付けます。画像をアクセス可能な HTTPS URL（任意の CDN、オブジェクトストレージバケット、または署名付き URL で構いません）でホストし、その URL を渡してください。

1 回の生成にどれくらいかかり、出力 URL はどれくらい有効ですか？ 通常、上記の Python 例の 600 秒のポーリング予算をはるかに下回ります。出力 URL には expireAt タイムスタンプが付いています——タスク成功後すぐにバイトをダウンロードして自分のストレージに保存してください。

同じコードを seedream-5.0-lite のテキストから画像に使えますか？ エンドポイントとフローは同じですが、テキストから画像には独自の input スキーマがあります（image_urls はありません）。モデル ID を seedream-5.0-lite/text-to-image に変更し、参照画像を削除します——その後、テスト呼び出しで検証してください。モードごとに必須フィールドが異なるためです。

1 枚あたりいくらですか？ 料金は生成ごとの使用量に基づいて課金され、解像度によって異なります。料金ページで最新の料率を確認してください。