HiAPI API で seedream-5.0-lite/text-to-image を呼び出す方法：curl と Python ガイド

この統合が実際に何をするか

HiAPI でテキストから画像への呼び出しを開始するとは、あなたのコードと非同期タスクキューとの間の短い対話です。あなたはリクエストを送信し、欲しい画像を記述します。プラットフォームはリクエストを検証し、タスクを受け入れ、識別子を返します。画像は最初のレスポンスには含まれず、その後で生成されます。次にあなたのコードはタスクを監視し、完了が報告されるまで待ち、最後にタスクが公開する URL から画像をダウンロードします。

この形態は重要です。なぜなら、それが統合の書き方を決定するからです。3つの異なる瞬間があります：送信、ポーリング、そして取得です。それぞれに独自の失敗モードがあります。送信はペイロードの形式が誤っているか、モデルパスが無効な場合に失敗します。ポーリングはループの書き方が誤っていると失敗します——速すぎる、短すぎる、または「まだ実行中」と「完了」を区別できない場合です。取得は、出力 URL を永続アドレスとして扱ったり、バイトをディスクに書き込むのを忘れたりすると失敗します。

内部では、seedream-5.0-lite/text-to-image は HiAPI プラットフォーム上の汎用テキストから画像へのモデルです。この正確なモデル識別子で呼び出します。送信するパラメータはこの種の呼び出しの通常のものです：モデル名、プロンプト、およびエンドポイントドキュメントで説明されている任意の出力サイズや数量の制御パラメータです。特別な SDK は不要で、通常の HTTPS クライアントで十分です。

この演習を読み終えると、curl で再現できるリクエスト、それを囲む Python 関数、レンダリングされたテキストを明確で読みやすくするためのプロンプトの言い回しのコツ、そして実際に終了するポーリングループが手に入ります。すべては同じ HiAPI エンドポイントを通じて実行されるため、一度呼び出しが成功すれば、後はパラメータの調整だけです。

curl でリクエストを構築する

コマンドラインから始めましょう。実行可能な curl 呼び出しはペイロードの基準です——それが成功すれば、他のすべての言語は単なる翻訳練習です。

最初の呼び出しの前に2つのものが必要です：HiAPI API キーと API のベース URL です。キーはベアラートークンとして Authorization ヘッダーに入ります。可能な限りシェル履歴に残らないようにしましょう。環境変数が最も簡単な習慣です。

export HIAPI_API_KEY="your_api_key_here"

リクエスト自体は JSON 本文を伴う POST です。モデル識別子は呼び出すパスセグメントであり、プロンプトは画像を説明します：

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/text-to-image",
    "prompt": "A minimalist poster for a coffee shop called North Roast, warm cream background, bold dark lettering"
  }'

HIAPI_BASE_URL はプラットフォームドキュメントに示されているテキストから画像への送信エンドポイントに設定してください。パスは製品インターフェースによって異なるため、推測せずコピーしてください。

さらにコードを書く前に、レスポンスを読みましょう。成功した送信は、タスク識別子とステータスフィールドを含む JSON オブジェクトを返します。ステータスは通常、タスクがキューに入れられたか処理中であることを示します——まだ完了していません。これは想定された動作です。返されたフィールド名を正確に書き留めてください。次の2つのセクションでそれらを参照します。

curl レベルでの2つのエラーが、ほとんどの初回失敗を引き起こします。1つ目はキーの欠落またはスコープの誤りです：レスポンスは認証エラーであり、モデルエラーではありません。2つ目は本文の形式エラーです——プロンプト内の引用符のエスケープ漏れ、末尾のカンマ、JSON が二重引用符を要求する箇所での単一引用符の使用などです。プラットフォームがペイロードを拒否した場合は、jq で整形表示して単独で検証してから、モデルのせいにしてください。

送信が識別子を返したら、有効なリクエストができたことになります。以降はすべて待機と取得です。

Python への移植

