Seedream API コスト最適化：hiapi で画像生成コストを削減する方法

Seedream は hiapi 上で 4 つの異なるティアで提供されています——seedream-5.0-flash、seedream-5.0-lite、seedream-5.0-pro、そして旧版の seedream-4.5——各ティアの課金方式はそれぞれ異なります。ティアや解像度を誤って選ぶと、見た目の画質向上が一切ないのに 1 枚あたり 2〜4 倍の料金を支払うことになりかねません。本ガイドでは、各ティアの実際の料金体系を示し、要件を満たす中で最も低コストなモデルを呼び出すための実行可能なコード例を紹介します。

構築するものと前提条件

hiapi の統合タスク API を通じて Seedream の画像タスクを作成し、結果を待機する小さな Python クライアントを構築します。その際、チュートリアルからコピー＆ペーストしたデフォルト値をそのまま使うのではなく、解像度とモデルの組み合わせを意識的に選択します。まず、hiapi コンソールから API キーを取得してください——以下のすべてのリクエストで、Authorization: Bearer sk-... の形式でこのキーを送信します。

最適化対象となる料金体系

現在の 1 枚あたりの料金（料金は変動するため、リリース前に必ず最新の料金ページを確認してください）：

• seedream-5.0-flash —— 1 枚あたり一律 $0.025。テキストからの画像生成と画像からの画像生成が同額です。プラットフォームで最も安価なティアであり、下書き、サムネイル、そして何度も再生成してから最終結果を選ぶようなあらゆる場面に最適です。
• seedream-5.0-lite —— 1 枚あたり一律 $0.035。しかも重要な点として、2K でレンダリングしても 4K でレンダリングしても価格は同じです。このティアでは、コストの観点から 2K をリクエストする理由は決してありません——4K は無料のアップグレードです。
• seedream-4.5（旧版）—— 両エンドポイントとも 1 枚あたり一律 $0.045。
• seedream-5.0-pro —— 一律価格ではなく解像度による段階制：テキストからの画像生成は 1K が $0.05、2K が $0.10。画像からの画像生成は 1K が $0.06、2K が $0.10。このティアでは、解像度こそが予算の実際の行き先です——1K の下書きのコストは、2K の最終レンダリングのおよそ半分です。

この非対称性こそが最適化の要点です：lite はより高い解像度のリクエストに報い（無料）、pro はより高い解像度に罰を与えます（コストがほぼ倍増）。 呼び出しコード内ではこれらを区別して扱い、至る所で同じ解像度をハードコードしないでください。

最小限の実行可能な例

Seedream の呼び出しはすべて同じ非同期タスクエンドポイントを経由します：POST /v1/tasks で作成し、その後 GET /v1/tasks/{taskId} をポーリングするか、Webhook コールバックを受信します。モデル ID は裸の形式です——先頭に models/ やベンダープレフィックスは付きません。

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]  # starts with sk-
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_task(model: str, input_payload: dict) -> str:
    resp = requests.post(f"{BASE_URL}/tasks", headers=HEADERS,
                          json={"model": model, "input": input_payload}, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_task(task_id: str, interval: float = 3.0, timeout: float = 180.0) -> dict:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] == "success":
            return data
        if data["status"] == "fail":
            raise RuntimeError(data["error"])
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish within {timeout}s")


# seedream-5.0-lite: 4K costs the same $0.035 as 2K, so always ask for 4K here.
task_id = create_task(
    "seedream-5.0-lite/text-to-image",
    {"prompt": "a minimalist product photo of a ceramic mug on a wooden table", "resolution": "4K"},
)
result = wait_task(task_id)
image_url = result["output"][0]["url"]
print(image_url)

seedream-5.0-lite の resolution は 2K または 4K のみを受け付けます（1K はありません）。一方、seedream-5.0-pro は 1K/2K を受け付け、さらに aspect_ratio（1:1、4:3、3:4、16:9、9:16、2:3、3:2、21:9 のいずれか）が必須です——Seedream の各ティアは入力スキーマが多少異なるため、あるモデルが受け付けるフィールドが別のモデルでもそのまま使えると考えないでください。

本番環境向けのパターン

習慣ではなくプログラムでティアを選択する。 呼び出し箇所のそばに小さなコスト表を維持し、予算や品質の要件に応じてルーティングします。至る所で同じモデルをハードコードしないでください——数値は事実の源泉ではなく料金ページのキャッシュとして扱います：

SEEDREAM_COST_USD = {
    ("seedream-5.0-flash", None): 0.025,
    ("seedream-5.0-lite", "2K"): 0.035,
    ("seedream-5.0-lite", "4K"): 0.035,   # same price — always prefer 4K
    ("seedream-5.0-pro", "1K"): 0.05,      # text-to-image; i2i 1K is $0.06
    ("seedream-5.0-pro", "2K"): 0.10,
}

