hiapi API で ideogram-v4 を使う方法：curl、Python、そして実際に動作するリクエスト

Ideogram モデルの評判は、ほとんどの画像モデルがいまだに苦手としているある一点に築かれています。それはタイポグラフィです。ポスターの見出しは正しく綴られ、ロゴの文字はくっきりとし、看板のテキストが崩れて読めなくなることはありません。ideogram-v4 は他のすべての画像・動画モデルと同様、同じ統一タスク API を通じて hiapi 上で利用できます。本ガイドではこのリクエストを一通り解説します。コピー＆ペーストできる curl 版、完全な Python スクリプト、schema が実際に検証するパラメータ（Ideogram のネイティブ API が公開しているものとは異なります）、そして実運用で遭遇するエラーです。

何を作るか、何を用意するか

目標：POST /v1/tasks にテキストプロンプトを送信し、タスクの完了を待ち、指定どおりに文字がレンダリングされた画像をダウンロードします。

必要なものは 1 つだけです：hiapi の API キー —— コンソールで作成します。各リクエストで Bearer トークンとして使用します。無料の未認証ティアはありません。以下のすべての呼び出しは Authorization: Bearer sk-... を前提としています。

hiapi 上のすべてのモデルと同様、ideogram-v4 は非同期です。タスクを作成するとすぐに taskId が返り、その後は結果をポーリングするかコールバックを受け取るかのどちらかです。「1 つの HTTP 接続で 40 秒待つ」ような同期モードは存在しません——そして画像生成においては、そもそもそれを望むこともないでしょう。

最小限のリクエスト：curl

タスクを作成：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v4",
    "input": {
      "prompt": "ヴィンテージのアールデコ調ジャズフェスティバルのポスター。メインの見出しテキスト \"MIDNIGHT & BRASS\" は太字のゴールドの書体で、背景は濃紺、サブ見出し \"Live at the Riverside, Fridays\" はその下に細身のサンセリフ体で。",
      "rendering_speed": "BALANCED",
      "aspect_ratio": "3:4"
    }
  }'

レスポンスは即座に返り、タスク id は data.taskId にあります（tk-hiapi-... の形式）。それをポーリングします：

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-XXXXXXXX \
  -H "Authorization: Bearer $HIAPI_KEY"

画像生成中、data.status は queued から handling へと順に遷移します。終態に達すると success または fail になります。成功時、画像 URL は data.output[0].url にあります：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-XXXXXXXX",
    "status": "success",
    "output": [
      { "url": "https://.../result.png?...expireAt=..." }
    ]
  }
}

この URL について 1 点注意があります：署名付きで、有効期限があります（expireAt）。タスク成功後すぐにバイト内容をダウンロードし、自分のストレージに保存してください。ホットリンクをデータベースに保存してはいけません。

ideogram-v4 が実際に受け付けるパラメータ

これは正確に扱う価値のある部分です。Ideogram 自身のドキュメントを読んだことがあれば、そのネイティブ API がスタイルプリセット、マジックプロンプトの切り替え、ネガティブプロンプト、バッチ数を公開していることがわかるでしょう。hiapi の ideogram-v4 タスク schema は意図的に小さく作られており、バリデータは schema 外のあらゆるものを拒否します。以下はライブ API で確認済みの全範囲です：

フィールド	必須	型 / 値
prompt	はい	string
rendering_speed	はい	"TURBO"、"BALANCED"、"QUALITY"
aspect_ratio	いいえ	"1:1"、"16:9"、"4:3"、"9:16"、"3:4"
seed	いいえ	整数

2 つの必須フィールドは強制検証されます。空の input を送ると以下が返ります：

invalid input: prompt: missing required field "prompt";
rendering_speed: missing required field "rendering_speed"

列挙値を誤って綴ると、エラーが有効な値を教えてくれます：

invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'

