Ideogram 4.5 API 사용법? 생성, 편집 및 작업 조회

TL;DR

• Ideogram 4.5는 텍스트 조판 우선의 텍스트-투-이미지 시리즈입니다. ideogram-v4.5/text-to-image는 포스터, 로고 워드마크, 이중 언어 패키지처럼 텍스트가 포함된 이미지를 생성하고, ideogram-v4.5/image-to-image는 Precise Edit로 글자를 정밀하게 수정하거나, 참조 이미지로 스타일을 바꾸거나, 마스크로 일부를 수정합니다. 모델 페이지에서 작업을 선택하거나 아래와 같이 API를 호출할 수 있습니다.
• 가격은 장당 계산되며 품질 등급에 따라 달라집니다. LOW $0.043, MEDIUM(기본) $0.086, HIGH $0.3145; 편집 등급 VERY_LOW $0.0115부터; 현재 요청마다 1장을 출력하며 num_images는 1만 가능합니다. 자세한 내용은 가격 페이지를 참고하세요.
• 호출은 HiAPI /v1/tasks 인터페이스를 사용합니다. 제출 후 data.taskId를 읽고, 다시 data.status를 조회합니다. 성공 후 data.output에서 type=image인 주소를 가져와 다운로드합니다.

할 수 있는 일

• 화면 텍스트 계층 구성: 표시할 텍스트를 따옴표로 묶고 제목, 부제목, 날짜, 라인업의 위치를 각각 설명합니다. 출력 후 글자 하나하나 확인합니다.
• 단일 작업으로 구도 탐색: 요청마다 1장을 출력합니다. 프롬프트나 seed를 조정하여 여러 작업을 각각 제출해 방향을 비교합니다.
• 연계 편집 인터페이스: Precise Edit(edit_precision=high)는 브랜드명, 날짜 등 소규모 수정에 사용할 수 있습니다. 원본 이미지와 대조하여 유지 영역을 확인합니다.
• 참조 이미지 + 마스크: 참조 이미지는 최대 4장(마스크 포함 시 3장); 마스크 검정 = 재생성, 흰색 = 유지.

아래는 생성된 실제 결과물입니다(LOW 등급):

Minimal modern brand poster for a design conference. Huge bold headline text "DESIGN FORWARD" centered, smaller subtitle "Typography Summit 2026" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering

(한국어 의미: 미니멀 모던 디자인 콘퍼런스 브랜드 포스터, 중앙에 초대형 볼드 제목 "DESIGN FORWARD", 아래에 작은 글씨 부제목 "Typography Summit 2026", 스위스 그리드 레이아웃, 따뜻한 오렌지와 딥 네이비 배색, 기하학적 도형, 선명하고 날카로운 글자. 크기는 landscape_16_9 선택.)

ideogram-v4.5/text-to-image, LOW, landscape_16_9, 1280×720, $0.043.

이 프롬프트로 생성하기 →

두 인터페이스 선택 방법

	ideogram-v4.5/text-to-image	ideogram-v4.5/image-to-image
하는 일	텍스트에서 조판이 포함된 이미지 생성	기존 이미지 편집
필수 입력	prompt	image_url + prompt
품질 등급	low / medium / high	very_low / low / medium / high
특징 파라미터	num_images: 1, enable_prompt_expansion	edit_precision(Precise), reference_image_urls, mask_url
크기	6가지 프리셋, 기본 square_hd	auto(기본) 또는 6가지; 마스크 / Precise 시 auto만 가능
적합	포스터, 로고, 패키지, 간판 신규 시안	글자 수정, 배색 교체, 시즌 버전, 부분 재생성

일반적인 파이프라인: 브랜드 포스터를 생성한 후 Edit로 브랜드명이나 날짜를 고객 버전으로 수정합니다. 생성 LOW 1장 $0.043에 Precise LOW 글자 수정 1회 $0.043, 한 세트 $0.086.

두 가지 시작 경로

브라우저 3단계: 모델 페이지 열기 → 프롬프트 붙여넣기, 품질 등급 선택 → 생성 클릭.

API 3단계: POST /v1/tasks 제출 → data.taskId 읽기 → GET /v1/tasks/<taskId>로 data.status 조회, success가 되면 다운로드.

curl: 첫 장

먼저 터미널에서 HIAPI_IDEMPOTENCY_KEY를 이번 업무의 고유 식별자로 설정하고, 동일 요청 재시도 시 이 값을 그대로 사용합니다. 예시는 LOW, 가로 크기, 확장 활성화를 명시적으로 사용합니다.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/text-to-image",
  "input": {
    "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
    "quality": "low",
    "image_size": "landscape_16_9",
    "enable_prompt_expansion": true,
    "num_images": 1
  }
}'

