Ideogram 4.5 APIの使い方？生成、編集、タスク照会

TL;DR

• Ideogram 4.5 は文字レイアウト優先のテキストtoイメージシリーズです。ideogram-v4.5/text-to-image はポスター、ロゴのレターマーク、バイリンガルパッケージなど文字入りの画像を生成し、ideogram-v4.5/image-to-image は Precise Edit で正確に文字を変更し、参照画像でスタイルを変え、マスクで部分を変更します。モデルページからタスクを選択することも、以下のとおりAPIを呼び出すこともできます。
• 価格は枚数単位で、品質ティアによって変わります：LOW $0.043、MEDIUM（デフォルト）$0.086、HIGH $0.3145。編集ティアは VERY_LOW $0.0115 から。現在は1リクエストにつき1枚を出力し、num_images は 1 のみです。詳細は価格ページをご覧ください。
• 呼び出しは HiAPI の /v1/tasks インターフェースを使用します。送信後に data.taskId を読み取り、次に data.status を照会します。成功後は data.output から type=image のURLを取得してダウンロードします。

できること

• 画面内の文字階層を整理：表示したい文字を引用符で囲み、タイトル、サブタイトル、日付、出演者の位置をそれぞれ指定します。出力後に一字ずつ確認します。
• 単枚タスクで構図を探索：1リクエストにつき1枚を出力します。プロンプトや seed を調整し、複数のタスクを個別に送信して方向性を比較します。
• 編集インターフェースとの併用：Precise Edit（edit_precision=high）はブランド名や日付など小範囲の修正に使えます。元画像と照らし合わせて保持領域を確認します。
• 参照画像 + マスク：参照画像は最大4枚（マスクありの場合は3枚）。マスクの黒 = 再描画、白 = 保持。

以下は生成された実際の成果物（LOWティア）：

Minimal modern brand poster for a design conference. Huge bold headline text "DESIGN FORWARD" centered, smaller subtitle "Typography Summit 2026" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering

（意味：ミニマルでモダンなデザインカンファレンスのブランドポスター。中央に超大サイズの太字見出し "DESIGN FORWARD"、その下に小さめのサブタイトル "Typography Summit 2026"、スイスグリッドのレイアウト、ウォームオレンジとディープネイビーの配色、幾何学図形、文字はくっきりと鮮明。サイズは landscape_16_9 を選択。）

ideogram-v4.5/text-to-image、LOW、landscape_16_9、1280×720、$0.043。

このプロンプトで生成 →

2つのインターフェースの選び方

	ideogram-v4.5/text-to-image	ideogram-v4.5/image-to-image
用途	テキストからレイアウト入りの画像を生成	既存画像を編集
必須入力	prompt	image_url + prompt
品質ティア	low / medium / high	very_low / low / medium / high
特徴的なパラメータ	num_images: 1、enable_prompt_expansion	edit_precision（Precise）、reference_image_urls、mask_url
サイズ	6種類のプリセット、デフォルト square_hd	auto（デフォルト）または6種類。マスク / Precise 時は auto のみ
適した用途	ポスター、ロゴ、パッケージ、看板の新規案	文字変更、配色変更、季節バージョン、部分的な再描画

典型的なワークフロー：ブランドポスターを生成し、次に Edit でブランド名や日付をクライアントのバージョンに変更します。生成 LOW 1枚 $0.043 に Precise LOW の文字変更1回 $0.043 を加えて、一式 $0.086 です。

2つの開始ルート

ブラウザで3ステップ：モデルページを開く → プロンプトを貼り付け、品質ティアを選択 → 生成をクリック。

APIで3ステップ：POST /v1/tasks で送信 → data.taskId を読み取る → GET /v1/tasks/<taskId> で data.status を照会し、success になったらダウンロード。

curl：最初の1枚

まずターミナルで HIAPI_IDEMPOTENCY_KEY を今回の業務の一意な識別子として設定し、同じリクエストを再試行する際はその値を使い続けます。例では LOW、横長サイズ、拡張を明示的に有効にしています。

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/text-to-image",
  "input": {
    "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
    "quality": "low",
    "image_size": "landscape_16_9",
    "enable_prompt_expansion": true,
    "num_images": 1
  }
}'

