Ideogram 3.0 Character API の使い方？5 分で最初のキャラクター画像を生成

TL;DR

• Ideogram 3.0 Character は参照画像によるキャラクター生成モデルです。キャラクターの参照画像を 1 枚アップロードし、シーンのプロンプトを書くだけで、同じ顔と服装のキャラクターが新しいシーンに現れます。モデルページを開くとオンラインで試せます。新規ユーザー登録で 200 クレジット進呈。
• 料金は枚数単位：TURBO $0.09、BALANCED $0.13、QUALITY $0.18。参照画像は無料、失敗時は課金されません（詳細は料金ページ）。
• 呼び出しは HiAPI の /v1/tasks エンドポイント経由：タスクを送信して taskId を取得し、それで結果を問い合わせます。成功後 output[0].url から画像をダウンロードします。

できること

• キャラクター一貫性生成：1 枚の参照画像でキャラクターを固定し、顔立ちと服装を保ちながらシーンを自由に変えられます。
• イラストも写実も対応：style は AUTO / REALISTIC / FICTION を選択可能。写真風人物もイラストキャラクターも扱えます。
• 画幅は参照画像に追従：縦版の参照なら 3:4（864×1152）、横版の参照なら 16:9（1328×752）。サイズパラメータの入力は不要です。
• 編集エンドポイントも完備：ideogram-v3-character/edit はマスクを使ってキャラクターを既存画像の指定領域に描き込み、それ以外の部分は変えません。

以下は実際の生成例です（参照画像は横版のイラストキャラクター）：

The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs

（日本語の意味：この探検家キャラクターが提灯を掲げた夜市を歩き、紙カップの熱い麺を手に持っている。両側には暖かな光の屋台。絵本イラスト風、文字なし、看板なし。）

ideogram-v3-character、TURBO、16:9、1328×752、$0.09。

このプロンプトで生成 →

2 つのエンドポイントの選び方

	ideogram-v3-character	ideogram-v3-character/edit
用途	ゼロからキャラクターの新シーンを生成	キャラクターを既存画像のマスク領域に描き込む
必須入力	prompt + 参照画像 1 枚	prompt + 元画像 + マスク + 参照画像 1 枚
料金（TURBO / BALANCED / QUALITY）	$0.09 / $0.13 / $0.18	$0.09 / $0.13 / $0.18
出力	WebP、画幅は参照画像に追従	WebP、サイズは元画像に追従
向いている用途	ポスター、連載、シリーズのシーン画像	完成画像上でのキャラクター差し替え・追加

マスクの規約：黒 = 再描画、白 = 保持。マスクと元画像のアスペクト比は必ず一致させてください。編集エンドポイントは negative_prompt を受け付けず、渡すと 400 エラーになります。

2 つの始め方

ブラウザで 3 ステップ：モデルページを開く → キャラクター参照画像をアップロードし、プロンプトを貼り付け → 生成をクリック。TURBO で 1 枚 $0.09。

API で 3 ステップ：POST /v1/tasks で送信 → taskId を取得 → GET /v1/tasks/<taskId> で success を確認してダウンロード。