편집 인터페이스: model을 ideogram-v4.5/image-to-image로 바꾸고 원본 이미지와 지시문을 전달합니다. 아래는 Precise Edit로 글자 수정 및 레이아웃 유지 요구를 제시하며, 결과물은 여전히 원본 이미지와 대조하여 확인해야 합니다:

이 편집 작업에는 HIAPI_EDIT_IDEMPOTENCY_KEY를 별도로 설정하고, 생성 작업의 키를 재사용하지 마세요.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_EDIT_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "Change the logo text from \"Ember & Oak\" to \"Maple & Co\", keep the same serif lettering style, emblem, tagline, colors and layout exactly unchanged",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/88567ad2baf46b32.png",
    "edit_precision": "high",
    "quality": "low",
    "image_size": "auto",
    "num_images": 1
  }
}'

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

먼저 requests를 설치하고 HIAPI_API_KEY를 설정합니다. 최초 제출 시에는 HIAPI_IDEMPOTENCY_KEY도 설정해야 하며, 새 업무마다 독립적인 값을 사용하고 동일 제출 재시도 시에는 값을 유지합니다. 프로그램은 먼저 작업 ID를 출력합니다. 중단 후 HIAPI_TASK_ID를 설정하면 조회 및 다운로드를 계속할 수 있으며 생성이 다시 제출되지 않습니다.

import os
import time
from pathlib import Path

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
headers = {"Authorization": "Bearer " + os.environ["HIAPI_API_KEY"]}
payload = {
    "model": "ideogram-v4.5/text-to-image",
    "input": {
        "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
        "quality": "low",
        "image_size": "landscape_16_9",
        "enable_prompt_expansion": True,
        "num_images": 1,
    },
}
# Set HIAPI_TASK_ID to resume polling without creating another task.
task_id = os.environ.get("HIAPI_TASK_ID")
if not task_id:
    # Use one unique key per business operation; keep it for retries.
    submission_key = os.environ["HIAPI_IDEMPOTENCY_KEY"]
    response = requests.post(
        BASE, headers={**headers, "Idempotency-Key": submission_key},
        json=payload, timeout=30,
    )
    response.raise_for_status()
    created = response.json()
    if created.get("code") != 200:
        raise RuntimeError(created)
    task_id = created["data"]["taskId"]
print("Keep this task ID:", task_id, flush=True)

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{BASE}/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    result = response.json()
    if result.get("code") != 200:
        raise RuntimeError(result)
    task = result["data"]
    if task["status"] in ("fail", "failed"):
        raise RuntimeError(task.get("error", task))
    if task["status"] == "success":
        image_url = next(
            (item["url"] for item in task.get("output", [])
             if item.get("type") == "image" and item.get("url")), None,
        )
        if not image_url:
            raise RuntimeError("Successful task has no image URL")
        # Do not forward API authorization to the media download host.
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        media_type = image.headers.get("Content-Type", "").split(";", 1)[0].lower()
        suffix = {"image/png": ".png", "image/jpeg": ".jpg",
                  "image/webp": ".webp"}.get(media_type)
        if not suffix:
            raise RuntimeError("Unexpected image content type: " + media_type)
        target = Path(task_id + suffix)
        partial = target.with_suffix(suffix + ".part")
        partial.write_bytes(image.content)
        partial.replace(target)
        print("Saved:", target)
        break
    time.sleep(3)
else:
    raise TimeoutError(f"Polling timed out; keep checking task {task_id}")

조회 또는 다운로드 중 네트워크 오류가 발생하면 출력된 작업 ID를 보관한 후 재개하세요. 스크립트는 생성 요청을 자동으로 다시 보내지 않습니다. 예시 폴링 상한은 600초, 대기 간격은 3초이며, 다운로드는 먼저 .part 파일에 쓰고 완료 후 정식 파일명으로 변경합니다.

파라미터 표

생성 ideogram-v4.5/text-to-image

필드	필수	값	설명
prompt	예	1–10000자	네 문단 작성: 어떤 이미지 → 텍스트와 배색 → 레이아웃 → 질감과 제약
quality	아니오	low / medium / high, 기본 medium	대량 탐색 low, 일상 medium, 작은 글자가 많은 최종본 high
image_size	아니오	6가지 프리셋, 기본 square_hd	사용자 정의 너비/높이 없음
num_images	아니오	고정 1	작업마다 1장 출력
enable_prompt_expansion	아니오	기본 true	프롬프트 확장; false로 확장 끄기, 여전히 결과물 텍스트 확인 필요
seed	아니오	정수	동일 파라미터로 재현