また、上表にない Ideogram ネイティブインターフェースの内容は、未知のプロパティとして拒否されます——style_type、magic_prompt、negative_prompt、num_images、size、および画像入力はすべて 400 を返します。例えば：

invalid input: <root>: additional properties 'style_type' not allowed

実際の影響：

• タイポグラフィの制御は完全にプロンプトに依存します。 レンダリングしたい正確なテキストを二重引用符でプロンプトに入れ、フォントを描写してください（「太字のアールデコ書体」「細身のジオメトリックサンセリフ体」「手描き看板書体」）。これが Ideogram の代名詞であるポスター/ロゴ/看板の効果を得る方法です——頼れるスタイルパラメータは別途存在しません。
• 1 タスクにつき 1 枚の画像。 n や num_images はありません。4 つの候補が欲しければ 4 つのタスクを送信し、それぞれの taskId を個別にポーリングしてください。
• seed は再現性のための調整つまみです。 同じプロンプト + 同じ seed は安定した出発点を与え、文言の反復に役立ちます。
• テキストから画像への生成のみ。 このモデルの schema は参照画像を受け付けません。ワークフローが画像から画像への生成を必要とする場合は、それをサポートするモデルを選んでください——統合コードを変更せずにモデルを切り替える方法については1 つの API キーで複数の画像モデルを呼び出す方法を参照してください。

rendering_speed について：TURBO は高速ティアで、プロンプトの文言を反復する際の下書きに適しています。QUALITY は低速で精細なティアで、最終レンダリングに適しています。BALANCED は妥当なデフォルトです。料金は画像ごとの使用量に基づいて課金されます——現在の価格は料金ページを確認してください。

完全な Python スクリプト

同じ流れ——作成、ポーリング、ダウンロード——をタイムアウトと終態処理付きで示します。唯一の依存関係は requests です（pip install requests）。

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_KEY']}",
    "Content-Type": "application/json",
}

