hiapi で wan2.7-image-standard API を使用する方法：テキストから画像生成と参照画像編集

wan2.7-image-standard は通義万相 Wan 2.7 Image モデルの標準グレードです。これを独立したページにする価値がある理由は、1 つのモデル ID でテキストから画像生成と参照画像に基づく画像編集の両方をサポートし、最大 2K に対応し、固定価格1 枚あたり $0.0345 で課金される点です——4K 対応の Pro グレードよりも安価です。本ガイドでは、すぐに実行できるリクエスト、正確な入力スキーマ（オンライン API に対して検証済み）、参照画像編集のパス、そして本番環境で必ず対処すべき境界動作を提供します。

以下のスキーマとエラーに関する部分のすべては、執筆中にオンラインの /v1/tasks エンドポイントをプローブして確認したものです——列挙リスト、受け入れ可能なフィールド集合、失敗レスポンスの形態はすべて実際の API レスポンスから引用しており、記憶によるものではありません。

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

プロンプト（必要に応じて参照画像を添付）を送信し、タスクが完了するまでポーリングしてから画像をダウンロードします。まず必要なものは 1 つです。hiapi クイックスタートから API key を取得し、HIAPI_API_KEY としてエクスポートしてください。key 不要のパスは存在しません——すべてのリクエストは Authorization: Bearer sk-<your-key> で認証されます。

wan2.7-image-standard は hiapi の非同期タスク API 上で動作します。まず POST /v1/tasks でタスクを作成し、その後詳細エンドポイントをポーリングして終態を報告するまで待ちます。

テキストから画像生成：最小リクエスト

タスクを作成：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "雨上がりのブルーアワー、静かで人けのない路地にある小さな陶芸工房、温かな紙提灯が下がり、ショーウィンドウには釉薬をかけた急須が並び、濡れた石畳に灯りが映り込み、壁際に自転車が寄りかかっている、シネマティックな 35mm 写真、高精細",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

レスポンスのタスク id は data.taskId にあります：

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5D5..." }, "message": "success" }

次に GET /v1/tasks/<taskId> を data.status が success になるまでポーリングし、data.output[0].url から画像 URL を読み取ります：

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(prompt, aspect_ratio="16:9", resolution="2K", image_urls=None, timeout=600):
    payload = {"model": "wan2.7-image-standard",
               "input": {"prompt": prompt,
                         "aspect_ratio": aspect_ratio,
                         "resolution": resolution}}
    if image_urls:                      # 参照画像編集（次のセクションを参照）
        payload["input"]["image_urls"] = image_urls

    create = requests.post(API, headers=HEADERS, json=payload).json()
    if create.get("code") != 200:       # 同期バリデーションエラー（例：無効な列挙値）
        raise RuntimeError(create)
    task_id = create["data"]["taskId"]

    deadline = time.time() + timeout
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if data["status"] == "success":
            return requests.get(data["output"][0]["url"]).content
        if data["status"] == "fail":    # 終態の失敗——ポーリングを続けない
            raise RuntimeError(data.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...")   # バイト列をすぐに保存——以下の有効期限の説明を参照

aspect_ratio と resolution はどちらも任意です（モデルにデフォルト値があります）が、明示的に設定してください——resolution は 1K または 2K のみを受け付け、両者の課金は同じなので、デフォルトのままにするコスト上の理由はありません。

参照画像に基づく編集：同じモデル ID に image_urls を加える

ここが標準グレードと Pro グレードの違いです。image_urls に参照画像を渡すと（配列で、モデル仕様によれば最大 9 枚の参照画像）、モデルはそれらに基づいて編集や再構図を行いながら、テキストプロンプトにも従います：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "この製品を日当たりの良い大理石のキッチンカウンターに置き、そばに新鮮なハーブを添え、朝の柔らかな光、ライフスタイル製品撮影",
      "image_urls": ["https://your-storage.example.com/product.jpg"],
      "resolution": "2K"
    }
  }'

Python では、上記のヘルパー関数に image_urls=[...] パラメータを渡すだけです——他は何も変わりません。参照画像を渡す場合でも prompt は必須です（API は prompt のないリクエストを拒否します：missing required field "prompt"）。

フィールド名が重要です：image_urls です。もっともらしく見える代替名——reference_image_urls、image_input、input_urls——はすべてスキーマによって additional properties '<name>' not allowed で拒否されます。他のモデルの編集エンドポイントからコードを移植している場合、まず修正すべきはここです。

正確な入力スキーマ

スキーマは厳格です：以下のリストにないフィールドはすべて 400 INVALID_REQUEST を返し、additional properties '<name>' not allowed が付きます。以下が受け入れられるすべてのフィールドです：

