HiAPI API で ideogram-v3-character を使う方法：curl + Python ガイド

ideogram-v3-character とは何か、いつ使うべきか

ideogram-v3-character は HiAPI 上でキャラクターの一貫性に特化した画像生成モデルです。毎回の生成を独立したプロンプトとして扱うのではなく、キャラクターの参照画像を提供できるため、後続のレンダリングで同じ顔、服装、全体的なアイデンティティの特徴を保つことができます。

誰がと何をするかが同じくらい重要な場合に使うべきです：

• ストーリーボードや漫画：同じキャラクターが複数のコマに登場する。
• ゲームアセットのバリエーション：メインキャラクターの異なるポーズ、表情、服装を生成する。
• ブランドマスコット：多くの異なるシーンや背景で一貫した姿を保つ必要がある。
• 反復的なアートディレクション：類似性を失わずに複数回の調整でキャラクターを磨き上げる。

一度きりのイラストだけが必要で、以前の画像との一致を気にしないなら、汎用のテキスト画像生成モデルの方がシンプルです。参照画像がもたらす追加の構造こそが、ideogram-v3-character にリクエストフィールドを追加する価値がある理由です。

このモデルは他のモデルと同様に、統一された HiAPI 画像生成エンドポイントを通じて公開されているため、リクエスト構造は馴染み深いものに感じられるはずです。JSON ペイロードを送信し、非同期タスクのジョブ参照を受け取り、結果が準備できるまでポーリングします。このチュートリアルでは、このフローを正しく完了する方法に焦点を当てます。

リクエストを送信する前に：セットアップと認証

最初の呼び出しの前に、いくつかの準備が必要です。

1. API キー

HiAPI アカウントのダッシュボードで API キーを作成します。これは機密情報として扱ってください。すべてのリクエストを認可し、アカウントの課金に計上されます。

2. 環境変数による認証情報の管理

キーをソースファイルにハードコードしたり、git にコミットしたりしないでください。代わりに環境変数を使用します：

export HIAPI_API_KEY="your_api_key_here"

Python では次のように読み取ります：

import os
api_key = os.environ["HIAPI_API_KEY"]

ローカル開発で .env ファイルを使用する場合は、他の何よりも先に .gitignore に追加してください。

3. 参照画像の URL

キャラクターの一貫性は参照画像に依存するため、URL で渡せる画像を用意してください。その URL が公開アクセス可能であるか、他の方法で API からアクセスできることを確認してください。認証の背後にあるプライベートリンクは失敗します。正方形または縦長で、キャラクターの顔がはっきり見える画像が最適です。

4. HTTP リクエストの送信手段

コマンドラインの curl、または requests をインストールした Python 環境のいずれかで十分です。以下の例はいずれかを持っていることを前提としています。

これら 4 つが揃えば、最初のリクエストを送信できます。

動作する curl リクエストを行ごとに解析する

以下は HiAPI に ideogram-v3-character ジョブを送信する完全なリクエストです。プレースホルダーを自分の値に置き換えてください。

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v3-character",
    "prompt": "陽の差し込む作業場に立つ、親しみやすいロボット整備士。レンチを手に、斜め前からのアングル",
    "reference_images": [
      "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1
  }'

各部分の役割

• POST /v1/images/generations — 統一された HiAPI 画像生成エンドポイント。すべてのモデルが同じパスを使用します。
• Authorization: Bearer $HIAPI_API_KEY — 呼び出しを認証します。シェルが先ほど設定した環境変数を展開します。
• Content-Type: application/json — JSON ボディを送信するため、それを宣言する必要があります。
• model — ideogram-v3-character を選択します。これがないと、リクエストはどのモデルにルーティングすべきか分かりません。
• prompt — シーンの説明。ポーズ、環境、照明、雰囲気を記述し、キャラクターのアイデンティティは参照画像に任せます。
• reference_images — 画像 URL の配列。単一のキャラクターの場合、通常は 1 つのエントリで十分です。
• aspect_ratio — 出力形状。想定される用途（正方形、縦長など）に合わせます。
• num_images — ジョブごとに生成するバリエーションの数。

