Ideogram 3.0 Character API 사용법? 5분 만에 첫 캐릭터 이미지 생성하기

TL;DR

• Ideogram 3.0 Character는 참조 이미지 기반 캐릭터 생성 모델입니다: 캐릭터 참조 이미지 1장을 업로드하고 장면 프롬프트 한 줄을 작성하면, 동일한 얼굴과 의상이 새로운 장면에 나타납니다. 모델 페이지 열기에서 온라인으로 체험해 보세요. 신규 사용자 가입 시 200 크레딧을 증정합니다.
• 가격은 장당: TURBO $0.09, BALANCED $0.13, QUALITY $0.18. 참조 이미지는 무료이며 실패 시 과금되지 않습니다(자세한 내용은 가격 페이지 참조).
• 호출은 HiAPI /v1/tasks 인터페이스를 사용합니다: 작업을 제출하여 taskId를 받고, 이를 사용해 결과를 조회한 후, 성공하면 output[0].url에서 이미지를 다운로드합니다.

할 수 있는 일

• 캐릭터 일관성 생성: 참조 이미지 한 장으로 캐릭터를 고정하고, 얼굴형과 의상을 일관되게 유지하며 장면을 자유롭게 변경합니다.
• 일러스트와 사실적 표현 모두 가능: style에서 AUTO / REALISTIC / FICTION을 선택할 수 있으며, 사진 인물과 일러스트 캐릭터 모두 지원합니다.
• 화면 비율은 참조 이미지 따름: 세로 참조는 3:4(864×1152), 가로 참조는 16:9(1328×752)로 출력되며, 크기 파라미터를 입력할 필요가 없습니다.
• 편집 인터페이스 제공: ideogram-v3-character/edit는 마스크를 사용하여 캐릭터를 기존 이미지의 지정 영역에 그려 넣고 나머지 화면은 그대로 둡니다.

아래는 실제 완성품입니다(참조 이미지는 가로 일러스트 캐릭터):

The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs

(한국어 의미: 이 탐험가 캐릭터가 등불이 가득한 야시장을 걸어가며, 손에 뜨거운 면이 담긴 종이컵을 들고 있고, 양옆에는 따뜻한 빛이 나는 노점이 있으며, 그림책 일러스트 스타일, 텍스트 없음, 간판 없음.)

ideogram-v3-character, TURBO, 16:9, 1328×752, $0.09.

이 프롬프트로 생성하기 →

두 인터페이스 선택 방법

	ideogram-v3-character	ideogram-v3-character/edit
하는 일	처음부터 캐릭터의 새 장면 생성	기존 이미지의 마스크 영역에 캐릭터 그리기
필수 입력	prompt + 참조 이미지 1장	prompt + 원본 이미지 + 마스크 + 참조 이미지 1장
가격 (TURBO / BALANCED / QUALITY)	$0.09 / $0.13 / $0.18	$0.09 / $0.13 / $0.18
출력	WebP, 화면 비율은 참조 이미지 따름	WebP, 크기는 원본 이미지 따름
적합한 용도	포스터, 연재, 시리즈 장면 이미지	완성된 이미지에서 캐릭터 교체, 캐릭터 추가

마스크 규칙: 검정 = 다시 그리기, 흰색 = 유지; 마스크와 원본 이미지의 가로세로 비율이 반드시 일치해야 합니다. 편집 인터페이스는 negative_prompt를 허용하지 않으며, 전달하면 400 오류가 발생합니다.

두 가지 시작 방법

브라우저 3단계: 모델 페이지 열기 → 캐릭터 참조 이미지 업로드, 프롬프트 붙여넣기 → 생성 클릭, TURBO 한 장 $0.09.

API 3단계: POST /v1/tasks 제출 → taskId 받기 → GET /v1/tasks/<taskId>로 success 확인 후 다운로드.

