HiAPI
ブログ

使用ガイド

Ideogram V3 Character Edit 接入ガイド:元画像・マスク・キャラクター参照画像の準備方法

3種類の画像入力がそれぞれの役割を担う:契約のフィールドに従って局部編集を送信し、キャラクターの一貫性と境界を項目ごとに自己確認する

Nov 18, 2026
ブログカバー画像:深い墨緑の背景に、2組の幅広で平たいストリップが織り合わさって技術的な織り格子を作り、真鍮色が縦に交差し、幾何学的で抑制が効いている。
このページの内容

3種類の画像入力がそれぞれ担う役割

ideogram-v3-character/edit に接続する前に、3つの画像フィールドの責務を分けておけば、以降のすべての準備作業が明確になります。

  • 元画像 image_url:「どの画面を変更するか」を決めます。元の構図、背景、被写体の位置を提供し、編集操作全体の土台となります。
  • マスク mask_url:「どこを変更するか」を決めます。再描画が必要な領域だけを囲み、その外側の内容は保持されるべきです。
  • キャラクター参照画像 reference_image_urls:「キャラクターがどんな見た目か」を決めます。キャラクターの外見的特徴を提供し、再描画結果を参照キャラクターに合わせます。

3者の境界を混同しないでください。元画像はキャラクター参照画像ではなく、キャラクター参照画像が元画像の代わりになることもありません。マスクは空間的な制約であり、内容の記述ではありません。キャラクターの特徴は参照画像に、画面内容は prompt に、変更範囲はマスクに任せるのが、最もミスの少ない切り分け方です。一度混用すると(たとえばキャラクター画像だけをアップロードしてマスクを開かない、あるいはマスクでキャラクターの外見を「暗示」しようとする)、問題を調査するときに判断の根拠を失います。

契約のレベルでは、元画像とマスクは文字列の URL フィールド、キャラクター参照画像は配列フィールドです。3者の型が異なることも用途の違いを示しています。前者2つは1対1の空間的なペアであり、後者は独立した人物記述のソースです。

3種類の入力は並列に積み重なるのではなく、元画像・マスク・キャラクター参照画像がそれぞれ出力フレームの異なる領域を担います。図では3本の合流線でその分担を表しています。

元画像とマスクの準備の要点

image_url と mask_url はどちらも必須フィールドで、形式は URI、http:// または https:// で始まる必要があります(契約の pattern は ^https?://)。最小長は 1 です。

アスペクト比は必ず一致させる

契約が両者に課す唯一の厳格な幾何学的制約は、マスクは元画像と同じアスペクト比を保たなければならないことです。これは推奨ではなく前提条件であり、素材を準備する際に最も確実な方法は、まずローカルでマスクを元画像のサイズに合わせて出力し、それから一緒にアップロードすることです。サーバー側が合わせてくれることを期待してはいけません。

マスクの意味:再描画領域だけを囲む

マスクが示すのは「再描画を許可する」位置です。したがって:

  • 保持したい部分はマスク領域に入れないでください。
  • 変更したい被写体(衣装替え、ポーズ変更など)はマスク内に完全に収め、端が切れないようにしてください。
  • マスクを細切れにしすぎないでください。散在する小片はモデルが編集意図を理解するのを難しくします。

URL の可用性

両フィールドはリモート URL なので、送信前にリンクが匿名でアクセスでき、リダイレクト切れがなく、ログインが必要な認証がないことを必ず確認してください。マスクには透明チャンネルを持つ画像か、白黒のコントラストがはっきりした画像を使い、半透明のグラデーションによる境界の曖昧さを避けることをお勧めします。

キャラクター参照画像の仕様と制限

reference_image_urls は必須の配列フィールドで、契約には明確な制約があります:minItems: 1、maxItems: 1、つまりちょうど1枚のみです。2枚渡しても0枚渡しても不正な入力と判定されます。これは多くの「複数画像参照」の直感に反するため、接続時に陥りやすい落とし穴です。

形式とサイズ

  • 対応形式:JPEG、PNG、WebP
  • 1枚あたり最大 10 MB

画像選びの推奨

キャラクター参照画像の役割は安定した人物特徴を提供することなので:

  1. 鮮明で、正面または正面に近く、顔が隠れていない画像を選んでください。
  2. 強い逆光、強いフィルター、複数人の集合写真(モデルが誰に合わせるべきか判断できない)は避けてください。
  3. 全身と半身にはそれぞれ取舍があります。服装の細部が必要なら半身以上、全体のスタイルが必要なら全身を使ってください。
  4. すでに複雑な背景が入った画像でシーンを「暗示」しないでください。シーンは prompt の記述に任せてください。

配列形式は要素を1つしか入れられませんが、書き方としては配列として送信する必要があります。たとえば単一の URL を1項目として包み、文字列をそのまま置かないでください。

必須フィールドと任意フィールドの組み合わせ方

必須項目は全部で4つです:prompt、image_url、mask_url、reference_image_urls。任意の調整項目には expand_prompt、style、seed、rendering_speed があります。

prompt に書くのは新しいシーンであり、編集命令ではない

契約における prompt の定義は非常に重要です:「参照キャラクターが置かれたシーン、つまり今回の編集で生成する画面内容を記述する」、長さは 1〜5000 文字です。つまり、「彼女の服を赤いコートに変える」といった操作命令を書くのではなく、「彼女は雨上がりの街路に立ち、赤いコートを着ており、ネオンが濡れた地面に反射している」といった画面記述を書きます。編集範囲はマスクが担当し、prompt は画面内容そのものを担当します。