フィールド	型	必須	説明
prompt	string	はい	テキストから画像生成と編集の両方で必須。英語または中国語が使用可能。
aspect_ratio	string enum	いいえ	いずれか 1 つ：1:1、16:9、4:3、21:9、3:4、9:16、8:1、1:8。それ以外の値（例：3:2）→ 400。
resolution	string enum	いいえ	1K または 2K のみ。このグレードでは 4K はサポートされません。
image_urls	string[]	いいえ	編集用の参照画像（最大 9 枚）。渡すと参照モードに切り替わります。
seed	integer	いいえ	再現可能な出力のため。

思い浮かぶかもしれませんが、このモデルが受け付けないフィールド：negative_prompt、n、size、prompt_optimizer はすべて未知のプロパティとして拒否されます。バッチ（n）パラメータはありません——1 枚の画像につき 1 つのタスクを送信します。

本番環境の注意点と実測動作

送信時に 200 が返っても、画像が必ず生成されるわけではありません。wan2.7-image-standard は列挙値を同期的に検証します（誤った resolution や aspect_ratio は POST を即座に 400 INVALID_REQUEST で失敗させます）が、参照 URL は送信時に検証しません。形式が誤っているか到達不能な image_urls の項目は受け入れられ、200 と taskId が返され、その後タスクは約 1 秒で失敗します。これを直接検証しました：無効な参照 URL で作成したタスクが返す終態は以下のとおりです

{ "status": "fail", "error": { "code": "INVALID_REQUEST", "message": "invalid request parameters for this model" } }

実際の結果として：常に終態までポーリングし、data.status == "fail" の分岐で処理してください（data.error を読み取ります）。失敗タスクは HTTP 200 かつ data.status: "fail" として報告されます——失敗情報は data.error にあり、トップレベルの HTTP エラーではありません。送信前に参照 URL が公開アクセス可能であることを確認してください。

出力はすぐにダウンロードしてください。data.output[0].url は expireAt タイムスタンプ付きの一時リンクであり、永続的な CDN リソースではありません。タスクが成功した瞬間にバイト内容を取得して独自のストレージに移してください。期限切れの URL は 404 になります。すでにこの問題に遭遇している場合は、hiapi の出力 URL が 404 になる理由とその対処法を参照してください。

ポーリング vs. コールバック。上記の例は 5 秒ごとにポーリングしており、スクリプトや小規模バッチには問題ありません。本番のスループットでは、作成リクエストに callback を付加して、接続を保持し続けるのではなく、hiapi が終態イベント時に通知するようにしてください——具体的な仕組みはタスク作成ドキュメントを参照してください。

標準グレード vs. Pro：どちらを呼び出すべきか

hiapi は 2 つの Wan 2.7 Image グレードをホストしており、これらはパラメータではなく異なるモデル ID です：

• wan2.7-image-standard（本ガイド）——テキストから画像生成および参照画像編集、1K/2K、どちらの解像度でも固定価格1 枚あたり $0.0345 で課金。
• wan2.7-image/text-to-image——Pro グレード：テキストから画像生成のみ、最大 4K、固定価格 1 枚あたり $0.08。Wan 2.7 Image Pro ページおよび、それを使って4K の EC 製品画像を生成する詳細解説を参照してください。

参照画像に基づく編集が必要な場合、または 2K で十分で Pro の 1 枚あたり価格の半額未満で済ませたい場合は、標準グレードを選択してください。ネイティブ 4K 出力が特に必要な場合にのみ Pro を使用してください——これは標準グレードにできない唯一のことです。両者の現在の価格は価格ページを参照してください。

よくある質問

wan2.7-image-standard は画像編集をサポートしますか、それともテキストから画像生成のみですか？両方をサポートしており、同じモデル ID から利用できます。image_urls 配列を追加すると参照画像に基づく編集に切り替わり、省略すると純粋なテキストから画像生成になります。

最大解像度は？2K です。resolution フィールドは 1K と 2K のみを受け付け、オンライン API はそれ以外の値を拒否します。4K が必要な場合は Pro グレード（wan2.7-image/text-to-image）を使用してください。

タスクが 200 を返したのに失敗したのはなぜですか？参照 URL は送信時にはチェックされず、実行時にのみチェックされます。到達不能または形式が誤った image_urls の項目はタスクを作成し（HTTP 200）、その後 INVALID_REQUEST の終態で失敗します。data.status をポーリングし、URL が公開されていることを確認してください。

ネガティブプロンプトを設定できますか？できません。negative_prompt はこのモデルが受け付けるフィールドではありません（n、size、prompt_optimizer も同様です）。ポジティブな prompt と seed で誘導してください。