はじめに
これは、Ideogram が 2025 年 7 月に公開した写真 1 枚で使える一貫性モデル Ideogram Character のマスク編集の側です。テキストからシーンを作る代わりに、手持ちの画像から始めて、印をつけた部分だけを描き直し、そこに参考ポートレートの人物を入れます。マスクの外側はそのまま残ります。
主な機能とハイライト
1 か所だけ描き直し、ほかは残す
mask_url の黒い部分が描き直され、白い部分は保たれます。ジャズクラブのテストでは歌手の頭を黒く塗りました。金のスパンコールのドレス、マイク、バンド、赤いカーテンは手つかずのまま戻り、顔と髪だけが参考写真の黒いボブの女性になりました。
元の画像が画面を決める
編集結果は image_url の比率を保ちます。縦長のステージ写真は 866 × 1154 で返りました。新しいシーンの生成は常に正方形を返すので、キャラクターで正方形以外の結果を得たいときはこのエンドポイントを使います。
生成と同じ段階とスタイル
Turbo、Balanced、Quality が速さと 1 枚あたりの料金を、Auto、Realistic、Fiction が見た目を決め、1 回の呼び出しで描き直した版を最大 4 枚受け取れます。テストでは Turbo の編集が約 25〜50 秒で完了しました。
リクエストパラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
prompt | はい | マスクの黒い部分を埋める内容だけを書きます。人物、表情、服装、光を 5,000 文字以内で。 1 文字以上 · 5000 文字以内 |
image_url | はい | 編集する画像で、形式は JPEG、PNG、WebP、サイズは 10 MB までです。結果はこの画像の比率を保ちます。 |
reference_image_urls | はい | マスク部分に入れる人物のポートレートをちょうど 1 枚。顔がはっきり見えるもので、10 MB まで。 1 件以上 · 1 件以内 |
mask_url | はい | 黒が描き直す部分、白が残す部分です。 |
quality | いいえ | turbo、balanced(既定)、quality。上位の段階ほど時間がかかり、1 枚あたりの料金も上がります。 |
style | いいえ | auto(既定)、realistic、fiction。見た目が変わり、料金は変わりません。 |
num_outputs | いいえ | 1 回のリクエストで描き直した版を 1〜4 枚。1 枚ごとに課金されます。 |
enable_prompt_expansion | いいえ | MagicPrompt は既定でオンで、短いプロンプトを描画前に書き換えます。長く正確なプロンプトではオフにします。 デフォルト値: |
seed | いいえ | 比較をくり返すための任意の整数。同じ画像になる保証はありません。 |
料金
選んだ段階で、返ってきた画像 1 枚ごとに課金します。料金は新しいシーンの生成と同じで、拒否や失敗したリクエストは課金されません。
| 仕様 | 料金 |
|---|---|
| $0.08 / 枚 |
| $0.12 / 枚 |
| $0.16 / 枚 |
ユースケース
完成したレイアウトの差し替え
ポスターのラフ、アルバムジャケット、広告カンプには仮の顔が入っていることがよくあります。頭をマスクして承認済みのタレントで描き直せば、デザインのほかの部分はすべてそのまま保てます。
シリーズ内の一貫性の修正
一連の画像の中で 1 枚だけキャラクターがずれたら、全体を作り直すのではなく、顔をマスクしてほかと同じポートレートから描き直します。
ロケーション写真に人物を置く
先にロケーションを撮影するか用意し、人物を置きたい場所をマスクすれば、モデルがその場面の光に合わせて人物を描き込みます。
プロンプトガイドと実践のヒント
マスクは大きめに
頭に加えて髪と首まわりを少し余分に黒く塗ると、新しい生え際がシーンになじみます。マスクは image_url と同じ比率にし、白いまま残した部分は必ず保たれます。ページ上ではアップロードした画像に直接マスクを描けます。
マスクの中身だけを書く
プロンプトはマスクの内側に現れるものについて書きます。たとえば、赤いステージライトの下で目を閉じて歌う黒いボブの女性、という具合です。シーン全体を繰り返す必要はなく、マスクの外の変更を求めても効果はありません。
衣装の変更は控えめに
体にかかる大きなマスクは衣装やポーズの調整には使えますが、テストではこのモードは成人向けの要望を描かずに控えめにしました。より自由度が必要なシーンには、同じポートレートで新しいシーンのエンドポイントを使ってください。
API クイックスタート
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "ideogram/character/edit",
"input": {
"image_url": "https://example.com/reference.png",
"mask_url": "https://example.com/reference.png",
"num_outputs": 1,
"prompt": "A ceramic teapot on a linen cloth, soft window light, muted palette",
"quality": "balanced",
"reference_image_urls": [
"https://example.com/reference.png"
],
"style": "auto"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
認証、完全なスキーマ、ポーリング、エラー処理は API リファレンスを参照してください。





