블로그

사용 가이드

Ideogram V3 Character Edit 연동 가이드: 소스 이미지, 마스크, 캐릭터 참조 이미지 준비 방법

세 가지 이미지 입력이 각자 역할을 수행: 계약 필드에 따라 부분 편집을 제출하고, 캐릭터 일관성과 경계를 항목별로 자체 점검

Nov 18, 2026
블로그 커버 이미지: 짙은 먹색 녹색 바탕 위에 두 쌍의 넓고 평평한 띠가 교차해 기술적인 직조 격자를 이루고, 황동색이 세로로穿插하며 기하학적으로 절제된 모습.
이 페이지에서

세 가지 이미지 입력이 각각 담당하는 것

ideogram-v3-character/edit를 연동하기 전에 먼저 세 이미지 필드의 역할을 분리하면, 이후의 모든 준비 작업이 명확해집니다.

  • 소스 이미지 image_url: "어떤 화면을 바꿀지"를 결정합니다. 원본 구도, 배경, 피사체 위치를 제공하며 전체 편집 작업의 토대입니다.
  • 마스크 mask_url: "어디를 바꿀지"를 결정합니다. 다시 그려야 할 영역만 표시하며, 영역 밖의 내용은 유지되어야 합니다.
  • 캐릭터 참조 이미지 reference_image_urls: "캐릭터가 어떻게 생겼는지"를 결정합니다. 캐릭터의 외모 특징을 제공하여 재생성 결과가 참조 캐릭터와 정렬되도록 합니다.

세 가지의 경계를 혼동하지 마세요. 소스 이미지는 캐릭터 참조 이미지가 아니며, 캐릭터 참조 이미지도 소스 이미지를 대체할 수 없습니다. 마스크는 공간 제약이지 내용 설명이 아닙니다. 캐릭터 특징은 참조 이미지에, 화면 내용은 prompt에, 수정 범위는 마스크에 맡기는 것이 오류를 가장 줄이는 분할 방식입니다. 일단 혼용하면(예: 캐릭터 이미지만 업로드하고 마스크를 켜지 않거나, 마스크로 캐릭터 생김새를 "암시"하는 경우) 문제를排查할 때 판단 근거를 잃게 됩니다.

계약 수준에서 소스 이미지와 마스크는 문자열 URL 필드이고, 캐릭터 참조 이미지는 배열 필드입니다. 세 가지의 타입이 다르다는 점 역시 용도가 다르다는 것을 보여줍니다. 앞의 두 가지는 일대일 공간 짝이며, 후자는 독립적인 인물 설명 소스입니다.

세 가지 입력은 병렬로 쌓이는 것이 아닙니다. 소스 이미지, 마스크, 캐릭터 참조 이미지가 각각 출력 프레임의 서로 다른 영역을 담당하며, 그림은 세 개의 합류선으로 분업을 표현합니다.

소스 이미지와 마스크 준비 요점

image_url과 mask_url은 모두 필수 필드이며, 형식은 URI이고 http:// 또는 https://로 시작해야 합니다(계약 pattern ^https?://). 최소 길이는 1입니다.

가로세로 비율이 반드시 일치해야 함

계약이 두 필드에 부과하는 유일한 강제 기하 제약은 마스크가 소스 이미지와 동일한 가로세로 비율을 유지해야 한다는 것입니다. 이는 권장 사항이 아니라 전제 조건이므로, 소재를 준비할 때 가장 안전한 방법은 먼저 로컬에서 마스크를 소스 이미지 크기에 맞춰 출력한 뒤 함께 업로드하는 것입니다. 서버가 정렬해 주리라고 기대하지 마세요.

마스크의 의미: 재생성 영역만 표시

마스크는 "재생성 허용" 위치를 표시합니다. 따라서:

  • 유지해야 할 부분은 마스크 영역에 들어가지 않도록 합니다.
  • 변경해야 할 피사체(예: 의상 변경, 포즈 변경)는 마스크 안에 완전히 들어가야 하며, 가장자리가 잘리지 않도록 합니다.
  • 마스크를 너무 조각조각 만들지 마세요. 흩어진 작은 조각들은 모델이 편집 의도를 이해하기 어렵게 만듭니다.

