Ideogram

Ideogram V3 Character

ideogram-v3-character/edit

参照画像で同一キャラクターを固定し、シーン・ポーズ・照明の変更をまたいで顔と衣装の一貫性を保ち、さらに Ideogram の画像内テキスト組版の強みを継続する

ideogram-v3-character ideogram-v3-character/edit

ideogram-v3-character/edit を試す

入力

作品ギャラリー

すべての作品を見る

出力

image

パラメータを入力して生成すると、結果がここに表示されます。

料金

ideogram-v3-character/edit per image

仕様	単価
TURBO	$0.090
BALANCED	$0.130
QUALITY	$0.180

位置づけの概要

ideogram-v3-character/edit はキャラクター一貫性を重視した編集向けの画像モデルです。ソース画像とマスクを1枚ずつアップロードし、再描画する領域を指定したうえで、ちょうど1枚のキャラクター参照画像を視覚的アンカーとして与えることで、顔・髪型・服装・体型を保ったまま局所的な画面を書き換えられます。同一の人物、マスコット、アバターをシリーズ素材で繰り返し使いたい開発者、とりわけキャラクターの見た目を統一しつつ、シーンやコピーを可変にしたバッチ制作を行いたい場面に適しています。

主な特長

キャラクターを固定した局所再描画——ソース画像とマスクで編集領域を定義し、参照画像でキャラクターの同一性を固定するため、シーンは変えても顔は変わりません。
シーンは可変、見た目は不変——プロンプトでポーズ・照明・背景を置き換えつつ、人物の核となる特徴は参照画像によって制約されます。
再現可能なバッチ制作——固定ランダムシードに対応し、スタイルとレンダリング速度の段階と組み合わせることで、シリーズ素材を安定して再現できます。

機能説明

マスクによる領域指定編集：ソース画像と同じアスペクト比のマスクを渡すと、マスクが覆う領域だけが再描画され、それ以外の画面は変わりません。背景や局所的な要素の差し替えに適しています。

単一参照画像によるキャラクター固定：参照画像は1枚のみ（JPEG、PNG、WebP、最大10MB）で、これに基づいて再描画結果におけるキャラクターの外見的特徴を制約します。

プロンプトで制御できるシーン：最大5000文字のプロンプトで目標のシーンを記述でき、プロンプト拡張を有効にすると記述の詳細を自動補完します。

スタイルと速度の段階：スタイルは AUTO、REALISTIC、FICTION から選択でき、レンダリング速度は TURBO、BALANCED、QUALITY に分かれ、段階ごとに細部の程度が異なります。

適した用途

シリーズキャラクター素材のバッチ反復——運用チームやデザインチームが同一の参照画像に異なるマスクを組み合わせ、同一キャラクターの多シーン配図をバッチで生成し、SNSやイベントページに利用します。
ポスターや宣伝画像の局所的な背景差し替え——キャラクターの主体を保ったまま背景とライティングを差し替え、そのまま配信できる宣伝画像や文字レイアウト付きの素材を得ます。
漫画や絵コンテにおけるキャラクターの一貫性——作者が設定参考画像を用いて絵コンテ内のポーズとシーンを再描画し、一貫した見た目の連続画面をストーリーボード用に生成します。

制限と選定の指針

キャラクターの一貫性は絶対ではなく、複雑なシーンや極端なポーズ・表情では目に見えるズレが生じることがあります。参照画像は顔が鮮明で、照明が良く、遮蔽が少ない必要があり、そうでなければ効果は低下します。マスクとソース画像は同じアスペクト比でなければならず、参照画像は1枚のみ受け付けます。単体の独立したクリエイティブ生成が目的で、同一キャラクターを固定する必要がない場合は、テキストから画像を生成する経路のほうが適しています。QUALITY 以上の細部段階では生成時間が長くなるため、速度と品質の間で取捨選択が必要です。

よくある質問

よくある質問を見る →

マスクにはどのような要件がありますか？

マスクは元画像と同じアスペクト比である必要があり、黒い領域は再描画され、白い部分は保持されます。領域がキャラクターの輪郭より少し大きい方が自然です。
出力サイズはどれくらいですか？

出力は元画像のサイズに従います。たとえば 1024×768 の元画像なら 1024×768 の結果が得られます。
元の画像にすでに人物がいる場合、置き換えられますか？

はい、置き換えたい人物をマスクに塗り込み、プロンプトで新しいキャラクターの動作を記述してください。マスク外の人物と背景は保持されます。
マスクはどのフォーマットを使いますか？

元画像と同じ縦横比の画像を使い、白い背景の上に黒で再描画したい領域を塗りつぶします。本ページの事例では PNG マスクを使用しています。

生成タスクの作成

POST https://api.hiapi.ai/v1/tasks

ヘッダー

Authorizationstring必須

アカウントの API キー。すべてのリクエストで必須です。例：Bearer YOUR_HIAPI_API_KEY。API キーを取得

Content-Typestring任意

リクエストボディは常に JSON として解析されます。送信する場合は application/json（charset 付き可）のみ受け付け、他の値は 415 を返します。例：application/json。

Idempotency-Keystring任意

冪等キー。最大 255 バイト。同じアカウントで同じキーの再試行はタスクを 1 つだけ作成し、リプレイは最初の taskId を返します。

冪等キー

ネットワークタイムアウトやクライアントの自動再試行時、同じキーではタスクを 1 回だけ作成し、二重課金は発生しません（適用範囲 = API キーのアカウント）。業務側の一意識別子（例："order-42"）をキーに使うことを推奨します。同じキーのリプレイは最初の taskId を返し、キーは初回送信から 24 時間で失効します。詳細なシナリオ表は統一非同期 API の紹介ページをご覧ください。