送信に成功すると、ジョブ識別子を含む JSON ボディが返されます。その値を控えてください。ポーリングのステップで必要になります。レスポンスにはジョブがキューに入っているか処理中であることを示すステータスフィールドも含まれる場合があります。ステータスがすでに終端状態であれば、結果がレスポンスに直接埋め込まれている可能性があります。そうでなければ、ポーリングを続けます。

Python での同じリクエスト

以下は Python での完全に同じ呼び出しです。環境変数からキーを読み取り、リクエストを送信し、ジョブ参照を出力します。

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "ideogram-v3-character",
    "prompt": "陽の差し込む作業場に立つ、親しみやすいロボット整備士。レンチを手に、斜め前からのアングル",
    "reference_images": [
        "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1,
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=60)
response.raise_for_status()

job = response.json()
print(json.dumps(job, indent=2))

job_id = job.get("id") or job.get("job_id")
print("Job id:", job_id)

Python バージョンに関する注記

• timeout=60 は、ネットワーク状況が悪いときにスクリプトが無限にハングするのを防ぎます。
• raise_for_status() は非 2xx レスポンスを例外に変換し、認証やバリデーションの問題にすぐ気づけるようにします。
• ジョブ ID の抽出 — HiAPI はレスポンスボディにジョブ識別子を返します。レスポンス構造によっては id または job_id の下にある場合があります。サンプルは両方をチェックしていますが、まず実際のレスポンスを確認してから、明確さのために正しいフィールド名をハードコードすべきです。

ペイロードは意図的に curl の例とまったく同じです。両者の間で JSON ボディをコピーし合うことは、デバッグ時の良い健全性チェックになります。一方が動作して他方が動作しない場合、問題はモデルではなくトランスポート層にあります。

キャラクター一貫性のための参照画像の扱い

参照画像こそが ideogram-v3-character と通常のテキスト画像生成モデルを分けるものです。これをうまく扱えば、作業の大半は完了します。

参照画像の提供方法

reference_images フィールドは URL の配列です。各 URL は API が直接取得できる画像を指す必要があります。ユーザーアップロードを保存している場合、未認証の GET リクエストを許可するバケットや CDN から提供するか、ジョブの実行中に有効な署名付き URL を生成してください。

本当に一貫性を保てる参照画像のコツ

• 各参照画像には 1 人のキャラクターだけを含める。 集合写真では、どの顔を保つべきか判断しにくくなります。
• 顔がはっきりし、照明が良好であること。 濃い影、極端な角度、遮蔽を避けます。
• ニュートラルまたは特徴的なポーズ。 正面または斜め前からのアングルがアイデンティティの特徴を最もよく保ちます。
• 服装を保ちたい場合は、参照画像の服装も一貫させる——モデルは見たものを再現します。
• 解像度は重要だが、過度にしない。 適度なサイズではっきりした顔の画像は、巨大でぼやけた画像に勝ります。

複数回の生成でキャラクターを識別可能に保つ

同じキャラクターの 2 番目のシーンを生成するときは、以前の生成出力ではなく同じ参照画像を再利用してください。生成画像を連鎖的に使うと、微妙なドリフトが蓄積する可能性があります。新しい参照画像が必要な場合——たとえば異なる服装——一度生成して確認し、そのファイルを後続のジョブの新しい参照画像として再利用します。

一貫性の検証

同じキャラクターの異なるポーズのバリエーションを 2〜3 個生成し、並べて比較します。顔や服装がドリフトする場合、通常は参照画像が弱いか曖昧であることが原因です。プロンプトを変更する前に、まず参照画像を引き締めてください。

非同期ジョブ：送信、ポーリング、結果の取得

画像生成には時間がかかるため、HiAPI は非同期で処理します。パターンは常に同じです：送信し、ジョブ ID を取得し、ジョブが終端状態に達するまでポーリングし、出力 URL を読み取ります。

