HiAPI API で recraft-v4.1/text-to-image を使う方法：curl と Python ガイド

このエンドポイントでできること

recraft-v4.1/text-to-image はテキストから画像を生成するモデルのエンドポイントです。リクエストボディにテキストプロンプトといくつかの整形オプションを送信すると、生成された画像データが返ってきます。多段階のパイプラインを自分で組み立てることなく、1 回の呼び出しで完成した画像を得たい場合に最適です。

HiAPI では、このモデルはアグリゲーションモードに含まれます。1 つのベース URL、1 つの認証ヘッダー、そしてエンドポイント間で一貫したリクエスト/レスポンス構造です。評価したい画像モデルごとに SDK や認証情報セットを個別に接続する必要はなく、クライアントを HiAPI 上の recraft-v4.1/text-to-image のエンドポイントに向けるだけで、残りのコードはそのまま維持できます。これはプロトタイピング段階で特に重要です。毎回トランスポート層を書き直すことなく、プロンプト、スタイル、モデルを比較したいからです。

この呼び出しを理解する実用的な方法は次のとおりです：

• Prompt —— 生成したい画像の自然言語による説明。
• Style —— 出力の視覚的な処理方法を導くリクエストボディのフィールド。
• Resolution —— 出力サイズを決定するリクエストボディのフィールド。

3 つとも同じ JSON ボディ内で送信されるため、プロンプトエンジニアリングと出力の整形は 1 回のラウンドトリップで完了します。これが適切なエンドポイントかどうかを判断している場合、答えは通常イエスです。同期的でプロンプト駆動の画像生成が必要で、ベンダー側の配管の詳細をアプリケーションコードの外に置きたい場合に当てはまります。

前提条件と認証

初めての呼び出しの前に、以下を用意してください：

• HiAPI アカウントと API キー。ソース管理の対象外にし、環境変数から読み込んでください。
• 簡単なスモークテスト用の curl、および requests をインストールした Python 3（Python の例を使う場合）。
• 実際にレンダリングしたいプロンプト——粗くても、接続が正しいかを検証するには十分です。

HiAPI の認証はリクエストヘッダーに基づきます。API キーはヘッダーで渡され、curl、Python、その他の HTTP クライアントから呼び出す場合でも同じヘッダーパターンを使用します。モデルの選択はエンドポイントのパスで行うため、モデルを切り替えても認証ヘッダーは変わりません。

安全なローカル設定は次のとおりです：

export HIAPI_API_KEY="your-key-here"

そしてシェルコマンドでは $HIAPI_API_KEY を参照し、Python では os.environ["HIAPI_API_KEY"] を参照します。コミットされる可能性のあるスクリプトにキーをハードコードしないでください。また、ログやエラーレポートに貼り付けないようにしてください。キーが漏洩した場合は、履歴から消そうとするのではなく、アカウント設定でローテーションしてください。

以下の例は 2 つを前提としています：HiAPI API のベース URL、および recraft-v4.1/text-to-image のモデルパスです。実装に組み込む前に、これら 2 つをアカウントの API リファレンスで確認してください。正確なホストとパスは、このガイドの中で記憶ではなく現在のドキュメントからコピーすべき唯一の内容だからです。

実行可能な curl リクエスト

キー、エンドポイント、ペイロード構造がすべて正しく機能することを確認する最速の方法は、curl 呼び出し 1 回です。このリクエストはプロンプトと整形フィールドを含む JSON ボディを送信し、API キーをヘッダーで渡します：

curl -X POST "$HIAPI_BASE_URL/recraft-v4.1/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist isometric illustration of a developer workstation, soft pastel palette, clean background",
    "style": "illustration",
    "resolution": "1024x1024"
  }'

この呼び出しについて、いくつか注意すべき点があります：