curl：最初の 1 枚

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "ideogram-v3-character",
  "input": {
    "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

編集エンドポイントでは model を ideogram-v3-character/edit に変え、input に image_url（元画像）と mask_url（マスク）を追加します：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character/edit",
  "input": {
    "prompt": "The explorer character curled up in the armchair asleep under a knitted blanket",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/8e1328c02f8edd33.jpg",
    "mask_url": "https://static.hiapi.ai/gallery/2026/10/0121b5b1d8af8697.png",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

レスポンスの taskId が問い合わせ用のキーになります。

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

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "ideogram-v3-character",
    "input": {
        "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
        "reference_image_urls": ["https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"],
        "rendering_speed": "TURBO",
    },
}

# 送信：Idempotency-Key 付きなら、ネットワークリトライでもタスクが重複作成されない
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# ポーリング：queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # 一時 URL。できるだけ早くダウンロードして保存
    img = requests.get(image_url, timeout=60)
    with open("output.webp", "wb") as f:
        f.write(img.content)
    print("saved output.webp")

パラメータ表（ideogram-v3-character）

フィールド	必須	値	説明
prompt	はい	1〜5000 文字	キャラクターが現れるシーンを記述する。キャラクターの見た目は書かない（見た目は参照画像に依存）
reference_image_urls	はい	ちょうど 1 枚、JPEG / PNG / WebP、≤10 MB	キャラクター参照画像。画幅が出力画幅を決める
rendering_speed	いいえ	TURBO / BALANCED / QUALITY、デフォルト BALANCED	グレードと料金を決定
style	いいえ	AUTO / REALISTIC / FICTION、デフォルト AUTO	REALISTIC は写真風の質感、FICTION はイラスト感を維持
seed	いいえ	整数 0〜2147483647	同じパラメータと同じ seed で画面を再現
expand_prompt	いいえ	デフォルト true	プロンプトを自動拡張。原文を厳密に反映したい場合は false を渡す
negative_prompt	いいえ	≤5000 文字	出現させたくない内容

編集エンドポイントは表外に必須項目 image_url、mask_url が 2 つ追加され、negative_prompt はサポートしません。リクエストボディに表外のフィールドがあると即 400 になります（additional properties ... not allowed）。

遭遇するエラー（API 原文）

行った操作	返却
prompt を渡していない	400 invalid input: prompt: missing required field "prompt"
参照画像を 2 枚渡した	400 invalid input: reference_image_urls: maxItems: got 2, want 1
rendering_speed を打ち間違えた	400 invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'
API が認識しないフィールドを渡した	400 invalid input: <root>: additional properties 'foo' not allowed
編集エンドポイントに negative_prompt を渡した	400 invalid input: <root>: additional properties 'negative_prompt' not allowed
残高不足	402 insufficient account balance; top up and retry

同じ Idempotency-Key で再送信すると 409（処理中）または 422（パラメータ不一致）が返ります。新しい key に変えて再試行してください。

本番前の注意点

• コールバック：リクエストボディのトップレベルに "callback": {"url": "https://..."} を渡すと、タスクが終態になった際にサービスへ通知され、ポーリングを省略できます。
• 速やかに転送保存：output[0].url は一時 URL です。取得したらすぐにダウンロードして自分のストレージに保存し、永続リンクとして使わないでください。
• グレードと画幅を明示する：rendering_speed は毎回明示的に渡す（渡さないと BALANCED で課金）。出力画幅は参照画像で決まるため、縦版のシーンなら縦版の参照画像を用意してください。
• バッチタスクはそれぞれ別の冪等キーを使う：各送信に一意の Idempotency-Key を付けます。ネットワークリトライで同じ key を使うと同一タスクにヒットするだけで、タスクの重複作成やクレジットの二重消費は発生しません。

よくある質問

参照画像は URL でもいいですか？

可能です。アクセス可能な http/https アドレスであれば、JPEG、PNG、WebP のいずれも使え、最大 10 MB です。

参照画像は何枚まで渡せますか？

ちょうど 1 枚というのが厳格なルールで、2 枚渡すと即 400 エラーになります。キャラクターを変えたい場合は参照画像を差し替えてください。

サイズパラメータは必要ですか？

不要です。出力画幅は参照画像に追従し、縦版の参照なら 864×1152、横版の参照なら 1328×752 になります。

2 つのエンドポイントの呼び出し方法は同じですか？

同じです。model と input 内のフィールドを変えるだけです。

失敗すると課金されますか？

されません。事前に引き落とされたクレジットは失敗の終態後に全額返還されます。

次のステップ：上記の夜市プロンプトを使ってモデルページで 1 枚試してから、シーン別のプロンプトをプロンプト大全で確認しましょう。3 段階の料金と予算表は料金ページをご覧ください。