チュートリアル
HiAPI API で ideogram-v4.5 を使う方法：curl、Python、そして動作するリクエスト
HiAPI 上の ideogram-v4.5 がもたらすもの
画像内のテキストが本当に重要なとき、選ぶべきモデルは ideogram-v4.5 です。ポスターのレイアウト、ロゴのグラフィック、パッケージのモックアップ、ソーシャルカード——見出しの綴りが一つ間違っていたり、キャプションがぼやけたりするだけで素材が台無しになる場面こそ、このモデルの価値が発揮される場所です。読みやすくある必要のない抽象的なテクスチャや写真風の風景を生成したいなら、汎用画像モデルのほうが安価で高速なのが普通です。
本記事は統合ガイドであり、モデルのレビューではありません。読み終えるころには、実際に動作するリクエスト、同じ処理を行う Python クライアント、そして人々がつまずきがちな部分——アスペクト比パラメータ、非同期タスクのポーリング、出力の取得——を処理する再利用可能なヘルパー関数が手に入ります。
早い段階で腹に落としておくべきことが一つあります。HiAPI 上の画像生成は非同期タスク API です。リクエストを送信し、識別子を受け取り、タスクが完了するまでポーリングします。レスポンスボディにすでに画像が含まれていると仮定したコードは動きません。以下の各節はすべてこのパターンに向かっています。
リクエストを送る前に
初回呼び出しの前に、四つのものを用意する必要があります。
1. API キー
HiAPI アカウントのコンソールで作成し、ソースコード管理から遠ざけてください。スクリプトに貼り付けるのではなく、環境変数としてエクスポートします：
export HIAPI_API_KEY="your_key_here"
2. ベース URL
すべてのリクエストは HiAPI API のベース URL に、生成エンドポイントの具体的なパスを付加して送信します。プラットフォームのドキュメントに現在のパスが記載されています。ドキュメントの記述が異なる場合は、ブログ記事（本記事を含む）で見たパスをハードコードしないでください。
3. モデル識別子
リクエストボディで渡すモデル文字列が ideogram-v4.5 を識別します。プラットフォームのモデル一覧に表示される正確な大文字小文字を使用してください。モデル識別子は文字通りに照合されるため、少しでもずれると有用な提案ではなく検証エラーが返ります。
4. パラメータリファレンス
ideogram-v4.5 のモデルページは、リクエストボディが受け付けるフィールドの権威ある情報源です：プロンプトの長さ制限、サポートされるアスペクト比、出力フォーマット、および任意のシードやスタイル制御。コードを書く前に一読してください。そこに記載されていないパラメータは黙って無視されたり拒否されたりする可能性があり、値を推測することはデバッグ時間を無駄にする最も一般的な方法です。
これら四つが揃えば、最初のリクエストを送信できます。
動作する curl リクエスト
以下は最小限の送信例です。アカウントで異なる値が表示される場合は、プラットフォームのドキュメントにあるエンドポイントパスとモデル識別子に置き換えてください。
curl -X POST "$HIAPI_BASE_URL/<generation-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram-v4.5",
"input": {
"prompt": "A vintage travel poster for the Amalfi Coast, bold serif headline reading \"AMALFI\", warm sunset palette, grainy print texture"
}
}'
各部分の役割：
Authorization— bearer トークン認証。ヘッダーの欠落や形式の誤りは 401 の最も一般的な原因です。Content-Type—application/jsonでなければなりません。一部の HTTP クライアントは POST 時に自動設定しないため、サーバー側で紛らわしいパースエラーが発生します。model— リテラルのモデル識別子。ドキュメントに示されているとおり、リクエストボディのトップレベルに配置します。input.prompt— 生成指示。上記のように、画像内にレンダリングしたいテキストを引用符で囲むと、モデルはそれを説明ではなくリテラルのコピーとして扱います。input.*— その他すべての生成パラメータ（アスペクト比、フォーマット、シードなど）はこのネストされたオブジェクトに属し、promptと並びます。
送信に成功すると、タスク識別子とステータスフィールドを含む JSON オブジェクトが返ります。このレスポンスに画像は含まれません——これは想定どおりの動作です。識別子を保存してください。ポーリングの手順で使用します。
Python で同じ呼び出しを行う
Python 版は一対一の翻訳です。requests を使用し、同じリクエストボディを共有するので、両者を並べて比較できます。
import os
import json
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
GEN_PATH = "/<generation-path>" # confirm in platform docs
payload = {
"model": "ideogram-v4.5",
"input": {
"prompt": (
"A vintage travel poster for the Amalfi Coast, bold serif "
'headline reading "AMALFI", warm sunset palette, grainy print texture'
)
},
}
response = requests.post(
BASE_URL + GEN_PATH,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
data=json.dumps(payload),
timeout=30,
)
response.raise_for_status()
job = response.json()
print(job)
意図的な選択が二つあります：
json=ではなくjson.dumpsにより、送信フォーマットが curl の例と目に見えて一致します。どちらでも動作しますが、明示的に書くことでデバッグ時に実際に送信している内容を検査しやすくなります。timeout=30は送信のみに使用します。送信は高速で、生成はそうではありません。送信呼び出しにポーリング用の短いタイムアウトを継承させてはいけません。そうしないと正常に動作しているタスクを失敗として報告してしまいます。
出力された job 辞書にはタスク識別子と現在のステータスが含まれます。識別子をどこかに保存してください——ポーリングループがそれに依存しています。
アスペクト比と出力フォーマットの制御
アスペクト比と出力フォーマットはリクエストボディのパラメータであり、別個のエンドポイントではありません。それらはプロンプトと同じ input オブジェクト内にあります：
{
"model": "ideogram-v4.5",
"input": {
"prompt": "...",
"aspect_ratio": "<ratio from docs>",
"output_format": "<format from docs>"
}
}
ここで重要なのは値を推測しないという規律です。各生成モデルは固定の比率とフォーマットの列挙を公開しており、モデルによって受け入れる綴りが異なります——16:9 と 16x9、png と PNG など。モデルがサポートしない値を渡すと、通常は検証エラーが発生するか、さらに悪い場合は黙ってデフォルト出力にフォールバックし、プロンプトのバグのように見えます。
したがってワークフローは次のとおりです：
- プラットフォームで ideogram-v4.5 のモデルページを開き、サポートされるアスペクト比の一覧と出力フォーマットの一覧を逐語的にコピーします。
- これらの値をコード内の小さなホワイトリストに入れ、無効な入力が API に届く前に呼び出し側で失敗するようにします。
- ダウンストリームのレイアウトに合った比率をデフォルトにします。画像を 1200×630 のソーシャルカード枠に収めるなら、正方形を生成してからコンテンツを切り取るのではなく、その比率に近い値を選びます。
テキストが密集した画像には追加の注意事項があります：極端な比率（超ワイドなバナー、超縦長のポスター）はテキストのレンダリングに使えるスペースを圧縮します。本当に読みやすくする必要がある見出しには、パノラマ的な極端な比率よりも中景の横長または縦長の比率のほうが安全です。
非同期タスクの処理と結果のダウンロード
一度の生成のライフサイクルは三段階です：送信 → ポーリング → 取得。
送信
前の節ですでにこの手順は押さえています。レスポンスはタスク識別子とステータス（例：queued や processing）を返します。
ポーリング
その識別子でタスクステータスエンドポイントをポーリングし、ステータスが完了を報告するまで続けます。このプロセスをまともな状態に保つルールが二つあります：
- ポーリング間にスリープを入れる。 約 1 秒から始めて段階的にバックオフします。ステータスエンドポイントを連打してもタスクは早く完了せず、レート制限に引っかかるリスクがあります。
- 待機時間に上限を設ける。 最大試行回数または期限を設定し、超過したら無限ループではなく明示的にエラーを報告します。
import time
def wait_for_job(job_id, headers, base_url, status_path,
max_attempts=60, initial_delay=1.0, factor=1.5):
delay = initial_delay
for _ in range(max_attempts):
r = requests.get(
f"{base_url}{status_path}/{job_id}",
headers=headers,
timeout=30,
)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status in ("succeeded", "completed", "success"):
return data
if status in ("failed", "error", "cancelled"):
raise RuntimeError(f"job {job_id} ended with status {status}: {data}")
time.sleep(delay)
delay *= factor
raise TimeoutError(f"job {job_id} did not finish in time")
アカウントの正確なステータス文字列とステータスパスについてはプラットフォームのドキュメントを参照してください——ドキュメントの値に照合し、認識できないステータスは成功ではなくまだ実行中として扱います。
取得
タスクが完了を報告すると、レスポンスには出力の場所（通常は URL）が含まれます。通常の GET でそれをダウンロードし、バイトをディスクに書き込みます。出力 URL には時間制限がある可能性があるため、URL を保存して後で使うのではなく、できるだけ早くダウンロードしてください。このループを書くために必要な知識はすべて送信レスポンスの構造から得られます——学ぶべき別個の「画像取得」API はありません。
再利用可能なヘルパー関数へのカプセル化
それぞれがポーリングを再実装する三つのインラインスクリプトはメンテナンス上の問題です。一度パッケージ化しましょう。
import os, json, time, requests
class IdeogramClient:
def __init__(self, base_url, api_key, gen_path, status_path,
poll_attempts=60, poll_factor=1.5):
self.base_url = base_url.rstrip("/")
self.gen_path = gen_path
self.status_path = status_path
self.poll_attempts = poll_attempts
self.poll_factor = poll_factor
self.headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
def generate(self, prompt, **params):
body = {"model": "ideogram-v4.5", "input": {"prompt": prompt, **params}}
r = requests.post(self.base_url + self.gen_path,
headers=self.headers,
data=json.dumps(body), timeout=30)
r.raise_for_status()
job = r.json()
done = self._wait(job["id"])
url = done["output"]["url"] # confirm shape in docs
return self._download(url)
def _wait(self, job_id):
delay = 1.0
for _ in range(self.poll_attempts):
r = requests.get(f"{self.base_url}{self.status_path}/{job_id}",
headers=self.headers, timeout=30)
r.raise_for_status()
data = r.json()
if data.get("status") in ("succeeded", "completed", "success"):
return data
if data.get("status") in ("failed", "error", "cancelled"):
raise RuntimeError(data)
time.sleep(delay)
delay *= self.poll_factor
raise TimeoutError(job_id)
def _download(self, url):
r = requests.get(url, timeout=60)
r.raise_for_status()
return r.content
使用時は一度の呼び出しだけです：img_bytes = IdeogramClient(...).generate("...", aspect_ratio="<from docs>")。done["output"]["url"] のアクセス方法とステータス文字列をドキュメントのレスポンス構造に合わせて調整してください——この二箇所がアカウントごとに微調整が必要になる可能性が最も高い部分です。
よくあるエラーとデバッグのコツ
最初の一週間の失敗のほとんどは五つのカテゴリに分類されます。
401 / 403 — 認証。 キーの欠落、コピー＆ペースト時の空白混入、または Bearer プレフィックスの欠落。実際に送信しているキーの前後各四文字を出力してください。環境ファイルからの末尾改行が定番の犯人です。
400 — JSON 形式エラーまたは不明なフィールド。 リクエストボディを文字列連結で組み立てている場合、プロンプト内のエスケープされていない引用符が JSON を壊します。ボディを辞書として構築し、json.dumps でシリアライズしてください。JSON がパースできるなら、次の容疑者はモデルが受け付けないパラメータ名です——キーをモデルページと一文字ずつ照合してください。
404 / モデルが見つからない。 通常はモデル識別子の綴りや大文字小文字の誤り、またはエンドポイントパスが古くなっていることが原因です。どちらも記憶や古いチュートリアルからではなく、プラットフォームのドキュメントからコピーしてください。
429 — レート制限。 ほぼ常にポーリングが攻撃的すぎることが原因です。初期ポーリング遅延とバックオフ係数を増やしてください。送信側では 429 および 5xx レスポンスに対してジッター付きのリトライを追加しますが、4xx の検証エラーはリトライしないでください——毎回同じように失敗します。
タスクは成功したが画像が開けない。 ダウンロードしているのが JSON エラーページではなくバイトであることを確認してください。ダウンロード GET で raise_for_status() を呼ぶことで、この種の問題のほとんどを捕捉できます。また、ダウンロード URL は短期的に有効なものとして扱い、セッションをまたいでキャッシュしないことを確認してください。
判断に迷ったら、呼び出しチェーン全体の各呼び出し——送信、各ポーリング、ダウンロード——の完全なレスポンスボディとステータスコードを記録してください。API は通常どこが間違っているかを明確に示しています。バグはたいてい私たちが見に行かなかっただけです。
動作する送信、ポーリングループ、適切なエラー処理が揃えば、ideogram-v4.5 は他のあらゆる HiAPI モデル呼び出しと同様に実際のパイプラインに組み込めます。
関連記事
すべての記事を見る →-
チュートリアル
HiAPI API で hailuo-2.3-fast/image-to-video を呼び出す方法：curl と Python の実践
高速・低コストな画像から動画へのティアにおける最初の実行可能なリクエスト — モデル ID から MP4 のダウンロードまで
-
チュートリアル
HiAPI APIでhailuo-2.3/text-to-videoを呼び出す方法：curl、Python、実行可能なリクエスト例
-
チュートリアル
HiAPI で Kandinsky 6.0 Pro のテキストto動画を使用する：curl と Python チュートリアル
リクエスト優先の実践デモ：プロンプトから動画クリップへの呼び出しを構築し、リクエストを送信し、完了状態をポーリングし、結果をダウンロードする