ジョブのライフサイクル

1. 送信 — 前述の例のリクエストを送信します。
2. キュー待ち — ジョブは受け付けられ、容量を待っています。
3. 処理中 — モデルがレンダリング中です。
4. 完了または失敗 — 終端状態。結果（またはエラー）が利用可能です。

Python でのポーリング

job_id を取得したら、ジョブエンドポイントをポーリングします：

import time
import requests

def wait_for_job(job_id, api_key, interval=2, max_attempts=60):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    for attempt in range(max_attempts):
        resp = requests.get(url, headers=headers, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("completed", "succeeded"):
            return data
        if status in ("failed", "error", "canceled"):
            raise RuntimeError(f"Job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Job {job_id} did not finish in time")

結果の取得

ジョブが完了すると、レスポンスボディに出力が含まれます。通常は画像 URL の配列または単一の URL にメタデータが加わったものです。その URL からできるだけ早く画像をダウンロードしてください。一部の URL には時間制限があります。長期保存が必要な場合は、ジョブ成功直後にファイルを自分のバケットにコピーしてください。

ポーリングのマナー

• バックオフ。 2 秒間隔は短いジョブには問題ありません。多数のジョブをポーリングする場合は、間隔を増やすかジッターを使用してください。
• 試行回数を制限する。 max_attempts ガードは無限ループを防ぎ、コードに明確な失敗経路を提供します。
• 必要以上に速くポーリングしない。 各ポーリングは 1 つのリクエストです。エンドポイントを叩きまくってもレンダリングが早く完了することはありません。

よくあるエラーとその診断方法

問題が発生したとき、最速の道は通常、問題がリクエスト、参照画像、ジョブ自体のどこにあるかを切り分けることです。

認証の失敗

401 はキーが欠落している、形式が誤っている、または取り消されていることを意味します。リクエストを実行するシェルまたはプロセスで環境変数が実際に設定されているか確認してください。よくある落とし穴：あるターミナルで変数を設定したのに、別のターミナルでスクリプトを実行している。

バリデーションエラー

400 はほぼ常にペイロードを指します。以下を検証してください：

• model フィールドが正確に ideogram-v3-character であるか。
• reference_images が文字列ではなく配列であるか。
• 配列内のすべての URL が公開アクセス可能であるか。
• aspect_ratio がサポートされている値を使用しているか。

不明な場合は、最小限のペイロード——model、prompt、reference_images のみ——を送信し、その後フィールドを 1 つずつ戻してください。

完了しないジョブ

ポーリングが試行上限を超えた場合、ただ盲目的に再試行しないでください。ジョブステータスのレスポンスにメッセージがないか確認してください。よくある原因は、参照 URL に到達できないか、キューが過負荷であることです。一度再送信してください。再び停滞する場合は、プロンプトと参照画像を簡素化してください。

参照画像が黙って無視される

ジョブは成功したのにキャラクターが一致しない。これは通常、コードの問題ではなく参照画像の問題です：URL がエラーページ、PDF、またはプレースホルダー画像を返している可能性があります。ブラウザでその URL を自分で取得し、期待する画像が正しいコンテンツタイプで返されることを確認してください。

レート制限

429 はリクエストを送信しすぎたことを意味します。指数バックオフを使用してください。バッチ生成を行っている場合は、一度にすべて送信するのではなく、送信をずらしてください。

クイックチェックリスト

• キーは正しい環境に設定されていますか？
• 参照 URL は認証なしでアクセスできますか？
• ペイロードのフィールドの綴りは正しいですか？
• ポーリングには上限とバックオフが設定されていますか？
• 出力はその URL が期限切れになる前にダウンロードされていますか？

このチェックリストを順に確認すれば、ほとんどの失敗はすぐに解決できます。初回のエンドツーエンド実行が成功したら、それを既知の良好な例として保存し、新しいリクエストをそれと比較してください。多くのキャラクターとシーンに拡張するにつれて、この習慣だけで時間を節約できます。