소개
이것은 Ideogram이 2025년 7월 공개한, 사진 한 장으로 쓰는 일관성 모델 Ideogram Character의 마스크 편집 쪽입니다. 텍스트로 장면을 지어내는 대신, 이미 가진 이미지에서 시작해 표시한 영역만 다시 그리고 그곳에 참고 인물 사진의 사람을 넣습니다. 마스크 바깥은 그대로 남습니다.
핵심 기능 및 하이라이트
한 영역만 다시 그리고 나머지는 유지
mask_url의 검은 부분은 다시 그려지고 흰 부분은 보존됩니다. 재즈 클럽 테스트에서 가수의 머리를 검게 칠했더니, 금빛 스팽글 드레스, 마이크, 밴드, 빨간 커튼은 손대지 않은 채 돌아오고 얼굴과 머리만 참고 사진의 검은 단발 여성으로 바뀌었습니다.
원본 이미지가 화면을 정합니다
편집 결과는 image_url의 비율을 유지합니다. 세로형 무대 사진은 866×1154로 돌아왔습니다. 새 장면 생성은 항상 정사각형을 돌려주므로, 캐릭터가 들어간 정사각형이 아닌 결과가 필요하다면 이 엔드포인트를 쓰세요.
생성과 같은 단계와 스타일
Turbo, Balanced, Quality가 속도와 장당 가격을, Auto, Realistic, Fiction이 분위기를 정하며, 호출 한 번에 다시 그린 버전을 최대 4장까지 받을 수 있습니다. 테스트에서 Turbo 편집은 약 25~50초 만에 끝났습니다.
요청 파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
prompt | 예 | 마스크의 검은 부분을 채울 내용만 적습니다. 인물, 표정, 옷차림, 빛을 최대 5,000자로. 1자 이상 · 5000자 이하 |
image_url | 예 | 편집할 이미지이며 JPEG, PNG, WebP 형식으로 10MB까지 받습니다. 결과는 이 이미지의 비율을 유지합니다. |
reference_image_urls | 예 | 마스크 영역에 넣을 인물의 사진 정확히 한 장. 얼굴이 잘 보이는 것으로, 10MB까지 받습니다. 1개 이상 · 1개 이하 |
mask_url | 예 | 검은색은 다시 그릴 영역, 흰색은 남길 영역입니다. image_url과 같은 비율로 만드세요. |
quality | 아니요 | turbo, balanced(기본값), quality. 상위 단계일수록 오래 걸리고 장당 가격이 높습니다. |
style | 아니요 | auto(기본값), realistic, fiction. 분위기만 바뀌고 가격은 그대로입니다. |
num_outputs | 아니요 | 요청당 다시 그린 버전 1~4장. 장마다 과금됩니다. |
enable_prompt_expansion | 아니요 | MagicPrompt는 기본으로 켜져 있어 짧은 프롬프트를 렌더링 전에 다시 씁니다. 길고 정확한 프롬프트라면 끄세요. 기본값: |
seed | 아니요 | 반복 비교용 선택 정수입니다. 같은 이미지가 나온다고 보장하지는 않습니다. |
요금
고른 단계로 돌아온 이미지 한 장마다 과금하며, 가격은 새 장면 생성과 같습니다. 거부되거나 실패한 요청은 과금하지 않습니다.
| 사양 | 요금 |
|---|---|
| $0.08 / 장 |
| $0.12 / 장 |
| $0.16 / 장 |
활용 사례
완성된 레이아웃 바꾸기
포스터 시안, 앨범 커버, 광고 시안에는 임시 얼굴이 들어 있는 경우가 많습니다. 머리를 마스크하고 확정된 인물로 다시 그리면 디자인의 다른 부분은 모두 그대로 유지됩니다.
시리즈의 일관성 수정
연작 이미지 중 한 장에서 캐릭터가 어긋났다면, 전체를 다시 만들지 말고 얼굴을 마스크해 다른 장과 같은 인물 사진으로 다시 그리세요.
로케이션 사진에 인물 넣기
먼저 장소를 촬영하거나 구하고, 인물이 있어야 할 곳을 마스크하면 모델이 그 장면의 빛에 맞춰 사람을 그려 넣습니다.
프롬프트 가이드 및 실전 팁
마스크는 넉넉하게
머리에 더해 머리카락과 목 주변까지 조금 더 검게 칠하면 새 헤어라인이 장면에 자연스럽게 섞입니다. 마스크는 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 레퍼런스에서 확인하세요.