URL 사용 가능성

두 필드 모두 원격 URL이므로, 제출 전에 링크가 익명으로 접근 가능한지, 리디렉션이 만료되지 않았는지, 로그인이 필요한 인증이 없는지 반드시 확인하세요. 마스크는 투명 채널이 있거나 흑백 대비가 명확한 이미지를 사용하여 반투명 그라데이션으로 인한 경계 모호성을 피하는 것이 좋습니다.

캐릭터 참조 이미지의 사양과 제한

reference_image_urls는 필수 배열 필드이며, 계약이 명확한 제약을 제시합니다: minItems: 1, maxItems: 1, 즉 단 한 장만 필요합니다. 두 장을 전달하거나 0장을 전달하면 모두 불법 입력으로 판정됩니다. 이는 많은 "다중 이미지 참조"의 직관과 반대이므로 연동 시 실수하기 쉽습니다.

형식과 용량

  • 지원 형식: JPEG, PNG, WebP
  • 단일 이미지 최대 10 MB

이미지 선택 권장 사항

캐릭터 참조 이미지의 역할은 안정적인 인물 특징을 제공하는 것이므로:

  1. 선명하고 정면 또는 정면에 가까우며 얼굴이 가려지지 않은 이미지를 선택합니다.
  2. 강한 역광, 과한 필터, 여러 명이 함께 찍은 사진(모델이 누구를 정렬해야 할지 판단할 수 없음)을 피합니다.
  3. 전신과 반신은 각각 장단점이 있습니다. 의상 디테일이 필요하면 반신 이상, 전체 스타일링이 필요하면 전신을 사용합니다.
  4. 이미 복잡한 배경이 있는 이미지로 장면을 "암시"하지 마세요. 장면은 prompt 설명에 맡기세요.

배열 형식이 요소 하나만 담더라도, 작성할 때는 여전히 배열로 제출해야 합니다. 예를 들어 단일 URL을 하나의 항목으로 감싸야 하며, 문자열을 직접 넣으면 안 됩니다.

필수 및 선택 필드 조합 방법

필수 항목은 총 네 가지입니다: 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의 enum은 AUTO, REALISTIC, FICTION이며 기본값은 AUTO입니다. 사실적인 인물이 필요하면 REALISTIC, 스타일화된 일러스트에는 FICTION을 사용하고, 확실하지 않으면 AUTO에 두세요.
  • seed는 정수이며 범위는 0부터 2147483647까지이고, 동일한 프롬프트의 생성 결과를 재현하는 데 사용합니다. "동일 입력, 다른 파라미터"를 비교하고 싶을 때 seed를 고정하면 무작위성 간섭을 배제할 수 있습니다.

rendering_speed 단계 선택

rendering_speed는 문자열 enum이며 기본값은 BALANCED이고, 총 세 단계입니다:

  • TURBO: 가장 빠른 이미지 생성으로, 초안 단계에서 마스크 범위와 캐릭터가 맞는지 빠르게 검증하기에 적합합니다.
  • BALANCED: 기본 단계로, 속도와 디테일의 절충이며 일상적인 연동의 출발점입니다.
  • QUALITY: 디테일이 가장 풍부하여 최종 이미지 생성 전 확정 라운드에 적합합니다.

선택 방식은 한 번에 고정하는 것이 아니라 단계별로 전환하는 것입니다. 먼저 TURBO로 기하와 캐릭터 방향에 문제가 없는지 확인한 뒤, BALANCED나 QUALITY로 디테일을 다듬습니다. 이렇게 하면 반복 디버깅 시 고품질 렌더링에 시간을 소모하지 않습니다.

강조할 점은 세 단계의 과금 기준에 차이가 있다는 것입니다(이미지 생성 단계별 과금). 구체적인 가격은 사이트 가격 패널을 기준으로 하며, 이 글에서는 숫자를 다루지 않습니다. 이미지 입력 문제를排查할 때는 먼저 기본 단계로 고정하면 변수를 하나 줄일 수 있습니다.

