チュートリアル
HiAPI API で grok-imagine/text-to-image を使う方法:curl と Python ガイド
このページの内容
grok-imagine/text-to-image でできること
grok-imagine/text-to-image は HiAPI が提供するテキストから画像を生成するエンドポイントです。プロンプトと少数の生成パラメータを JSON として HTTP で送信すると、画像が返ってきます。約束事はこれだけです。SDK のインストールも、セッションの初期化も、最初の 1 枚を見るためのバックグラウンドタスクのポーリングも不要です。
開発者ワークフローにおける位置づけ:
- プロトタイピング。 端末のコマンド 1 本でアイデアからレンダリング済み画像まで到達できるため、プロンプトのアイデアを素早く試せます。
- コンテンツパイプライン。 ただの HTTP 呼び出しなので、他の API を呼ぶのと同じように、バックエンドサービス、キューワーカー、ビルドスクリプトから呼び出せます。
- プロダクト機能。 ユーザー向けの画像生成では、通常、予測可能なリクエスト/レスポンス処理、構造化されたエラー、リトライが必要になります。ステートレスなエンドポイントはこの 3 点に非常によく合います。
このエンドポイントではないもの:プロンプトを保存したり、生成画像のライブラリを管理したり、あなた自身のオーケストレーションを置き換えたりはしません。リクエストはあなたの責任、出力はあなたの責任、バイトの行き先もあなたが決めます。
本ガイドは、まずリクエストを通すこと、次にそれを信頼できるものにすることを重視します。curl でも Python でも呼び出しのパターンは完全に同じです。どちらも認証付きの同じ HTTP リクエストだからです。最小構成から始め、往復が成功することを確認してから、複雑さを積み上げてください。
前提条件と認証
最初の呼び出しの前に、以下を確認してください:
- HiAPI アカウントと API キー。 キーは機密情報として扱い、環境変数から読み込み、コミットされる可能性のあるスクリプトにハードコードしないでください。
- HTTP リクエストを送るツール。 初回テストには
curlで十分です。Python ではrequestsまたはhttpxを使います。両方とも後述します。 - HiAPI API ホストへのネットワークアクセス。 社内プロキシの背後にいる場合は、
curlと Python の両方が読めるよう、シェルにHTTPS_PROXYを設定してください。
キーは bearer トークンとして Authorization ヘッダーで渡します:
export HIAPI_API_KEY="your-key-here"
そして、すべてのリクエストに以下を含めます:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
すぐに身につけるべき 2 つの習慣:
- キーを URL に入れない。 リクエストのどの部分でも、認証情報をクエリ文字列に入れてはいけません。そこは最終的にログやシェル履歴に残るからです。
- 環境ごとに別のキーを使う。 開発用キーと本番用キーは別の値にすべきです。そうすれば、片方をローテーションしてももう片方に影響しません。
キーをまだ生成していない場合は、HiAPI ダッシュボードで作成し、シークレットマネージャー、またはバージョン管理から除外したローカルの .env ファイルに保存してください。echo $HIAPI_API_KEY が値を出力すれば、最初のリクエストを送る準備ができています。
curl での最小構成リクエスト
最小の有用な呼び出しは、モデル識別子とプロンプトだけを送ります。それ以外はすべてデフォルト値なので、画像が返るのを確認する前にパラメータをいじり始めないでください。
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine/text-to-image",
"prompt": "夕暮れの岩の多い海岸に立つ灯台、穏やかな海、柔らかな曇り空の光"
}'
各部分の役割:
-X POSTと JSON ボディの組み合わせは、生成エンドポイントの標準的な形式です。modelでgrok-imagine/text-to-imageを明示的に選択します。スクリプトではデフォルト値に頼らずモデル名を固定してください。そうすれば、デフォルトの変更が出力をこっそり変えることはありません。promptが唯一のコンテンツ入力です。初回テストでは、明確な一文に保ってください。
成功レスポンスは生成画像を含む JSON を返します。通常は URL または base64 ペイロードで、リクエストしたレスポンス形式によります。解析コードを書く前に、まず JSON フォーマッターでレスポンスを読んでください。端末で出力を見る場合は、python -m json.tool にパイプすると構造が読みやすくなります。
通ったら、生のレスポンスをファイルに保存し、既知の良好なベースラインを作りましょう:
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json \
-o response.json
リクエストボディを request.json に入れておけば、シェルのクォートと格闘せずにプロンプトを編集できます。プロンプトが長くなったり句読点を含んだりする場合に特に重要です。
Python での同じリクエスト
Python 版も同じ HTTP 呼び出しですが、使い勝手は良くなります。ネストしたクォートの代わりに辞書を使え、画像バイトを直接扱えます。
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "grok-imagine/text-to-image",
"prompt": "夕暮れの岩の多い海岸に立つ灯台、穏やかな海、柔らかな曇り空の光",
}
response = requests.post(
f"{base_url}/v1/images/generations",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
特に言及すべき 2 つの詳細があります。第一に timeout=120——画像生成は瞬時ではないため、タイムアウトのないリクエストは、上流で詰まったときにワーカーを無限にぶら下げてしまいます。第二に、解析の前に raise_for_status() を呼ぶことです。そうすれば、エラーレスポンスボディを成功した画像レスポンスと誤認しません。
画像を保存するには、2 つのレスポンス形態を処理します:
item = data["data"][0]
if item.get("b64_json"):
import base64
image_bytes = base64.b64decode(item["b64_json"])
else:
image_bytes = requests.get(item["url"], timeout=60).content
with open("output.png", "wb") as f:
f.write(image_bytes)
単一の依存関係セットを好むなら、httpx も使い方は同じで、httpx.post(..., json=payload) を使います。重要なのは、リクエストボディとヘッダーが curl の例と完全に一致していることです。この一貫性のおかげで 2 つの例は相互に置き換え可能になり、デバッグも予測可能になります。
アスペクト比に合わせたプロンプトの構成
横長の出力は特定の仕方で失敗します。モデルには埋めるべき水平方向の空間が大量にあるため、要素を繰り返したり、小さな被写体を空っぽの画面に浮かべたりします。これを解決するには、形容詞を積み重ねるのではなく、プロンプトの構造で対処します。
3 部構成の骨格を使います:
- 被写体——画像が何についてかを、最初に具体的に述べます。「港に入る貨物船」は「船」より良いです。
- スタイル——描画言語:写真、フラットベクター、水彩、映画のワンシーン。1〜2 語で十分です。
- 構図——画面をどう組織するか。横長比の成否はここで決まります。
構図では、水平方向の構造を明確に名指しします:
- 左から右、あるいはパノラマ的な読み順を指定する:「横長の遠景、被写体は右 3 分の 1 に、左側は開けた空」。
- 前景、中景、背景を分離した帯として描写する。横長の画面は自然にレイヤーとして読まれるからです。
- 端を何で埋めるかを明示する:「最も左に港のクレーン、最も右に開けた水域」。端は横長画像で最初に空になる場所です。
- ポートレートや正方形の構図を示唆するプロンプト——顔のクローズアップ、単一の中央配置オブジェクト——は避け、引き伸ばしや黒帯が入ることを想定する。
パノラマ形式でアスペクト比パラメータを設定するときは、プロンプトも同時に変更します。正方形向けに書かれたプロンプトは、横長キャンバスの中で正方形の概念を生みます。地平線、通り、並んだ物体、部屋に散らばる群衆など、水平方向の距離を含むシーンに書き換えてください。
一度に 1 つの変数だけを反復します。アスペクト比を固定して表現を変える。次に表現を固定して比率を変える。両方を出力と一緒に記録すれば、どの変更が本当に役立ったかを判断できます。
エラーとレスポンスコードの処理
まずステータスコードを読み、次にレスポンスボディを読みます。よくある失敗はそれぞれ異なる修正方法を示すので、混同すると時間を無駄にします。
401 Unauthorized
キーが欠落しているか、形式が誤っているか、失効しています。ヘッダーが正確に Authorization: Bearer <key> になっているか、環境変数が実際に展開されているか(値ではなく長さを出力する)、別環境のキーを誤って送っていないかを確認してください。
400 Bad Request
JSON としては有効な HTTP ですが、このエンドポイントには無効です。よくある原因:
modelの誤字または欠落。grok-imagine/text-to-imageでなければなりません。promptが空または欠落。- いずれかのパラメータの型が誤っている——数値であるべき場所に文字列、またはその逆。
- リクエストボディがそもそも有効な JSON でない。多くの場合
curlでのシェルクォート問題が原因。ボディをファイルに移して-d @request.jsonを使ってください。
エラーメッセージのボディを読んでください。通常、問題のあるフィールドを指し示します。
429 Too Many Requests
クォータを超える速度でリクエストを送っています。修正はクライアント側です:バックオフ、キューイング、リトライ。429 を受けたからといってリトライループを詰めないでください。事態は悪化します。
5xx Server Errors
これらは一時的または上流の状況です。遅延後にリトライし、何度試しても失敗が続く場合は、無限にリトライするのではなく、リクエストペイロードとレスポンスボディを捕獲して診断してください。
タイムアウトと接続エラー
これらは HTTP ステータスコードではなく、実務上最もよくある失敗です。requests が接続タイムアウトを投げた場合、リクエストはすでに処理されている可能性があります。リトライループを書く前に、あなたのユースケースでタイムアウトが「リトライ」を意味するのか「断念」を意味するのかを決めてください。
本番環境でのチューニングとリトライ
ベースラインのリクエストが通ったら、小さなステップで調整します。まずプロンプトの表現を変え、次にアスペクト比を変え、その後で他のパラメータを変え、出力を並べて比較します。各リクエストペイロードをその出力と一緒に保存すれば、結果は常に再現可能です。
本番用ラッパーは 3 つのことを行います。リトライに値する失敗だけをリトライし、デバッグに十分なログを記録し、断念するときは大きな音を立てて失敗します。
import time
import requests
def generate(payload, max_attempts=4):
for attempt in range(1, max_attempts + 1):
try:
r = requests.post(
f"{base_url}/v1/images/generations",
headers=headers,
json=payload,
timeout=120,
)
except requests.RequestException as exc:
log.warning("request failed attempt=%d err=%s", attempt, exc)
time.sleep(2 ** attempt)
continue
if r.status_code == 429 or r.status_code >= 500:
log.warning("retryable status=%d attempt=%d", r.status_code, attempt)
time.sleep(2 ** attempt)
continue
if r.status_code >= 400:
raise RuntimeError(f"{r.status_code}: {r.text[:500]}")
return r.json()
raise RuntimeError("exhausted retries")
このパターンについての説明:
- 上限付きの指数バックオフ(
2 ** attempt)により、レート制限されたクライアントがエンドポイントを繰り返し叩くのを防ぎます。多数のワーカーを動かす場合はジッターを加えてください。 - 429、5xx、ネットワークエラーのみをリトライする。 400 や 401 はどの試行でも同じように失敗します。
- 試行回数とステータスを記録するが、API キーは記録せず、プロンプトにユーザーデータが含まれる可能性がある場合は完全なプロンプトを絶対に記録しないでください。
- 総時間を制限する。 上限のないリトライループは、遅いリクエストをスタックしたワーカーに変えてしまいます。
自分のレイテンシと成功率を仮定せず測定してください。この 2 つの数値が、より多くの並列処理が必要なのか、より多くのバックオフが必要なのかを教えてくれます。本ガイドの最小リクエストから始め、上のヘルパー関数でラップし、そこから反復してください。