def pick_model_for_draft_vs_final(is_final: bool) -> tuple[str, dict]:
    if not is_final:
        return "seedream-5.0-flash", {}  # $0.025, iterate freely
    return "seedream-5.0-pro", {"resolution": "2K"}  # $0.10, one shot at the end

頻繁なポーリングよりもコールバックを優先する。 高スループットのパイプラインでは、数秒ごとに wait_task をループ呼び出しするのではなく、作成リクエストに callback を追加します：

task_id_resp = requests.post(
    f"{BASE_URL}/tasks", headers=HEADERS,
    json={
        "model": "seedream-5.0-lite/text-to-image",
        "input": {"prompt": "...", "resolution": "4K"},
        "callback": {"url": "https://yourapp.example.com/webhooks/hiapi", "when": "final"},
    },
    timeout=30,
)

タスクが終端状態（success または fail）に達すると、Webhook ハンドラーが 1 回の POST を受信します。ワーカーがポーリングループでリクエストを消費することはありません。公開 HTTPS エンドポイントを公開できない場合（ローカル開発、内部ツール）、ポーリングは依然としてより簡単な選択肢です——実際の規模で運用を始めたら、コールバックに切り替えてください。

タスク作成前に重複排除する。 タスク API は作成時に課金されるため、リクエストの再試行（タイムアウト、ワーカーのクラッシュ、キューコンシューマーの再デプロイ）が同じジョブを再送信すると、二重に課金されます。create_task を呼び出す前に、(model, input_hash) をキーとする既存タスクが自分のストレージにないかを確認し、そのタスクがすでに実行中か成功している場合は作成をスキップしてください——hiapi のタスクエンドポイントには組み込みの重複排除がないため、これはあなたのコード側で行う必要があります。

認証失敗を明示的に処理する。 無効または失効したキーは、汎用的なエラーページではなく、HTTP 401 と構造化されたレスポンスボディを返します：

{"error": {"code": "permission_denied", "type": "hiapi_error", "request_id": "..."}}

error.code == "permission_denied" を個別にチェックすることで、不良キーはタイムアウトまで再試行するのではなく即座に失敗します。

関連する hiapi リソース

• 料金 —— 各モデルの現在のレート。本記事内の数値はスナップショットであり、保証ではないとお考えください。
• API キーコンソール —— キーの作成とローテーション。
• Seedream 5.0 Lite — テキストからの画像生成 および 画像からの画像生成のモデルページ。
• Seedream 5.0 Pro — テキストからの画像生成 および 画像からの画像生成のモデルページ。
• Seedream 5.0 Flash のモデルページ。
• 非同期タスク API リファレンス —— 作成／ポーリング／コールバックの完全な契約。
• 認証ドキュメント —— キーの形式とリクエストヘッダーの要件。

よくある質問

迅速な下書きやアイコンに最も安い Seedream モデルはどれですか？ seedream-5.0-flash で、1 枚あたり一律 $0.025——プラットフォームで最も安価なティアであり、テキストからの画像生成と画像からの画像生成が同額です。

Seedream 5.0 Lite で 2K ではなく 4K をリクエストすると高くなりますか？ いいえ。seedream-5.0-lite は resolution が 2K でも 4K でも 1 枚あたり一律 $0.035 です。そのため、このティアではデフォルトで 4K をリクエストしてください。

Seedream 5.0 Pro は 1 枚あたりいくらですか？ 解像度による段階制：テキストからの画像生成は 1K が $0.05、2K が $0.10。画像からの画像生成は 1K が $0.06、2K が $0.10 です。lite と異なり、このティアでは解像度が実際に請求額を変動させます。

ジョブが再試行された場合、二重課金を避けるにはどうすればよいですか？ タスク API にはサーバー側の冪等キーがありません。そのためクライアント側で重複排除します。create_task を呼び出す前に (model, input_hash) のキーを保存し、そのキーが実行中または成功済みの場合は作成をスキップしてください。

ポーリングと Webhook コールバックのどちらを使うべきですか？ 公開 HTTPS エンドポイントを公開できない場合（ローカル開発、スクリプト）は、GET /v1/tasks/{taskId} をポーリングしてください。実際の規模で運用を始めたら、callback.url と when: "final" に切り替えてください——ポーリングループがタスクごとに 1 回のプッシュ通知に置き換わります。

無効な API キーは何を返しますか？ HTTP 401 と {"error": {"code": "permission_denied", "type": "hiapi_error", "request_id": "..."}} です。不良キーでタイムアウトまで再試行するのではなく、このエラーコードを明示的にチェックしてください。

API キーなしでこれらの価格を利用できますか？ いいえ——すべての /v1/tasks 呼び出しには、コンソールで作成した実際のキーによる有効な Authorization: Bearer sk-... リクエストヘッダーが必要です。本番の生成にキーなしや登録不要のトライアルといった経路はありません。