チュートリアル
HiAPI API で krea-3/text-to-image を使う方法:curl、Python、そして実行可能なリクエスト
このページの内容
なぜ集約 API 経由で krea-3/text-to-image を呼び出すのか
新しい画像モデルが出るたびに、新しい SDK、新しい認証方式、新しいレスポンスの癖が増えていきます。画像機能をひとつだけリリースするなら、そのコストは許容できるでしょう。しかし複数をリリースする場合——あるいは将来的にモデルを自由に差し替えたい場合——それは作業における主要なコストになります。
HiAPI 経由で krea-3/text-to-image を呼び出せば、このコストを消せます。単一のエンドポイント規約、単一の認証情報、単一のレスポンス構造に対して一度だけ統合すれば済みます。モデル識別子はコードベースの分岐ではなく、リクエストペイロード内のひとつのフィールドになります。出力を他の画像モデルと比較したいときや、ワークロードを移行したいときは、統合をやり直すのではなく文字列をひとつ変えるだけです。
このモデルに限って言えば、実利は具体的です:
- すべてのリクエストが同じ構造を共有します。 テキストからの画像生成呼び出しはプラットフォーム全体で同じ認証とペイロード規約に従うため、初回呼び出しで得た知識はそのまま次のモデルにも活かせます。
- モデルに依存しないアプリケーションコード。 モデル名は設定に保持します。
krea-3/text-to-imageでプロトタイプを作り、後で別のモデルに切り替えて提供する場合でも、HTTP 層を変更する必要はありません。 - 使用量を観測する統一的な入口。 課金、リクエストログ、エラーレスポンスはすべて同じ画面から得られ、N 個のベンダーダッシュボードを回る必要はありません。
- キーが少なくて済む。 いくつのモデルを呼び出しても、保存・ローテーション・権限付与すべきキーはひとつだけです。
代償は集約の一般的な代償です:汎用インターフェースを介して作業するため、モデル固有の癖は正規化されます。実際にはこれこそが望ましいことです——正規化された入力、予測可能なエラー、そしてモデルを調整可能なパラメータとして扱う自由。
本チュートリアルは意図的に範囲を絞ります。実行可能なリクエストを組み立て、2 回実行し(まず curl、次に Python)、プロンプトの言い回しが写真スタイルとイラストスタイルの出力をどう誘導するかを観察し、それから初回呼び出しの問題の大半を占める少数の失敗ケースをデバッグします。アーキテクチャ図もフレームワーク論もありません——次の 5 分で送れるリクエストと、問題が起きたときに使うチェックリストだけです。
前提:HiAPI アカウントを持ち、ダッシュボードから API キーを読み取れ、ターミナルと Python インタープリタに慣れていること。それ以外は不要です。
リクエストを送る前に
初回呼び出しの前に満たすべき条件が 3 つあります。これを正しくやれば残りの大半はチューニングです。間違えれば、間違ったレイヤーのデバッグに 1 時間を費やすことになります。
1. アカウントと API キー
HiAPI にログインし、ダッシュボードから API キーを取得します。機密情報として扱ってください:環境変数またはシークレットマネージャーに置き、コミットされたファイルに入れず、プロンプトやサポートメッセージにも決して入れないこと。以下の例は環境変数から読み取ります:
export HIAPI_API_KEY="your-key-here"
組織が複数のキーをサポートしている場合は、この統合専用のキーを使ってください。そうすれば他の実行とは独立してローテーションできます。
2. エンドポイント規約と認証ヘッダー
HiAPI のリクエストは bearer token 認証を使います——他の何百もの API で見たのと同じパターンです:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
HiAPI API リファレンスであなたのアカウントのリージョン用に示されている base URL を使い、そこに記載された画像生成パスを追加してください。記憶やブログ記事(本記事を含む)からパスを推測しないこと——API リファレンスが唯一の真実の源であり、パスはリクエストの中で予告なく変わりうる唯一の部分です。チュートリアルの提案:リファレンスを一度確認し、URL をコピーし、設定値として保存してください。
3. モデル識別子は綴りを完全に一致させる
モデル識別子は krea-3/text-to-image です。名前空間のプレフィックスとハイフンを記述どおりに正確に保ってください——krea3/text2image や単なる krea-3 はモデル未検出で失敗します。大文字小文字も重要です。定数として保存しましょう:
MODEL = "krea-3/text-to-image"
この文字列こそが統合をモデル非依存にするものなので、名付けを行い、各呼び出し箇所にハードコードするのではなく設定として扱ってください。
事前に把握しておく必要のないこと
初回呼び出しの前に、画像サイズ、シード、ステップ数のフィールド名を知っている必要はありません。最小構成から始めましょう:認証、モデル識別子、プロンプト。200 レスポンスを得たら、それからパラメータを 1 つずつ追加します。なぜなら 5 つのフィールドを設定した失敗リクエストは容疑者を 5 つ与えますが、最小限の失敗リクエストは容疑者を 1 つしか与えないからです。
curl で実行可能なリクエストを組み立てる
curl は初回呼び出しの 2 つの問題——認証情報とペイロード構造——を切り分ける最速の方法です。SDK のバージョンも、仮想環境も、非同期ランタイムもなく、ネットワーク上の 1 リクエストだけです。
最小限の呼び出しはモデルが本当に必要とするものだけを運びます:認証ヘッダー、モデル識別子、プロンプト。
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "krea-3/text-to-image",
"prompt": "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
}'
実行前に 2 点。第一に、$HIAPI_BASE_URL はプレースホルダーです——HiAPI API リファレンスの base URL に設定し、同じリファレンスでパスセグメントも確認してください。第二に、-sS フラグは出力を静かにしつつエラーは表示します。これはデバッグ時にまさに望む挙動です。
健全なレスポンスの姿:生成された画像への参照またはデータ、およびリクエストメタデータを含む JSON オブジェクト。正確な構造は API リファレンスに記載されています。まだ観察していない構造に対して解析コードを書かないでください。実際のレスポンスをファイルに保存し、基準となる事実を得ましょう:
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"krea-3/text-to-image","prompt":"A neon-lit alley after rain, cinematic still"}' \
-o response.json
その後 jq またはエディタで検査します。このファイルがテストフィクスチャになります:Python に移植したとき、出力を比較してください。Python のレスポンスが response.json と構造的に異なるなら、問題はコード側であってモデル側ではありません。
まず curl でやる理由は診断のてこの効き方です。curl 呼び出しが成功すれば、キーは有効で、URL は正しく、モデル識別子も解決できる——したがってそれ以降の失敗はすべてアプリケーションコードにあります。curl 呼び出しが失敗すれば、エラーボディがこの 3 つのどれが問題かを教えてくれ、しかもコードを 1 行も書いていません。
最小リクエストが成功したら、パラメータを 1 つずつ追加します。追加するたびに curl を再実行してください。成功したリクエストペイロードは保存しておきましょう。テストの受理済み入力フィクスチャになります。
Python での同じリクエスト
Python 版は意図的に退屈に保ちます:同じ URL、同じヘッダー、同じ JSON ボディ。重点は移植性です——curl で検証したリクエスト構造は、再設計なしにスクリプトへ、そしてサービスへと移行できるべきです。
import os
import json
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "krea-3/text-to-image"
def generate(prompt: str) -> dict:
response = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={"model": MODEL, "prompt": prompt},
timeout=120,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate(
"A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
)
print(json.dumps(result, indent=2))
いくつかの意図的な選択:
- リテラルではなく環境変数を使う。 キーはソースに決して現れません。変数が欠けていれば
os.environ["HIAPI_API_KEY"]は起動時に大声で失敗します。これは 3 層下で不可解な 401 に遭遇するより良いことです。 - 解析前に
raise_for_status()を呼ぶ。 HTTP エラーは例外として浮上してほしいのであって、たまたま JSON であるエラーボディからフィールドを読もうとしてKeyErrorが出るのは困ります。 - 余裕のあるタイムアウト。 画像生成は即時エンドポイントではありません。それを反映したタイムアウトを設定し、本番では明示的に扱います(本番の節を参照)。
- 文字列の手組みではなく
json=を使う。 シリアライズはライブラリに任せましょう。JSON の手組みは末尾カンマや引用符エラーの温床です。
一度実行し、出力を先ほど取得した response.json と比較してください。構造は一致するはずです。レスポンスが返す内容に応じて画像参照を出力するか画像データをデコードします——ここでも、仮定した構造ではなく観察した構造に対してコードを書いてください。
MODEL が定数なので、同じ generate() 関数はプラットフォーム上のどの画像モデルにも使えます。これが集約モデルの報酬です:サービスへの移動、2 つ目のモデルの追加、出力の A/B テストは、書き直しではなくパラメータ変更で済みます。
写真スタイルとイラストスタイルを制御する
スタイルはスイッチではなく、モデルを押しやる方向です。そして krea-3/text-to-image は、写真家やイラストレーターと協働するときに使うのと同じてこに反応します:被写体、媒体、光、そして工芸の語彙です。
写真スタイルへ押しやる
写真の出力は主に機材とその帰結を名指すことにかかっています。カメラ、レンズ、フィルム、実在の光を描写する語は「リアル」という一言より効きます。
- 媒体と撮影方法を名指す:「35mm photograph」「editorial portrait」「documentary still」。
- 光を名指す:「overcast daylight」「golden hour backlight」「single softbox at camera left」。
- 不完全さを名指す:「slight motion blur」「visible grain」「shallow depth of field」。
"a fisherman on a dock" と "a weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph, visible grain" を比べてください。2 番目のプロンプトは、漠然とした描写ではなく、写真の質感と光へとモデルを制約します。
イラストスタイルへ押しやる
イラストは伝統、線の質、配色を名指すこと——そして多くの場合、たった今学んだ写真の手がかりを取り除くことにかかっています。
- スタイルを名指す:「flat vector illustration」「ink and watercolor」「mid-century editorial illustration」「isometric line art」。
- 線を名指す:「clean uniform strokes」「loose gestural linework」。
- 配色を名指す:「restrained two-color palette」「muted pastels」。
プリセットではなく反復
プロンプトは調整可能な設定として扱ってください。一度に 1 つの次元だけを変える——媒体のフレーズだけを差し替え、被写体と光はそのままにする——そうすれば各トークンが何をするのか分かります。プロンプトの変種とそれが生んだ出力の短いログを残しましょう。このログはどんなプリセット集より価値があります。なぜならあなたのモデルとあなたのコンテンツに合わせて較正されたものだからです。
リクエストがプロンプト以外のパラメータ——サイズ、シードなど——を公開しているなら、プロンプトを固めた後に調整してください。その前にやると、プロンプトと 3 つのパラメータを同時に変えてしまい、どれが効いたのか分からなくなります。
よくあるエラーのトラブルシューティング
初回呼び出しの失敗の大半は 4 つのカテゴリに分類できます。チェックリストを順に実行し、各ステップで 1 つのレイヤーを除外していきます。
認証の失敗
症状:認証情報や権限に関するメッセージを伴う 401 または 403。
- コマンドを実行しているシェルで本当に
HIAPI_API_KEYが設定されていますか?echo $HIAPI_API_KEY——空文字列は誤ったキーによく似ています。 - ヘッダーはまさに
Authorization: Bearer <key>ですか?Bearerの欠落、余分な引用符、キーに貼り付いた改行はすべて失敗を招きます。 - キーは失効しているか、別の環境に限定されていませんか?疑わしければ再生成し、curl 呼び出しで再テストしてください。
不正な形式のリクエストペイロード
症状:ボディ、フィールド、または JSON 解析に関するメッセージを伴う 400。
- 送信前に JSON を検証してください。curl では、プロンプト内のエスケープされていない引用符 1 つでボディが壊れます。Python では
json=がこれを処理してくれます——これを好むもう 1 つの理由です。 Content-Type: application/jsonがあるか確認してください。- フィールド名を API リファレンスと照合してください。正しく綴られた値でも間違ったフィールド名の下にあれば 400 です。
- 最小ペイロード——モデルとプロンプトだけ——に戻し、それが通ることを確認してからフィールドを 1 つずつ追加してください。
誤ったモデル識別子
症状:404、またはモデルが不明・利用不可を示す 400。
- あなたの文字列を
krea-3/text-to-imageと 1 文字ずつ比較してください。名前空間プレフィックス、ハイフン、パスセグメントが重要です。 - ドキュメントからのコピー&ペーストで予期しない空白やスマートクォートが入っていないか確認してください。
- 値がコードのどこかで設定のデフォルト値に上書きされていないか確認してください。
レートとクォータのレスポンス
症状:429、または制限や残高不足に関するメッセージ。
- エンドポイントを叩き続けるのではなく、バックオフして短い遅延の後に再試行してください。
- ダッシュボードで使用量と残高を確認してください。
- これが開発中に起きたなら、想定より速く発火する再試行ループを探してください——
tryブロック内の失敗リクエストと積極的な再試行はレート制限を急速に消耗します。
以上のどれでも解決しない場合、レスポンスから完全なリクエスト ID とエラーボディを取得し、サポートに送ってください。集約 API のエラーボディは通常、問題を指し示すのに十分具体的です。誤りはそれを貼らずに言い換えてしまうことです。
本番投入
現在のリクエストはプロトタイプです。4 つの実践が、継続的に稼働できるものに変えます。
文字列ではなくカテゴリでエラーを扱う
HTTP ステータスコードを挙動にマッピングします:認証エラーは設定の不備であり、誰かを呼び出すべきです。4xx のペイロードエラーはコードの不備であり、リクエストを大声で失敗させるべきです。429 と 5xx は一過性であり、指数バックオフとジッターで再試行すべきです。400 を決して再試行しないこと——同じ不備を確認するためにクォータを浪費するだけです。明示的なタイムアウトを設定し、タイムアウトは一過性として扱ってください。
if response.status_code == 429 or response.status_code >= 500:
raise TransientError(response.status_code)
response.raise_for_status()
プロンプトを記録し、バージョン管理する
生成されたすべての画像は、それを生んだ正確なプロンプトまで追跡できるべきです。プロンプト、モデル識別子、パラメータ、レスポンスのリクエスト ID を一緒に保存してください。プロンプトテキストはバージョン管理された設定として扱います——関数に埋め込まれたリテラルではなく、設定ファイルにチェックインされた prompt_v3 文字列として。出力品質が変わったとき、プロンプトが変わったのか、パラメータが変わったのか、モデルが変わったのかを知る必要があります。
モデル名を設定に保持する
krea-3/text-to-image は定数または設定エントリ内の 1 箇所にだけ現れるべきです。これが集約モデルの報酬です:モデルの差し替え、比較の実行、ロールバックが、新しいコードパスのデプロイではなく設定変更になります。また、将来さまざまなワークロードをさまざまなモデルにルーティングすることも容易にします。
フィクスチャに対してテストする
本チュートリアルで取得した成功レスポンスをフィクスチャとして保存してください。解析コードがそれを処理できることをアサートし、記録したエラーボディを使ってエラーマッピングをテストします。こうすれば、ユーザーより先にレスポンス構造の漂いを発見できます。
最小限の curl 呼び出しから始め、レスポンス構造を確認し、そのまま Python に移植し、その後プロンプトを一度に 1 つの次元ずつ反復してください——そして変わりうるエンドポイントの詳細については HiAPI API リファレンスを確認しましょう。