編集インターフェース：model を ideogram-v4.5/image-to-image に変更し、元画像と指示を渡します。以下では Precise Edit で文字変更とレイアウト保持を要求していますが、成果物は元画像と照らし合わせて確認する必要があります：

この編集タスクには別途 HIAPI_EDIT_IDEMPOTENCY_KEY を設定し、生成タスクのキーを再利用しないでください。

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_EDIT_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "Change the logo text from \"Ember & Oak\" to \"Maple & Co\", keep the same serif lettering style, emblem, tagline, colors and layout exactly unchanged",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/88567ad2baf46b32.png",
    "edit_precision": "high",
    "quality": "low",
    "image_size": "auto",
    "num_images": 1
  }
}'

Python：送信、ポーリング、ダウンロード

まず requests をインストールし、HIAPI_API_KEY を設定します。初回送信時には HIAPI_IDEMPOTENCY_KEY も設定する必要があり、新しい業務ごとに独立した値を使用し、同じ送信の再試行では変更しません。プログラムは最初にタスクIDを出力します。中断後に HIAPI_TASK_ID を設定すると、再送信せずに照会とダウンロードを続行できます。

import os
import time
from pathlib import Path

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
headers = {"Authorization": "Bearer " + os.environ["HIAPI_API_KEY"]}
payload = {
    "model": "ideogram-v4.5/text-to-image",
    "input": {
        "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
        "quality": "low",
        "image_size": "landscape_16_9",
        "enable_prompt_expansion": True,
        "num_images": 1,
    },
}
# Set HIAPI_TASK_ID to resume polling without creating another task.
task_id = os.environ.get("HIAPI_TASK_ID")
if not task_id:
    # Use one unique key per business operation; keep it for retries.
    submission_key = os.environ["HIAPI_IDEMPOTENCY_KEY"]
    response = requests.post(
        BASE, headers={**headers, "Idempotency-Key": submission_key},
        json=payload, timeout=30,
    )
    response.raise_for_status()
    created = response.json()
    if created.get("code") != 200:
        raise RuntimeError(created)
    task_id = created["data"]["taskId"]
print("Keep this task ID:", task_id, flush=True)

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{BASE}/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    result = response.json()
    if result.get("code") != 200:
        raise RuntimeError(result)
    task = result["data"]
    if task["status"] in ("fail", "failed"):
        raise RuntimeError(task.get("error", task))
    if task["status"] == "success":
        image_url = next(
            (item["url"] for item in task.get("output", [])
             if item.get("type") == "image" and item.get("url")), None,
        )
        if not image_url:
            raise RuntimeError("Successful task has no image URL")
        # Do not forward API authorization to the media download host.
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        media_type = image.headers.get("Content-Type", "").split(";", 1)[0].lower()
        suffix = {"image/png": ".png", "image/jpeg": ".jpg",
                  "image/webp": ".webp"}.get(media_type)
        if not suffix:
            raise RuntimeError("Unexpected image content type: " + media_type)
        target = Path(task_id + suffix)
        partial = target.with_suffix(suffix + ".part")
        partial.write_bytes(image.content)
        partial.replace(target)
        print("Saved:", target)
        break
    time.sleep(3)
else:
    raise TimeoutError(f"Polling timed out; keep checking task {task_id}")

照会やダウンロードでネットワークエラーが発生した場合は、出力済みのタスクIDを保持してから再開してください。スクリプトは作成リクエストを自動で再送しません。例のポーリング上限は600秒、待機は3秒ごとで、ダウンロードはまず .part ファイルに書き込み、完了後に正式なファイル名に変更します。

パラメータ表

生成 ideogram-v4.5/text-to-image

フィールド	必須	値	説明
prompt	はい	1–10000 文字	4段構成：何の画像か → 文字と配色 → レイアウト → 質感と制約
quality	いいえ	low / medium / high、デフォルト medium	一括探索は low、日常は medium、小さい文字が多い最終稿は high
image_size	いいえ	6種類のプリセット、デフォルト square_hd	カスタム幅・高さなし
num_images	いいえ	固定で 1	1タスクにつき1枚を出力
enable_prompt_expansion	いいえ	デフォルト true	プロンプト拡張。false で拡張をオフにしても、成果物の文字確認は必要
seed	いいえ	整数	同じパラメータで再現