편집 ideogram-v4.5/image-to-image

필드	필수	값	설명
image_url	예	이미지 주소	원본 이미지
prompt	예	1–10000자	편집 지시; 무엇을 바꾸고 무엇을 유지할지 명확히 작성
edit_precision	아니오	regular / high, 기본 regular	high = Precise Edit, 소규모 글자 수정에 적합
quality	아니오	very_low / low / medium / high, 기본 medium	very_low는 regular와만 조합 가능
image_size	아니오	auto 또는 6가지 프리셋, 기본 auto	마스크 또는 Precise 시 auto만 가능
reference_image_urls	아니오	최대 4장	마스크 포함 시 최대 3장
mask_url	아니오	이미지 주소	검정 = 재생성, 흰색 = 유지
num_images	아니오	고정 1	작업마다 1장 출력
seed	아니오	정수

input 내에 해당 모델 파라미터 표 이외의 필드가 있으면 400을 반환합니다. 최상위 model, callback 등은 작업 인터페이스 형식에 맞게 작성합니다.

발생할 수 있는 오류

상태 코드	의미	처리 방법
400 INVALID_REQUEST	요청 본문이 유효하지 않음(prompt 또는 image_url 누락, 열거값 오류, 표 외 필드 전달)	파라미터 표에 맞춰 요청 본문 수정
402 INSUFFICIENT_QUOTA	잔액 부족(과금되지 않음)	충전 후 재시도
429 RATE_LIMITED	속도 제한 발생	제출 빈도 낮추기
409 IDEMPOTENCY_KEY_PROCESSING	동일 키 작업이 생성 중	대기 후 동일 키와 동일 요청 본문으로 재시도
422 IDEMPOTENCY_KEY_MISMATCH	동일 키에 다른 요청 본문 사용	원래 요청 본문 복원; 새 업무 작업에만 새 키 사용

작업 종료 상태 실패에는 CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT 등의 오류 코드가 포함될 수 있습니다. taskId와 오류 정보를 보관하고, 작업 최종 상태와 계정 기록을 대조하여 정산을 확인하세요. 조회 실패나 다운로드 실패를 생성 실패로 간주하지 마세요.

출시 전 주의사항

• 콜백: 요청 본문 최상위에 "callback": {"url": "https://..."}를 전달하면 종료 상태가 자동 통지됩니다.
• 즉시 저장: data.output의 결과 링크에는 유효 기간이 있으므로 성공 후 즉시 다운로드하세요.
• 단일 작업과 멱등성: 매번 1장 출력; 동일 업무 요청이 타임아웃으로 재시도될 때 원래 멱등 키를 사용하고, 새 업무 작업에만 새 키를 사용합니다.
• 중국어 작은 글자: 실제 문구로 품질 등급을 비교하고, 납품 전 글자 하나하나 교정하세요. medium이나 high도 검사를 대체할 수 없습니다.

자주 묻는 질문

한 번 요청에 최대 몇 장 생성되나요?

현재 생성과 편집 모두 매번 1장을 출력하며 num_images는 1만 가능합니다. 여러 방향은 작업을 각각 제출하세요.

기본 품질 등급이 LOW인가요?

아니요. 기본은 MEDIUM이며 장당 $0.086입니다. LOW 장당 $0.043이 필요하면 quality: "low"를 명시적으로 전달하세요.

브랜드명과 날짜만 바꾸려면 어떤 모드를 쓰나요?

Precise Edit를 선택하고 edit_precision: "high", quality: "low", image_size: "auto"를 명시적으로 전달하세요. 장당 $0.043입니다.

마스크의 검정과 흰색 영역은 각각 무엇을 의미하나요?

검정 영역은 재생성, 흰색 영역은 유지입니다. 마스크는 원본 이미지와 동일 크기여야 하며, 마스크 사용 시 image_size는 auto를 선택하세요.

제출 타임아웃 후 멱등 키를 바꿔야 하나요?

동일 업무 요청 재시도 시에는 키를 바꾸지 말고 동일한 Idempotency-Key와 동일 요청 본문을 사용하세요. 정말 새 작업이 필요할 때만 새 키를 사용합니다.

다음 단계: DESIGN FORWARD 포스터 프롬프트로 모델 페이지에서 한 장 생성한 후, 한 문장의 Precise 지시로 제목을 자신의 이벤트명으로 바꿔 보세요. 함께 읽기: 세 등급 가격과 예산 · 4가지 편집 프롬프트 사례.

바로 워드마크나 이벤트 포스터를 만들고 싶다면 이 프롬프트 사례 모음을 복사하세요.