ボディ

modelstring必須

現在の固定値：ideogram-v3-character/edit

routestring任意

現在の固定値：default

inputobject必須

ideogram-v3-character/edit とルート default の業務パラメータオブジェクト。下のパラメータ表を参照してください。

seedinteger任意min 0max 2147483647

整数型のランダムシード。同じプロンプトの生成結果を再現可能にするために使用します。値の形式は整数です。

stylestring任意デフォルト: "AUTO"

生成に使用するスタイルタイプを指定します。デフォルトは AUTO です。

オプション：AUTOREALISTICFICTION

promptstring必須minLength 1maxLength 5000

参照キャラクターが置かれるシーン、つまり今回の編集で生成する画面内容を記述します。最大 5000 文字です。

mask_urlstring必須minLength 1pattern ^https?://

再描画が必要な領域を指定するマスク画像の URL。マスクは元画像と同じアスペクト比である必要があります。

image_urlstring必須minLength 1pattern ^https?://

編集対象の元画像 URL。この画像はマスクと同じアスペクト比である必要があります。

expand_promptboolean任意デフォルト: true

MagicPrompt によるプロンプトの自動拡張を使用するかどうかを制御するブール値のスイッチです。デフォルトは true です。

rendering_speedstring任意デフォルト: "BALANCED"

レンダリング速度のグレードを指定します。TURBO は最速かつ最も安価で、QUALITY はディテールが最も豊かです。グレードによって価格が異なります。デフォルトは BALANCED です。

オプション：TURBOBALANCEDQUALITY

reference_image_urlsarray必須minItems 1maxItems 1

キャラクター参照画像の配列。キャラクター参照画像はちょうど 1 枚必要で、JPEG、PNG、WebP 形式に対応し、1 枚あたり最大 10 MB です。

Array [ string ]

callbackobject任意

終了状態の通知設定。省略した場合はコールバックされず、呼び出し側でポーリングします。

コールバック（Webhook）

作成時に callback.url を指定すると、タスク終了時に HiAPI があなたのサービスへ POST し、ポーリングが不要になります。コールバックのリクエストボディはタスク詳細と同構造です。署名検証・再送・冪等の詳細は統一非同期 API 紹介ページのコールバック説明を参照してください。

urlstring必須

callback を指定する場合は必須。タスク終了後にこの URL へ POST します。有効な http(s) URL である必要があります。

whenstring任意デフォルト: "final"

現在は final のみ対応（success / fail の両方で通知）。

オプション：final

storagestring任意デフォルト: "temp"

成果物の保存期間：temp（デフォルト・約 7 日）または persistent（長期保存・サイズ課金）。残高不足や保存上限超過の場合は temp に自動降格します。実際に適用された段階はタスク詳細レスポンスで確認できます。

オプション：temppersistent

リクエスト例

# 非同期タスクを送信。成功すると即座に taskId を返します（生成完了は待ちません）
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character/edit",
  "input": {
    "style": "AUTO",
    "prompt": "…",
    "mask_url": "…",
    "image_url": "…",
    "expand_prompt": true,
    "rendering_speed": "BALANCED",
    "reference_image_urls": "…"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "ideogram-v3-character/edit",
    input: {
      "style": "AUTO",
      "prompt": "…",
      "mask_url": "…",
      "image_url": "…",
      "expand_prompt": true,
      "rendering_speed": "BALANCED",
      "reference_image_urls": "…"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "ideogram-v3-character/edit",
        "input": {
          "style": "AUTO",
          "prompt": "…",
          "mask_url": "…",
          "image_url": "…",
          "expand_prompt": True,
          "rendering_speed": "BALANCED",
          "reference_image_urls": "…"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

タスク詳細の取得

GET https://api.hiapi.ai/v1/tasks/:id

レスポンスフィールド

taskIdstring必須

タスク ID。先頭は固定で tk-hiapi-。

modelstring必須

解決済みのモデル完全名。route パラメータで送信したタスクは base@route（例：gpt-image-2/text-to-image@ext）を返し、それ以外は送信時のモデル名と同一です。

routestring任意

route パラメータを明示して送信したタスクでのみ出現し、送信時の値をエコーします。

statusstring必須

タスク状態。

ステータス値

queued キュー投入済み、未開始。 handling 処理中。 archiving 処理完了、成果物準備中。 success 終端：完了。成果物利用可能（output を返却）。 fail 終端：失敗（error を返却）。送信後は status で判断します：success と fail が終端、それ以外は非終端です。1〜3 秒間隔で終端までポーリングすることを推奨します。成功したら output[].url から成果物をダウンロードし、expireAt までに保存先へ転送してください。長期保存が必要な場合は作成時に storage: "persistent" を指定します。

creatednumber必須

タスク作成時刻（Unix 秒）。

completednumber必須

終了状態になった Unix 秒。非終端では 0 固定。

outputarray任意

status == success のときのみ出現。成果物リスト — 常に配列で、1 タスクで複数の type を同時に返すことがあります（例：video + first_frame）。

Array [ object ]

配列要素

urlstring必須

成果物の URL。直接ダウンロードできます。

typestring必須

現在の候補値：video、image、audio、first_frame、last_frame、thumbnail。今後拡張される可能性があります。

expireAtnumber必須

成果物にアクセスできる期限（Unix 秒）。期限までにダウンロードまたは転送してください。

errorobject任意

status == fail のときのみ出現。

codestring必須

業務エラーコード。

messagestring必須

エラーの説明。

レスポンス例

成功

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

処理中（非終端）

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

失敗

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}