• エンドポイントのパス。 モデル名はパスに含まれます。後で別のモデルに切り替える場合は、リクエストを再構築するのではなく、そのパスセグメントを変更します。
• クエリ文字列ではなくボディを使用。 prompt、style、resolution はすべて JSON ボディに含まれます。これにより URL は安定し、ペイロードも記録・再生しやすくなります。
• ヘッダー認証。 Authorization ヘッダーがキーを運び、Content-Type は application/json である必要があります。

最初の試行で 200 以外のレスポンスが返ってきた場合は、次の順序で確認してください：キーがシェルに設定されているか、ベース URL に重複した末尾スラッシュがないか、JSON ボディが有効か（末尾のカンマが原因であることが多い）。呼び出しが成功したら、正確なコマンドをドラフトファイルに保存してください。動作することがわかっている curl 呼び出しは、SDK やクライアントの変更ごとに比較するための基準になります。

同じリクエストを Python で

実際のコードでは、呼び出しを小さな関数にカプセル化して、リトライ、ログ記録、モデル切り替えの一元化された置き場所を持たせてください。requests を使用します：

import os
import requests

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


def generate_image(prompt, style="illustration", resolution="1024x1024", timeout=120):
    url = f"{HIAPI_BASE_URL}/recraft-v4.1/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "prompt": prompt,
        "style": style,
        "resolution": resolution,
    }
    response = requests.post(url, headers=headers, json=payload, timeout=timeout)
    response.raise_for_status()
    return response.json()

残しておく価値のある設計上のポイント：

• data= ではなく json= を使用。 json= に dict を渡すと、コンテンツタイプを設定してボディをシリアライズしてくれるため、ペイロードは curl 版とバイト単位で一致します。
• 明示的なタイムアウト。 画像生成は瞬時ではありません。余裕のあるタイムアウトにすることで、遅いが正常なリクエストを誤って失敗と報告するのを避けられます。クライアントのデフォルト値に依存しないでください。
• まず raise_for_status()。 レスポンスボディを読み取ろうとする前に HTTP エラーを例外に変換することで、4xx や 5xx が画像データと誤認されることは決してありません。
• 環境駆動の設定。 ベース URL とキーの両方を環境から取得するため、この関数はローカル、ステージング、本番環境の間で移植可能です。

関数はパース済みの JSON を返します。この JSON から画像を抽出する方法が次の話題であり、ほとんどの統合がここでつまずきます。

同期画像レスポンスの処理

recraft-v4.1/text-to-image は画像データを同期的に返します。画像はリクエストと同じ HTTP レスポンスで返され、ポーリングループも、追跡すべきタスク ID もありません。これによりクライアントは単純になりますが、2 つの責務があなたのコードに移ります——ペイロードのデコードと、失敗の明示的な処理です。

堅牢な処理経路は次のとおりです：

1. パース前にステータスを確認。 200 以外はすべてエラーとして扱い、レスポンスボディを表示します。これが問題の多くを説明してくれます。
2. 画像フィールドを意識的に読み取る。 レスポンス JSON は画像データを運びます。受け取ったフィールドに応じて、URL かエンコードされた画像バイトのいずれかです。どちらか一方を仮定せず、両方の経路を処理してください。
3. 防御的なデコード。 ペイロードが base64 エンコードされている場合は、デコードしてバイトをファイルに書き込みます。バイナリデータをテキスト専用の経路に通したり、ターミナルに出力したりしないでください。
4. ペイロードサイズを制限。 同期画像レスポンスは一般的な JSON に比べて非常に大きくなります。クライアントが対応していればディスクにストリーミングし、複数のレスポンスを同時にメモリに保持することを避けてください。

base64 ペイロードを保存する最小限の手順：

import base64

