hiapi API で seedream-5.0-flash を使う方法：curl、Python、実行可能なリクエスト

作成するもの

curl と Python から hiapi の seedream-5.0-flash 画像モデルを呼び出す、実行可能な統合です。テキストから画像生成（または画像編集）リクエストを送信し、結果をポーリングして出力 URL をダウンロードします。最終的には、自分のプロジェクトにそのまま組み込めるスクリプトが完成します。

前提条件

• hiapi アカウントと API キー。hiapi コンソール から取得してください — キーは sk-... の形式です。
• curl または Python 3.8+（pip install requests）。
• 画像編集ライブラリは不要です — seedream-5.0-flash はプロンプトのみ、または編集用の入力画像 URL を伴うプロンプトを受け付けます。

完全なモデルリファレンス：hiapi の seedream-5.0-flash および API ドキュメントページ。

最小の実行可能な例

hiapi はすべての生成モデルを統一エンドポイントで公開しています。まずタスクを作成し、次にポーリング（またはコールバックを受信）して完了まで待ちます。

curl

# 1. タスクを作成
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {
      "prompt": "a minimalist ceramic teapot on a wooden table, soft morning light, product photography",
      "size": "2K"
    }
  }'
# => {"code":0,"data":{"taskId":"task_xxx","status":"pending", ...}}

# 2. 完了までポーリング
curl -s https://api.hiapi.ai/v1/tasks/task_xxx \
  -H "Authorization: Bearer sk-<your-api-key>"
# => {"code":0,"data":{"taskId":"task_xxx","status":"success",
#      "output":[{"url":"https://...signed-url...","expireAt":"..."}]}}

Python

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def generate_image(prompt: str, size: str = "2K") -> str:
    create = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "seedream-5.0-flash", "input": {"prompt": prompt, "size": size}},
        timeout=30,
    )
    create.raise_for_status()
    task_id = create.json()["data"]["taskId"]

    while True:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        data = poll.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data}")
        time.sleep(2)


if __name__ == "__main__":
    image_url = generate_image("a minimalist ceramic teapot on a wooden table, soft morning light")
    print(image_url)

input オブジェクトに関する補足：

• prompt（必須、1〜5000 文字）— 何を生成するか、または image を同時に渡す場合は何を変更するか。
• image（任意、文字列または最大 10 個の URL／base64 data:image/... URI の配列）— このパラメータを渡すと、ゼロから生成するのではなく既存画像を編集／参照します。純粋なテキストからの画像生成では省略します。
• size（任意、デフォルト "2K"）— プリセット値のいずれか 1K / 1.5K / 2K、または "1536x1024" のようなカスタム WIDTHxHEIGHT 文字列（総ピクセル数 921,600〜4,624,220、アスペクト比 1:16〜16:1 の範囲）。
• output_format（任意）— "jpeg" または "png"。
• background（任意、デフォルト "opaque"）— アルファチャンネルを持つ画像を編集する場合にのみ "transparent" に設定します。

レスポンスの output[].url は署名付きで有効期限のあるリンク（expireAt フィールド）です — 長期間このホットリンクを保存するのではなく、速やかにダウンロードするか再ホストしてください。

本番環境のパターン

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

サーバー間の統合では、ポーリングを省略し、タスク完了時に hiapi から通知を受け取ります。model/input の隣にトップレベルの callback オブジェクトを追加します（input 内にネストしないでください）：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {"prompt": "a minimalist ceramic teapot on a wooden table"},
    "callback": {"url": "https://yourapp.example.com/hooks/hiapi", "when": "final"}
  }'

when: "final" は現在唯一サポートされている値です — タスクが終端状態（success または fail）に達すると、エンドポイントは正確に 1 回の POST を受信します。配信のリトライに備えて taskId で重複排除し、本番環境で依存する前にエンドポイントが HTTPS でアクセス可能であることを確認してください。

ポーリング vs. コールバック