def create_task(prompt: str, rendering_speed: str = "BALANCED",
                aspect_ratio: str = "1:1", seed: int | None = None) -> str:
    input_obj = {
        "prompt": prompt,
        "rendering_speed": rendering_speed,
        "aspect_ratio": aspect_ratio,
    }
    if seed is not None:
        input_obj["seed"] = seed
    resp = requests.post(API_BASE, headers=HEADERS,
                         json={"model": "ideogram-v4", "input": input_obj},
                         timeout=60)
    data = resp.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: HTTP {resp.status_code} {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")

if __name__ == "__main__":
    task_id = create_task(
        prompt=('"Driftwood" という名前のコーヒーブランドのミニマルなロゴをデザインしてください。'
                'Driftwood という単語は温かみのあるセリフ体のロゴタイプで、モノクロ、'
                'クリーム色の背景'),
        rendering_speed="QUALITY",
        aspect_ratio="1:1",
        seed=42,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    png = requests.get(url, timeout=120).content   # 署名付き URL は期限切れになる - すぐにダウンロード
    with open("driftwood-logo.png", "wb") as f:
        f.write(png)
    print("saved driftwood-logo.png,", len(png), "bytes")

本番環境での注意点：コールバック、冪等性、エラー

ポーリング vs. コールバック。 1 枚ずつ生成するインタラクティブなツールでは、数秒ごとのポーリングがよりシンプルで、まったく十分です。バッチ処理やサーバー側のワークロードでは、作成リクエストにコールバックを追加して、hiapi が終態結果を POST してくれるようにします：

{
  "model": "ideogram-v4",
  "input": { "prompt": "...", "rendering_speed": "BALANCED" },
  "callback": { "url": "https://your.domain.example/hiapi/hook", "when": "final" }
}

作成時に強制される制約が 2 つあります：URL は https:// であり、公衆からアクセス可能でなければならず、when は "final" のみを受け付けます——他の値を試すと API は直接 invalid callback.when: only 'final' is supported を返します。ハンドラは taskId に対して冪等にし、素早く 2xx を返し、コールバックが決して届かないタスクのためにポーリングのフォールバックを用意してください。コールバックが届かない場合は、キューのせいにする前にhiapi のタスクコールバックが発火しない理由に従って調査してください。

冪等性。 タスク作成は冪等ではありません——成功した POST /v1/tasks は毎回新しいタスクとなり、新たな課金が発生します。taskId を受け取ったらすぐに自分のタスク id と関連付けて保存し、以降のリトライでは再送信せず、保存済みの taskId をポーリングしてください。

実際に目にするエラー。

• 401 と "code": "permission_denied"——キーが無効か、そのモデルを使用できません。メッセージは明確に述べます：「This API key cannot use the selected model. Please check permissions or use another key.」 コンソールで修正してください。リトライしてはいけません。
• 400 と "error_code": "INVALID_REQUEST"——検証失敗です。message は具体的なフィールドと有効な値を示します。それを読んでリクエストボディを修正してください。同じボディでリトライしても永遠に失敗します。
• GET /v1/tasks/{id} での 404 "task not found"——タスク id が誤っているか、タスクが別のキーで作成されています。
• 受け付けられたタスクの fail ステータス——ポーリングレスポンスの data.error.code / data.error.message を確認してください。これらは新しいタスクとして安全にリトライできます。

関連記事

• ideogram-v4 モデルページ——機能と現在の料金ティア
• hiapi のタスクコールバックが発火しない理由——コールバックのデバッグチェックリスト
• 1 つの API キーで複数の画像モデルを呼び出す方法——同じタスク API、異なる model 文字列
• 最も安価な画像生成 API——各モデルの実際の 1 枚あたりコストを比較する方法
• API ドキュメント——完全な POST /v1/tasks / GET /v1/tasks/{id} リファレンス

よくある質問

hiapi 上の ideogram-v4 は画像から画像への生成や参照画像をサポートしていますか？ いいえ。このモデルのタスク schema は prompt、rendering_speed、aspect_ratio、seed のみを受け付け、画像入力フィールドはすべて 400 で拒否されます。既存の画像を編集または再描画する必要がある場合は、画像から画像への生成をサポートするモデル（例えば gpt-image-2 シリーズ）を使用してください。

どの rendering_speed を使うべきですか？ プロンプトとテキストの正確な文言を最適化する際は TURBO で反復し、その後、勝ち残ったバージョンを同じ seed と QUALITY で再レンダリングしてください。一度しかレンダリングしないなら、BALANCED が良いデフォルトです。

ideogram-v4 で正確な文字をレンダリングするにはどうすればよいですか？ リテラルなテキストを二重引用符でプロンプトに入れ、その周囲でタイポグラフィを描写します：メイン見出しテキスト "SUMMER SALE"、極太のコンデンスドサンセリフ体。短い文字列のほうが完全な文よりも信頼性高くレンダリングされます。長い行が崩れてレンダリングされる場合は、メイン見出しとサブ見出しに分割してください。

1 つのリクエストで複数の画像を生成できますか？ いいえ——1 タスクにつき 1 枚の画像です。代わりに複数のタスクを並列に送信してください。各タスクは独自の taskId を持ち、独立してキューに入ります。

キーが他のモデルでは有効なのに、401 permission_denied になるのはなぜですか？ モデルへのアクセス権はキーごとに設定されます。コンソールでそのキーのモデル権限を確認するか、ideogram-v4 へのアクセス権を持つ新しいキーを作成してください。

出力 URL の有効期間はどのくらいですか？ expireAt タイムスタンプ付きの署名付き URL です。日単位ではなく分単位と考えてください：タスクが success に達したらすぐに画像をダウンロードし、ファイルを自分で保存してください。

利用可能なアスペクト比は何ですか？ ちょうど 5 種類です：1:1、16:9、4:3、9:16、3:4。自由形式の size パラメータはありません——size を含むリクエストは未知のプロパティとして拒否されます。