curl: 첫 장

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "ideogram-v3-character",
  "input": {
    "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

편집 인터페이스는 model을 ideogram-v3-character/edit로 변경하고, input에 image_url(원본 이미지)과 mask_url(마스크)을 추가합니다:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character/edit",
  "input": {
    "prompt": "The explorer character curled up in the armchair asleep under a knitted blanket",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/8e1328c02f8edd33.jpg",
    "mask_url": "https://static.hiapi.ai/gallery/2026/10/0121b5b1d8af8697.png",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

응답의 taskId가 조회凭证입니다.

Python: 제출, 폴링, 다운로드

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "ideogram-v3-character",
    "input": {
        "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
        "reference_image_urls": ["https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"],
        "rendering_speed": "TURBO",
    },
}

# 제출: Idempotency-Key 포함, 네트워크 재시도 시 작업이 중복 생성되지 않음
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# 폴링: queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # 임시 주소, 가능한 빨리 다운로드하여 저장
    img = requests.get(image_url, timeout=60)
    with open("output.webp", "wb") as f:
        f.write(img.content)
    print("saved output.webp")

파라미터 표 (ideogram-v3-character)

필드	필수	값	설명
prompt	예	1–5000자	캐릭터가 등장할 장면을 설명하며, 캐릭터 생김새가 아님(생김새는 참조 이미지 참조)
reference_image_urls	예	정확히 1장, JPEG / PNG / WebP, ≤10 MB	캐릭터 참조 이미지, 화면 비율이 출력 화면 비율 결정
rendering_speed	아니오	TURBO / BALANCED / QUALITY, 기본 BALANCED	등급과 가격 결정
style	아니오	AUTO / REALISTIC / FICTION, 기본 AUTO	REALISTIC은 사진 질감, FICTION은 일러스트 느낌 유지
seed	아니오	정수 0–2147483647	동일 파라미터 동일 seed로 화면 재현
expand_prompt	아니오	기본 true	프롬프트 자동 확장, 원문을 엄격히 따르려면 false 전달
negative_prompt	아니오	≤5000자	원하지 않는 내용

편집 인터페이스는 표 외에 image_url, mask_url 두 가지 필수 항목이 추가되며, negative_prompt를 지원하지 않습니다. 요청 본문에 표 외 필드가 포함되면 즉시 400이 발생합니다(additional properties ... not allowed).

만나게 될 오류 (인터페이스 원문)

한 일	반환
prompt 미전달	400 invalid input: prompt: missing required field "prompt"
참조 이미지 2장 전달	400 invalid input: reference_image_urls: maxItems: got 2, want 1
rendering_speed 오타	400 invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'
인터페이스가 인식하지 못하는 필드 전달	400 invalid input: <root>: additional properties 'foo' not allowed
편집 인터페이스에 negative_prompt 전달	400 invalid input: <root>: additional properties 'negative_prompt' not allowed
잔액 부족	402 insufficient account balance; top up and retry

동일한 Idempotency-Key로 중복 제출하면 409(처리 중) 또는 422(파라미터 불일치)가 반환되며, 새 key로 다시 시도하세요.

출시 전 주의사항

• 콜백: 요청 본문 최상위에 "callback": {"url": "https://..."}를 전달하면 작업이 종료 상태에 도달할 때 서비스에 알림이 전송되어 폴링을 생략할 수 있습니다.
• 즉시 저장: output[0].url은 임시 주소이므로 받자마자 다운로드하여 자체 스토리지에 저장하고, 영구 링크로 사용하지 마세요.
• 등급과 화면 비율 명시: rendering_speed는 매번 명시적으로 전달하세요(전달하지 않으면 BALANCED로 과금). 출력 화면 비율은 참조 이미지로 결정되므로 세로 장면에는 세로 참조 이미지를 준비하세요.
• 배치 작업은 각자 고유 키 사용: 각 제출에 고유한 Idempotency-Key를 포함하면 네트워크 재시도 시 동일한 key로 동일한 작업만 조회되며, 작업 중복 생성 및 크레딧 중복 차감이 발생하지 않습니다.

자주 묻는 질문

참조 이미지를 URL로 지정할 수 있나요?

가능합니다. 접근 가능한 http/https 주소라면 JPEG, PNG, WebP 모두 가능하며 최대 10 MB입니다.

참조 이미지를 몇 장 전달할 수 있나요?

정확히 1장이며, 이는 필수 규칙으로 2장 전달 시 즉시 400 오류가 발생합니다. 캐릭터를 바꾸려면 참조 이미지를 교체하세요.

크기 파라미터를 전달해야 하나요?

아니요. 출력 화면 비율은 참조 이미지를 따릅니다: 세로 참조는 864×1152, 가로 참조는 1328×752로 출력됩니다.

두 인터페이스의 호출 방식이 동일한가요?

동일합니다. model과 input 내 필드만 변경하면 됩니다.

실패 시 과금되나요?

아니요. 사전 차감된 크레딧은 실패 종료 상태 후 전액 환불됩니다.

다음 단계: 위의 야시장 프롬프트로 모델 페이지에서 한 장 시도해 보세요, 그런 다음 장면에 맞는 프롬프트를 프롬프트 모음에서 확인하세요. 세 가지 가격 등급과 예산표는 가격 페이지를 참조하세요.