세 단계는 같은 직조 방식의 밀도 변화와 같습니다. 위쪽으로 갈수록 직조가 촘촘해지고 디테일이 많아지며 속도는 느려집니다.

제출 전 자체 점검 목록

계약에 따라 항목별로 확인하면 대부분의 실패를 제출 전에 막을 수 있습니다:

  • prompt가 비어 있지 않고 5000자를 초과하지 않으며, 내용은 편집 지시가 아닌 장면 설명입니다.
  • image_url이 http:// 또는 https://로 시작하는 익명 접근 가능 링크입니다.
  • mask_url도 접근 가능하며, 소스 이미지와 가로세로 비율이 일치합니다.
  • reference_image_urls가 배열이고 길이가 정확히 1입니다.
  • 해당 참조 이미지 형식이 JPEG/PNG/WebP이고 크기가 10 MB를 초과하지 않습니다.
  • 선택 필드의 철자와 enum 값이 정확합니다(style, rendering_speed는 계약에 나열된 대문자 값을 사용).
  • seed를 설정했다면 0–2147483647의 정수인지 확인합니다.
  • expand_prompt를 비활성화했다면 prompt 자체가 충분히 완전한지 확인합니다.

이 목록은 문제 해결의 첫 관문이기도 합니다. 어느 하나라도 충족되지 않으면 설명을 반복 조정하기보다 입력을 먼저 수정하세요.

캐릭터 편차와 경계 문제의排查思路

생성 결과가 기대와 다를 때는 먼저 문제를 분류한 뒤 대상에 맞게 조정하는 것이 전체 이미지를 다시 제출하는 것보다 효과적입니다.

유형 1: 캐릭터가 닮지 않음

얼굴 특징, 헤어스타일, 체형이 참조 이미지와 벗어나는 경우입니다. 조정 방향:

  • 참조 이미지 교체: 더 선명한 정면 이미지, 더 좋은 조명, 단일 인물 피사체
  • 참조 이미지가 잘렸거나 과도하게 압축되지 않았는지 확인
  • prompt에 캐릭터 설명(의상, 체형, 나이 느낌)을 보충하여 텍스트와 이미지가 서로 보강되도록 함
  • 장면 복잡도를 낮추어 배경 요소가 캐릭터 디테일을 빼앗지 않도록 함

유형 2: 경계가 흐려짐

마스크 밖의 내용이 의도치 않게 변경되거나, 마스크 가장자리에 이음새, 잔상이 나타나는 경우입니다. 조정 방향:

  • 먼저 소스 이미지와 마스크의 가로세로 비율이 엄격히 일치하는지 확인
  • 마스크가 유지해야 할 부분까지 포함했는지 확인
  • 피사체가 마스크 안에 완전히 들어가도록 하여 잘림 방지
  • 더 명확한 마스크 가장자리로 교체하여 반투명 전환 감소

두 유형의 문제를 함께 조정하지 마세요. 캐릭터 문제는 참조 이미지와 설명을, 경계 문제는 마스크와 기하를 수정합니다. 한 번에 변수 하나만 바꿔야 어느 항목이 효과가 있었는지 판단할 수 있습니다.

예시에서 연동까지

위의 계약 요구 사항을 프로세스로 만들면 네 단계입니다. 동일 가로세로 비율의 소스 이미지와 마스크를 준비하고, 규격에 맞는 캐릭터 참조 이미지 한 장을 선택하고, 장면화된 prompt로 새 화면을 설명하고, 목록에 따라 필드를 확인한 뒤 제출합니다.

연동 진입점은 모델 페이지에 있으며, 필드 정의와 enum 값은 페이지를 기준으로 합니다. 이 글의 목록과 항목별로 대조할 수 있습니다: Ideogram V3 Character Edit 모델 페이지. 소재 준비가 맞아야 이후의 튜닝이 의미를 가집니다.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기