Python 版は小さく再利用可能な関数であるべきで、単一のプロンプトをハードコードしたスクリプトではいけません。requests（または好みに応じて httpx）を使用してください。呼び出し自体に特別なクライアントは不要です。

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_image(prompt: str, **params) -> dict:
    payload = {
        "model": "seedream-5.0-lite/text-to-image",
        "prompt": prompt,
        **params,
    }
    response = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=30)
    response.raise_for_status()
    return response.json()

ここには3つの意図的な選択があります。キーとベース URL は環境から取得されるため、関数は安全に送信できます。**params の万能パラメータにより、関数を編集せずに出力サイズやその他のドキュメント化されたオプションを渡せます。そして raise_for_status() は HTTP エラーを即座に例外に変換します。これはまさに望ましい動作です——送信時の 4xx は決して有効なタスクにならないため、混乱したレスポンス本文を検査するよりも早く失敗する方が優れています。

返された辞書がタスク記録です。開発中に一度印刷して、識別子とステータスの正確なキー名を把握してください。盲目的にインデックスするのではなく、小さなアクセサで残りのコードを読みやすく保ちましょう：

job = submit_image("A flat illustration of a paper plane over a city map")
print(job)

キューに入れられたタスクが印刷されれば、curl からの移植は正しいです。例外がスローされた場合、raise_for_status() からの例外メッセージが、認証の問題かペイロードの問題かを教えてくれます——シェルで遭遇するのと同じ2種類の問題です。

ネットワーク知識とレンダリングテキストのためのプロンプト作成

テキストから画像へのモデルは、プロンプトが表示されるべき内容を説明するときに最も強く、モデルが推論しなければならない知識を示唆するときに最も弱いです。seedream-5.0-lite/text-to-image は一般的な世界のコンテキスト——認識可能な物体、一般的なデザイン慣習、タイポグラフィスタイル——を活用できますが、そのコンテキストを固定するために十分な内容を依然として与える必要があります。

シーンのプロンプトでは、被写体、構図、視覚的スタイルを説明してください。「A cozy reading nook by a window, soft afternoon light, three-quarter view, muted earth tones」は、何を描くかだけでなく、どのようにスタイリングするかもモデルに伝えます。曖昧なプロンプトは平凡な画像を生み、具体的なプロンプトは使える画像を生みます。

レンダリングテキストはプロンプトが通常失敗する場所です。画像内にテキストを含める必要がある場合は、いくつかのルールに従ってください：

• 正確な文字列を引用する。 欲しいテキストを引用符で囲み、説明ではなくリテラルであることを明確にします。
• 短く保つ。 短いタイトルやブランド名は確実にレンダリングできますが、段落はできません。
• 位置とスタイルを指定する。 「The word "North" centered at the top in a bold sans-serif」は「some text at the top」に勝ります。
• 競合するテキストを避ける。 1つの画像に複数の異なるテキスト要素があると文字化けしやすくなります。複数必要な場合は、短く保ち、互いに離してください。
• 一度に1つの変数だけを反復する。 言い回し、レイアウト、スタイルを同時に変えるのではなく、言い回しを変えてください。そうしないと何が問題を解決したのか分からなくなります。

認識可能なコンテキストを伴うもの——製品カテゴリ、ポスターの種類、看板の種類——については、明示的に名前を付けてください。プロンプトがフックを与えるとき、モデルの事前知識が最も役立ちます。「A vintage travel poster for a coastal town」は「a poster」よりも多くの有用なコンテキストを持ちます。

パラメータを発明しないでください。プロンプトが望むテキスト位置を生み出さない場合は、未文書化のオプションを試す前に、まずプロンプト自体の言い回しを調整してください。

非同期タスクの処理と出力のダウンロード

ポーリングは統合が静かに壊れる場所です。タスクは非同期であるため、状態をチェックし、チェック間で待機し、最終的に諦め、どの状態値が「完了」を意味するかを正確に知るループが必要です。