• プロトタイピング中、短命なスクリプトを実行する場合、または公開 HTTPS エンドポイントがまだない場合はポーリングを使います。シンプルですが、遅延と遅いタスクのリクエスト量が増えます。
• サービスを運用する場合はコールバックを使います — 無駄なポーリングリクエストがなく、タスクが完了するとすぐに把握できます。公開アクセス可能な HTTPS URL が必要です。

冪等性

画像生成自体は冪等ではありません（同じプロンプトでも 2 回同じ画像が返ることはありません）。そのため、ワークフローに「リトライしても二重課金しない」というセマンティクスが必要な場合は、こちら側で taskId を追跡し、タイムアウト後に同じリクエストを再送信する前にタスク状態を確認してください。盲目的にリトライしないでください。

エラーハンドリング

• permission_denied を伴う 401 — API キーが欠落しているか、形式が誤っているか、失効しています：

  {"error":{"code":"permission_denied","message":"This API key is invalid. Check that it is correct or use another API key and try again.","type":"hiapi_error"}}
  

  Authorization: Bearer sk-...（生のキーだけではない）を送信していること、およびキーがローテーションされていないことを確認してください。

• INVALID_REQUEST を伴う 400 — いずれかのフィールドが検証に失敗しました。message はどのフィールドが、なぜ失敗したかを正確に示します（たとえば範囲外の size など）。そのフィールドを修正して再送信してください。そのままリトライしないでください。

• タスクレベルの失敗 — HTTP 呼び出しは成功（200）しても、タスクは処理完了後に status: "fail" で終了することがあります。作成呼び出しの HTTP ステータスコードだけでなく、ポーリング／コールバックレスポンスの data.status を常に確認してください。

関連する内部リンク

• seedream-5.0-flash モデルページ — 価格、制限、オンライン試用パネル。
• タスク作成（ドキュメント） — POST /v1/tasks の完全なリクエストスキーマ。
• タスク詳細取得（ドキュメント） — ポーリングレスポンスの構造とステータス値。
• 認証（ドキュメント） — API キーとリクエストヘッダーがすべての hiapi エンドポイントでどのように機能するか。
• hiapi 価格 — seedream-5.0-flash およびその他すべてのモデルの現在の 1 画像あたりの価格。
• seedream-5.0-pro テキストから画像生成 API ガイド — より高解像度の出力が必要な場合は、Pro 層のより高忠実度の姉妹モデルを参照してください。

よくある質問

seedream-5.0-flash は無料ですか？ 無料ではありません — hiapi API キーを通じて画像ごとに課金されます。現在の料金は価格ページを参照してください。有効なキーがないと本番アクセスはできません。

seedream-5.0-flash はテキストから画像生成だけでなく、画像から画像への編集もサポートしていますか？ サポートしています。prompt の隣に image フィールド（URL または base64 data:image/... 文字列、あるいは最大 10 個の配列）を追加すると、モデルはゼロから生成するのではなく参照画像に基づいて編集／融合します。

リクエストが 200 を返したのに画像がないのはなぜですか？ POST /v1/tasks が 200 を返すのは、タスクが受理されたことだけを意味します — 生成は非同期です。GET /v1/tasks/<id> をポーリングする（またはコールバックを待つ）して data.status を確認してください。画像 URL は status が "success" の場合にのみ現れます。

1K/1.5K/2K ではなくカスタム解像度を要求できますか？ できます — size にプリセット値の代わりに "WIDTHxHEIGHT"（例："1536x1024"）を渡してください。総ピクセル数は 921,600〜4,624,220、アスペクト比は 1:16〜16:1 の範囲である必要があり、そうでない場合はリクエストが 400 を返します。

出力 URL は時間が経つとどうなりますか？ 返される output[].url は expireAt タイムスタンプ付きの署名付き URL です — 永続ストレージではありません。タスク成功後はできるだけ早くバイトをダウンロードするか、自分のストレージにコピーしてください。

コールバックが一度も発火しません — 最初に何を確認すべきですか？ callback.url が公開アクセス可能な HTTPS エンドポイントであること（localhost や内部専用アドレスではないこと）、および callback がリクエスト本文のトップレベルフィールドであること — input 内にネストされていないことを確認してください。