expand_prompt はデフォルトで有効

expand_prompt はブール値のスイッチで、デフォルトは true です。有効にすると MagicPrompt でプロンプトが自動的に拡張されます。これは、送信した短い記述がモデルによってもう一度加工されることを意味します。調査段階ではまずデフォルトのままにし、長い記述と拡張結果の違いを確認してから無効にするかどうかを決めることをお勧めします。

style と seed

  • style の列挙値は AUTO、REALISTIC、FICTION で、デフォルトは AUTO です。写実的な人物が必要なら REALISTIC、スタイライズされたイラストなら FICTION、不明なら AUTO のままにしてください。
  • seed は整数で、範囲は 0 から 2147483647 です。同じプロンプトの生成結果を再現するために使います。「同じ入力で異なるパラメータ」を比較したいとき、seed を固定すればランダム性の干渉を排除できます。

rendering_speed の段階選択

rendering_speed は文字列の列挙値で、デフォルトは BALANCED、全部で3段階です:

  • TURBO:画像生成が最速で、草稿段階でマスク範囲やキャラクターが合っているかを素早く検証するのに適しています。
  • BALANCED:デフォルト段階で、速度と細部の折衷であり、日常的な接続の出発点です。
  • QUALITY:細部が最も豊かで、最終出力前の確定ラウンドに適しています。

選び方の考え方は、一度で決め打ちするのではなく段階ごとに切り替えることです。まず TURBO で幾何とキャラクターの方向に問題がないことを確認し、それから BALANCED または QUALITY で細部を収束させます。こうすれば何度もデバッグするときに、高品質レンダリングに時間を浪費しません。

強調しておきたいのは、3段階には課金基準の違いがあることです(画像生成の段階に応じた課金)。具体的な価格はサイトの価格パネルを基準とし、本記事では数字を展開しません。画像入力の問題を調査するときは、まずデフォルト段階に固定しておけば変数を1つ減らせます。

3段階は同じ織り方の疎密変化のようなものです。上にあるほど織りが密で、細部が多く、速度が遅くなります。

送信前の自己チェックリスト

契約に沿って項目ごとに確認すれば、大部分の失敗を送信前に食い止められます:

  • prompt が空でなく、5000 文字を超えておらず、内容が編集命令ではなくシーン記述である。
  • image_url が http:// または https:// で始まる匿名アクセス可能なリンクである。
  • mask_url も同様にアクセスでき、元画像とアスペクト比が一致している。
  • reference_image_urls が配列で、長さがちょうど 1 である。
  • その参照画像の形式が JPEG/PNG/WebP で、サイズが 10 MB を超えていない。
  • 任意フィールドの綴りと列挙値が正しい(style、rendering_speed は契約に列挙された大文字の値を使う)。
  • seed を設定した場合、0〜2147483647 の整数であることを確認する。
  • expand_prompt を無効にした場合、prompt 自体が十分に完全であることを確認する。

このチェックリストはトラブルシューティングの最初の拠点でもあります。どれか1つでも満たさない場合、記述を何度も調整するのではなく、まず入力を修正してください。

キャラクターのずれと境界問題の調査アプローチ

生成結果が期待に沿わないときは、まず問題を分類し、それから的を絞って調整するほうが、画像全体を再送信するより効果的です。

タイプ1:キャラクターが似ていない

顔の特徴、髪型、体型が参照画像から外れる形で現れます。調整の方向:

  • 参照画像を交換する:より鮮明な正面画像、より良い照明、単一の被写体。
  • 参照画像が切り取られたり過度に圧縮されたりしていないか確認する。
  • prompt にキャラクターの記述(服装、体型、年齢の雰囲気)を補い、文字と画像を互いに裏付けさせる。
  • シーンの複雑さを下げ、背景要素がキャラクターの細部を奪わないようにする。

タイプ2:境界がぼやける

マスク外の内容が意図せず変更されたり、マスクの縁に継ぎ目やゴーストが現れたりする形で現れます。調整の方向:

  • まず元画像とマスクのアスペクト比が厳密に一致していることを確認する。
  • マスクが保持すべき部分まで囲み込んでいないか確認する。
  • 被写体がマスク内に完全に収まり、端が切れないようにする。
  • よりくっきりしたマスクの縁に替え、半透明の遷移を減らす。

2種類の問題を混ぜて調整しないでください。キャラクターの問題は参照画像と記述を変え、境界の問題はマスクと幾何を変えます。一度に1つの変数だけを動かすことで、どれが効いたのかを判断できます。

サンプルから接続へ

上記の契約要件をフローに落とすと、4つのステップになります。同じアスペクト比の元画像とマスクを準備し、規格に合ったキャラクター参照画像を1枚選び、シーン化した prompt で新しい画面を記述し、チェックリストに沿ってフィールドを確認してから送信します。

接続の入口はモデルページにあり、フィールド定義と列挙値はページを基準とします。本記事のチェックリストと項目ごとに照合できます:Ideogram V3 Character Edit モデルページ。素材の準備が正しくなければ、その後のチューニングに意味はありません。

永続的なAIアーティファクトで開発を始める

APIキーを取得して、タスクベースの1つのAPIで画像・動画・音声モデルを呼び出せます。

APIドキュメントを読む