編集 ideogram-v4.5/image-to-image

フィールド	必須	値	説明
image_url	はい	画像URL	元画像
prompt	はい	1–10000 文字	編集指示。何を変更し、何を保持するかを明記
edit_precision	いいえ	regular / high、デフォルト regular	high = Precise Edit、小範囲の文字変更に適する
quality	いいえ	very_low / low / medium / high、デフォルト medium	very_low は regular とのみ組み合わせ可能
image_size	いいえ	auto または6種類のプリセット、デフォルト auto	マスクまたは Precise 時は auto のみ
reference_image_urls	いいえ	最大4枚	マスクありの場合は最大3枚
mask_url	いいえ	画像URL	黒 = 再描画、白 = 保持
num_images	いいえ	固定で 1	1タスクにつき1枚を出力
seed	いいえ	整数

input 内にこのモデルのパラメータ表以外のフィールドがあると 400 が返ります。トップレベルの model、callback などはタスクインターフェースの形式に従って記入してください。

遭遇するエラー

ステータスコード	意味	対処方法
400 INVALID_REQUEST	リクエストボディが不正（prompt または image_url の欠落、列挙値の誤り、表外フィールドの指定）	パラメータ表と照らし合わせてリクエストボディを修正
402 INSUFFICIENT_QUOTA	残高不足（課金なし）	チャージ後に再試行
429 RATE_LIMITED	レート制限に到達	送信頻度を下げる
409 IDEMPOTENCY_KEY_PROCESSING	同じキーのタスクが作成中	待機後、同じキーと同じリクエストボディで再試行
422 IDEMPOTENCY_KEY_MISMATCH	同じキーに異なるリクエストボディが設定された	元のリクエストボディに戻す。新しい業務タスクのみ新しいキーに変更

タスクの終端状態の失敗には CONTENT_POLICY_VIOLATION、TASK_FAILED、TASK_TIMEOUT などのエラーコードが含まれる場合があります。taskId とエラーメッセージを保持し、タスクの最終状態とアカウント記録を照らし合わせて精算を確認してください。照会失敗やダウンロード失敗を生成失敗とみなさないでください。

公開前の注意

• コールバック：リクエストボディのトップレベルに "callback": {"url": "https://..."} を渡すと、終端状態を自動通知します。
• 速やかな保存：data.output 内の結果リンクには有効期限があるため、成功後すぐにダウンロードしてください。
• 単枚タスクと冪等性：毎回1枚を出力。同じ業務リクエストがタイムアウトで再試行される場合は元の冪等キーを使い続け、新しい業務タスクのみ新しいキーを使用します。
• 中国語の小さい文字：実際の文案に合わせて品質ティアを比較し、納品前に一字ずつ校正してください。medium や high でも確認の代わりにはなりません。

よくある質問

1回のリクエストで最大何枚生成できますか？

現在、生成と編集はいずれも毎回1枚を出力し、num_images は 1 のみです。複数の方向性はそれぞれタスクを送信してください。

デフォルトの品質ティアは LOW ですか？

いいえ。デフォルトは MEDIUM で、1枚 $0.086 です。LOW の1枚 $0.043 が必要な場合は quality: "low" を明示的に渡してください。

ブランド名と日付だけを変更するにはどのモードを使いますか？

Precise Edit を選択し、edit_precision: "high"、quality: "low"、image_size: "auto" を明示的に渡します。1枚 $0.043 です。

マスクの黒と白の領域はそれぞれ何を意味しますか？

黒い領域は再描画、白い領域は保持です。マスクは元画像と同じサイズにし、マスク使用時は image_size に auto を選択してください。

送信がタイムアウトしたら冪等キーを変更すべきですか？

同じ業務リクエストの再試行ではキーを変更せず、同じ Idempotency-Key と同じリクエストボディを使い続けてください。本当に新しいタスクが必要な場合にのみ新しいキーを使用します。

次のステップ：DESIGN FORWARD ポスターのプロンプトを使ってモデルページで1枚生成し、その後 Precise の一文指示でタイトルを自分のイベント名に置き換えてみてください。 関連記事：3段階の価格と予算 · 4つの編集プロンプト事例。

すぐにレターマークやイベントポスターを作り始めたい場合は、このプロンプト事例集をコピーしてください。