チュートリアル
HiAPI API で seedream-4.5/text-to-image を使う方法:curl と Python のサンプル
開発者向けの、最小構成で動く統合の実践ガイド
このページの内容
seedream-4.5/text-to-image でできること
seedream-4.5/text-to-image は HiAPI API で提供されるテキストから画像を生成するエンドポイントです。テキストのプロンプトと任意のいくつかのパラメータを送信すると、モデルが生成した画像を返します。シーンのイラスト、製品のモックアップ、コンセプトアート、あるいは画像内に読みやすい文字を描画する必要があるビジュアル——看板、ラベル、短い見出し——の作成に利用できます。このエンドポイントはステートレスです。各リクエストは独立した 1 回の生成であるため、再現とバリエーションの制御はあなたのアプリケーションコード側にあります。
他の HiAPI モデルと同じ統一インターフェースの背後で動作するため、認証は 1 回だけで済み、同じベース URL とエラー規約を使用し、モデルを切り替えるときも新しい統合パターンを学ぶ必要はありません。seedream-4.5/text-to-image のモデル詳細ページには現在のパラメータ名と許容値が記載されています——フィールドの正式な情報源としては本文ではなくこのページを参照してください。
リクエスト構造:何を送り、何を受け取るか
すべてのテキストから画像への呼び出しは同じ構造です。モデルの HiAPI エンドポイントに JSON ボディを付けた POST リクエストを送ります。リクエストボディにはモデルが必要とするフィールドを含め、レスポンスには生成画像とそのリクエストに関するメタデータが含まれます。
送信するもの
prompt(文字列、必須):画像の説明。これが主要な制御点です。下記のプロンプトの節を参照してください。aspect_ratioまたはサイズ関連のフィールド(任意):出力キャンバスの形状を制御します。モデル詳細ページに記載された正確なフィールド名を使用してください——他のモデルのパラメータ名と同じだと仮定しないでください。- モデルページに記録されたモデル固有のオプション(スタイルや品質のヒントなど)。不要なフィールドは省略してください。API がデフォルト値を適用します。
受け取るもの
成功時のレスポンスは JSON オブジェクトです。コードで実際に読むことが多いフィールドは通常次のとおりです。
- 画像ペイロード:レスポンススキーマに応じて、生成画像の URL、または base64 エンコードされた画像文字列のいずれかです。コードはエンドポイントが実際に返す形式を扱う必要があります。どちらなのかはモデルページに記載されています。
- リクエストのメタデータ(識別子やステータスなど)。ログ記録やサポートに役立ちます。
すべてのフィールドがすべてのバージョンで保証されているわけではないため、固定のスキーマを仮定するのではなく、レスポンス構造を検証してください。必要なフィールドだけを探し、それ以外を任意として扱うパーサーを構築すれば、統合は軽微なレスポンスの変化に耐えられます。
最初に動かす curl リクエスト
最小の有効な呼び出しは、プロンプトだけを送り、他は何も送りません。プレースホルダーのキーとプロンプトを自分のものに置き換えて、実行してください。
curl -X POST "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "夕暮れの静かな街角のカフェ、暖かい窓明かり、OPEN と書かれた黒板の看板",
"aspect_ratio": "1:1"
}'
行ごとの説明:
- URL はそのモデルの HiAPI エンドポイントを指します。モデル識別子はドキュメントと完全に一致させてください。
Authorizationヘッダーには API キーを載せます。環境変数を使えば、キーがシェルの履歴やソースファイルに残りません。Content-Type: application/jsonは、リクエストボディを JSON として解析するようサーバーに伝えます。- JSON ボディにはプロンプトと任意のアスペクト比を含めます。まずは 1 枚の画像と 1 つのプロンプトから始め、オプションを追加する前に文言を反復してください。
呼び出しが成功すると、前の節で説明した画像データがレスポンスに含まれます。出力をファイルに保存する(または返された URL を開く)して、さらに先へ進む前に確認してください。認証エラーが出た場合は、キーが存在することとヘッダーの綴りが正しいことを確認します。パラメータエラーが出た場合は、フィールド名をモデルページと照らし合わせて再確認します。
同じリクエストを Python で実装する
Python 版は標準の requests ライブラリを使用します——SDK は不要です。
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image"
payload = {
"prompt": "夕暮れの静かな街角のカフェ、暖かい窓明かり、OPEN と書かれた黒板の看板",
"aspect_ratio": "1:1",
}
response = requests.post(
URL,
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
result = response.json()
print(result)
ここでは 2 つの細部が重要です。第一に、手組みの文字列ではなく json=payload を渡すこと——requests がコンテンツタイプを設定し、正しくシリアライズします。第二に、明示的な timeout を設定すること。画像生成は典型的な API 呼び出しより時間がかかることがあるため、明確な失敗モードを持つ余裕のあるタイムアウトのほうが、ぶら下がったリクエストより優れています。
出力される結果は生のレスポンスです。実際のコードでは、エンドポイントが返す画像フィールド(URL または base64)を抽出し、その URL を 2 回目のリクエストでダウンロードするか、base64 をバイトにデコードしてディスクに書き込みます。その抽出ロジックは小さなヘルパー関数にまとめ、テストと本番コードが同じ解析ロジックを共有できるようにしてください。
写実性と読みやすい文字のためのプロンプト作成
プロンプトの品質は、他のどのパラメータよりも出力品質を左右します。最もよくある 2 つの目標は、写真のように写実的なシーンと、画像内の明瞭で読みやすい文字です。
写実性
写真家が構図を決めるようにシーンを描写します。被写体、光、時間帯、レンズ感、環境などです。具体的な名詞は抽象的な形容詞に勝ります。「いい感じのカフェ店」ではなく、「大きな窓から正午の光が差し込む細長いカフェの店内、木製のカウンター、浅い被写界深度」と書きます。「photograph」や「documentary photo」のような短いスタイルヒントを加えて、モデルをイラスト調から遠ざけます。1 つのプロンプトには主要な被写体を 1 つだけ保ちます。競合する被写体はしばしば混乱した構図を生みます。
読みやすい文字
画像に文字を含める必要がある場合は、正確な文字を引用符で囲み、短く保ちます。OPEN と書かれた看板や FRESH BREAD と書かれたラベルは、長い文章よりもはるかに信頼できます。文字がどこに現れるかを指定します——「カウンターの上に OPEN と書かれた黒板の看板」——そうすればモデルはその文字が特定の物体に属することを理解します。文字が崩れる場合は、短くし、周囲のシーンを単純化して再生成します。文言を少し調整するのは普通のことです。数回の反復は想定しておいてください。
反復
一度に 1 つの変数だけを変えます。まずプロンプト、次にアスペクト比、最後にスタイルオプションです。プロンプトと、良い結果を生んだ設定を保存します。この記録が再生成の基準線になり、デバッグが当て推量になるのを防ぎます。
アスペクト比と出力設定の選び方
アスペクト比は、モデルが何かを描く前に構図を決めます。デフォルトに合わせるのではなく、用途に合わせて選んでください。
- 正方形(
1:1):ソーシャル投稿、アバター、商品タイル。シンプルで安全です。 - 横長(例:
16:9):バナー、キービジュアル、プレゼンスライド。広いシーン——地平線、店構え、広々とした室内——を促します。 - 縦長(例:
9:16):モバイル画面、ストーリー、ポスター。明確な縦方向の被写体を持つプロンプト——立っている人物、高い建物——が最も効果的です。
プロンプトが広いシーンを描写しているのに縦長キャンバスを要求すると、モデルは構図を切り取るか歪めるしかありません。説明と画面比を一致させてください。下流のパイプラインでは、最大のユースケースに合うサイズで生成し、後から縮小します。小さな画像を拡大すると正しく見えることはほとんどありません。複数の形式が必要な場合は、1 枚の画像をさまざまなレイアウトに切り抜くのではなく、比率ごとに個別に呼び出してください。
アスペクト比以外の出力設定(品質ヒント、スタイル制御)はモデル固有です。モデルページに記録されているものだけを設定し、追加の各パラメータはそのまま流用するデフォルトではなく、テストすべき変数として扱ってください。
エラーとレート制限の処理
本番統合の失敗理由は予測できます。キーの誤り、無効なパラメータ、タイムアウト、レート制限です。それぞれを明示的に処理してください。
解析する前に検証する
まず HTTP ステータスコードを確認します。2xx は成功です——その後にレスポンスボディを解析します。4xx は通常、リクエストに問題があることを意味します。キーが未認証、JSON の形式が不正、またはサポートされていないパラメータ値です。これらは再試行しても自然に解決しないため、レスポンスボディを記録し、呼び出し元に報告し、リクエストを修正してください。5xx はサーバー側の問題で、通常は一時的です。
バックオフ付きの再試行
後で成功する可能性がある失敗だけを再試行します。429 レスポンス、タイムアウト、接続エラー、およびほとんどの 5xx ステータスコードです。ジッター付きの指数バックオフを使用します——短い基準間隔で待ち、試行ごとに倍にし、総試行回数に上限を設けます。400 や 401 は決して再試行しないでください。クォータを無駄に消費するだけです。
import time, random
def generate(payload, max_attempts=5):
for attempt in range(max_attempts):
try:
r = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
except requests.RequestException:
pass # ネットワークエラー:以下で再試行
else:
if r.status_code == 200:
return r.json()
if r.status_code not in (429, 500, 502, 503, 504):
raise RuntimeError(f"回復不能:{r.status_code} {r.text}")
time.sleep(min(2 ** attempt + random.random(), 30))
raise RuntimeError("再試行回数を使い切りました")
制限を守る
リクエスト量をアカウントに示されたレート制限以下に保ち、429 はより強く再試行する合図ではなく、速度を落とす合図として扱ってください。ワーカーに同時実行数の上限を追加し、試行ごとにリクエスト ID をログに記録して、後からレート制限や失敗を診断できるようにします。画像呼び出しは生成された出力に課金されるため、画像を生成する再試行は無料ではありません——リクエストを送る前にまず入力を検証してください。
テスト呼び出しから本番へのチェックリスト
公開前に、次の運用ポイントを確認してください。
- キー管理:キーは環境変数またはシークレットマネージャーに保存し、ソース管理には決して置きません。定期的にキーをローテーションし、漏洩が疑われる場合は直ちにローテーションします。
- タイムアウト:すべての外向き呼び出しに明示的なタイムアウトがあり、タイムアウト発生時の処理を呼び出し元が計画していること。
- ログ記録:呼び出しごとにリクエスト ID、プロンプトのバージョン、パラメータ、ステータス、レイテンシを記録します。必要に応じてキーと完全なペイロードをマスクします。
- プロンプトのバージョン管理:受け入れられた出力を生んだプロンプトと設定を保存し、再現とロールバックを可能にします。
- コスト意識:生成は出力に課金されるため、バッチサイズを制限し、不要な再試行を避け、再利用する結果をキャッシュします。
- グレースフルデグラデーション:再試行後も生成が失敗する場合は、ページを壊すのではなく、キャッシュされた画像やプレースホルダーにフォールバックします。
このガイドの単一の curl 呼び出しから始め、小さな Python ヘルパー関数に移し、その後で並列化とバッチ処理を追加してください。統合を拡張する際、フィールド名を確認する場所は seedream-4.5/text-to-image のモデルリファレンスページです。