data = generate_image("A calm forest at dawn, soft light")
image_b64 = data["image"]  # adjust to the actual field name in the response
with open("out.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

特別に対処する価値のある失敗モードが 2 つあります。タイムアウトはバックオフ付きでリトライすべきですが、冪等性が期待できる場合に限ります——画像を再生成すると異なる結果になるため、各試行でプロンプトを記録してください。クライアントエラー（不正なボディ形式や無効なオプション値など）は、リトライしても自然に直りません。素早く失敗させ、レスポンステキストを記録してください。最後に、デコード前に画像フィールドの存在を検証してください。そうすれば、スキーマ変更やエラーペイロードは、紛らわしいデコードエラーではなく明確な例外を引き起こします。

ユースケースに合わせてスタイルと解像度を調整

style と resolution は、返される結果に最も大きく影響する 2 つのリクエストボディフィールドであり、どちらもプロンプトと一緒に渡されるため反復コストが低くなります。

Style

style は出力の視覚的な処理方法を導きます。一連の画像のスタイルを一致させるために使用します——たとえば、製品イラストや記事のヒーロー画像のバッチで同じスタイルを固定し、セットのように見せます。結果がしっくりこない場合は、まずスタイルがコンテンツに合っているかを確認してください。イラスト向けのスタイルをリアルなプロンプトに適用すると、テキストと衝突します。詳細を追加する前に、固定したスタイルで単純なプロンプトを試してください。そうすれば、悪い結果がスタイルによるものか表現によるものかを判断できます。

Resolution

resolution は出力サイズを決定します。目的の用途に合わせてください。アバターやサムネイルには正方形に近いサイズを選び、バナーやヒーロー画像にはより横長のサイズを選びます。実用的なルールが 2 つあります：

• 要求できるなら拡大しない。 小さく生成して拡大するのではなく、最終的な表示サイズに近い画像を直接生成します。
• アスペクト比に注意。 レイアウトが特定の比率を期待している場合は、後からクロップするのではなく、その比率に合う解像度を選んでください。

予期しない出力のデバッグ

画像がおかしいと感じたら、一度に 1 つの変数だけを切り離してください。プロンプトを固定して style を変え、次に両方を固定して resolution を変えます。それでも改善しない場合は、形容詞を追加するのではなく、具体的な名詞と明確な構図の手がかりでプロンプトを書き直してください。また、誤った値の型を密かに送信していないことも確認してください。許容されるオプションに一致しないスタイル文字列は、検証ロジックによって拒否されるか無視される可能性があります。各呼び出しの正確なリクエストボディを記録してください。これが、ある画像が何から生成されたかについての唯一の信頼できる記録です。

本番環境向けのカプセル化

先ほどの小さな関数の価値は、それを強化したときに現れます。本番品質のカプセル化は 4 つのことを行うべきです：

• トランスポートをカプセル化。 1 つの関数が URL、ヘッダー、ペイロード構造、タイムアウトを所有します。呼び出し側はプロンプトとオプションだけを渡し、それ以外は何も渡しません。
• バックオフ付きリトライを追加。 タイムアウトと 5xx レスポンスに対して有限回のリトライを行い、4xx エラーは決してリトライしません。画像生成は冪等ではないため、リトライ上限を低く設定し、プロンプトを各試行に関連付け続けてください。
• 結果だけでなくリクエストを記録。 プロンプト、スタイル、解像度、ステータス、所要時間を記録します。なぜ画像がこう見えるのかと誰かが尋ねたとき、そのログが答えになります。
• モデルをパラメータにする。 モデルパスをパラメータとして渡し、デフォルト値を recraft-v4.1/text-to-image にします。これにより、別の画像モデルへの切り替えはリファクタリングではなく設定変更になり、並行評価のコストが低くなります。

カプセル化層は薄く保ってください。キャッシュ、キューイング、ストレージ戦略をその中に追加するのは避けてください。それらは上の層に属し、API 呼び出しとは独立して進化できるようにします。安定したインターフェースは、テストがトランスポート層をモックして送信予定のペイロードをアサートできることも意味し、これによりほとんどの統合エラーを実際のリクエストに到達する前に捕まえられます。

認証、動作することがわかっているリクエスト、明示的なレスポンス処理が揃えば、HiAPI から curl と Python で recraft-v4.1/text-to-image を呼び出すために必要なものはすべて手に入ります。そしてその後は、残りのコードに触れることなくモデルを切り替えられます。