import time

def wait_for_job(job_id: str, poll_interval: float = 3.0, timeout: float = 180.0) -> dict:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/{job_id}", headers=HEADERS, timeout=30
        )
        response.raise_for_status()
        job = response.json()

        status = job.get("status")
        if status in {"succeeded", "completed"}:
            return job
        if status in {"failed", "error", "cancelled"}:
            raise RuntimeError(f"Job {job_id} ended with status {status}")

        time.sleep(poll_interval)
    raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")

ポーリングパスと状態文字列はプラットフォームドキュメントに示されている内容に合わせて調整してください——この2つの詳細が上記のスケッチと最も異なる可能性があります。構造が鍵です：単調なデッドライン、チェック間のスリープ、明示的な成功と失敗のセット、そして半完成のタスクを返すのではなく例外をスローするタイムアウトです。

タスクが成功を報告したら、レスポンスには出力の URL が含まれます。その URL は一時的なものとして扱ってください。リンクを保存するのではなく、直ちにバイトをダウンロードしてください：

def download_image(url: str, path: str) -> None:
    response = requests.get(url, timeout=60)
    response.raise_for_status()
    with open(path, "wb") as f:
        f.write(response.content)

job = wait_for_job(job_id)
download_image(job["output"]["url"], "out.png")

続行する前に、ファイルが実際の画像であることを確認してください——開く、寸法を確認する、または少なくともバイト長が異常に小さくないかを確認します。サーバーが正常に閉じた場合、切り詰められたダウンロードは requests から見ると成功のように見えます。

一般的なエラーとその修正方法

初回統合でのほとんどの失敗は4つのカテゴリに分類されます。順番に対処してください。

送信が拒否される

最初の呼び出しが 4xx を返す場合は、レスポンス本文を印刷してください。認証エラーは、キーが欠落している、期限切れ、またはベアラートークンとして送信されていないことを意味します。スキーマエラーは、ペイロードの形式が誤っていることを意味します——モデルフィールドの誤り、プロンプトの欠落、またはドキュメント化されたパラメータのスペルミスです。JSON を単独で検証し、実行可能な curl の例と差分を取ってください。

タスクが完了しない

ループが無限に回転するかタイムアウトします。まずポーリング間隔を確認してください：スリープなしでエンドポイントを叩き続けるとレート制限を引き起こし、健全なタスクがスタックしているように見えることがあります。次に状態比較を確認してください——プラットフォームが success を返すのに succeeded にマッチしていると、すべてのタスクが未完了に見えます。推測するのではなく、生の状態値を一度ログに記録してください。

出力 URL が 404 または 403 を返す

出力 URL は署名付きで時間制限があります。長時間ポーリングしてから取得すると、リンクが期限切れになっている可能性があります。完了後すぐに取得し、結果を保持する必要がある場合はリンクではなくファイルを保存してください。

画像はレンダリングされるがテキストが文字化けする

これはプロンプトの問題であり、コードの問題ではありません。テキストを短くし、正確に引用し、テキスト要素の数を減らし、スタイル指示をより明示的にしてください。どの調整が役立ったかを知るために、一度に1つの変更だけを行って再実行してください。

リクエストがハングまたはタイムアウトする

送信とポーリング呼び出しには常に明示的なタイムアウトを設定してください。タイムアウトのないリクエストはワーカープロセスを無期限にブロックする可能性があり、デッドラインのないポーリングループは一時的な中断をスタックしたプロセスに変えてしまいます。

予期しない動作が発生した場合は、依然として失敗する最小の curl 呼び出しに縮小してください。生の HTTP リクエストが異常な動作をする場合、Python レイヤーは問題ではありません——curl が再び動作すれば、Python への移植は機械的な作業です。seedream-5.0-lite/text-to-image のモデルページには現在のパラメータとレスポンス形態が記載されているので、フィールド名を仮定する前にそこを確認してください。