how-tos

Ideogram 4.6 API 가이드: cURL과 Python으로 첫 이미지 생성과 편집

Poyo.ai Team
7 min read
Share:

cURL과 Python으로 보는 Ideogram 4.6 API 가이드

이 Ideogram 4.6 API 가이드는 API 키 발급부터 cURL과 Python으로 완성된 이미지를 받기까지의 과정을 안내하고, 이어서 PoYo 스키마가 받는 모든 입력 모드를 다룹니다. 프리셋 또는 사용자 지정 크기의 텍스트-이미지, 투명 배경, 일반 편집, 마스크 편집, 참조 이미지, 고정밀 편집입니다. 텍스트-이미지는 모델 ID ideogram-v4.6, 편집은 ideogram-v4.6-edit를 사용하며, 두 ID 모두 Ideogram 4.6 모델 페이지에 나와 있습니다.

필드 규칙은 PoYo API 레퍼런스를 기준으로 합니다. 모델이 무엇이고 다른 모델과 어떻게 다른지는 Ideogram 4.6 API 개요부터 확인하십시오.

1단계: cURL로 Ideogram 4.6 API 요청 제출하기

PoYo 대시보드에서 키를 만들고 POYO_API_KEY로 export합니다. 키는 브라우저 코드가 아닌 서버에 보관하십시오.

curl https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v4.6",
    "input": {
      "prompt": "A colorful storefront with a neon sign reading \"HELLO\""
    }
  }'

이 요청은 기본값(size: auto(약 2K), quality: medium, 이미지 한 장)을 사용하므로 비용은 12 credits($0.06)입니다. 제출에 성공하면 code: 200과 함께 task_id, status: "not_started", created_time이 담긴 data 객체가 반환됩니다. 이것은 대기열에 들어간 작업일 뿐 이미지가 아닙니다. 본문의 code는 매번 확인하십시오. 일부 검증 오류는 HTTP 200과 code: 400으로 돌아옵니다.

2단계: 작업 상태 폴링하기

curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

상태는 not_started, running을 거쳐 finished 또는 failed가 됩니다. 완료된 작업은 data.files에 이미지마다 항목 하나를 담고, 각 항목에는 file_url과 file_type: "image"가 있으며, 과금액은 credits_amount에 표시됩니다. 실패한 작업은 error_message에 원인을 알려 줍니다.

3단계: 제한 시간이 있는 Python 폴링 루프

이 루프는 HTTP 상태와 본문의 code를 모두 확인하고, failed에서 멈추며, n이 1보다 크면 모든 이미지를 반환하고, 다시 제출하지 않은 채 10분 후에 중단합니다.

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]

def checked(response):
    body = response.json()
    if response.status_code >= 400 or body.get("code") != 200:
        error = body.get("error") or {}
        raise RuntimeError(f"PoYo error {body.get('code')}: {error.get('message', body)}")
    return body["data"]

def run(model, input_body, max_wait=600):
    task = checked(session.post(BASE + "/api/generate/submit",
                                json={"model": model, "input": input_body},
                                timeout=60))
    task_id = task["task_id"]
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        time.sleep(5)
        task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
        if task["status"] == "failed":
            raise RuntimeError(task.get("error_message") or "generation failed")
        if task["status"] == "finished":
            images = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
            return images, task.get("credits_amount")
    raise TimeoutError("Still running, check this task later: " + task_id)

images, credits = run("ideogram-v4.6", {
    "prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
    "size": "1728x2304",
    "quality": "high",
    "n": 2,
})
print(images, credits)

1728x2304는 3,981,312픽셀의 3:4 크기로 4,194,304픽셀 경계보다 작으므로, 두 이미지는 2K high 요금으로 과금됩니다: 2 × 20 = 40 credits($0.20). 타임아웃은 "같은 작업 ID를 나중에 다시 확인하라"는 뜻입니다. 다시 제출하면 과금되는 두 번째 작업이 시작됩니다. 같은 run()을 편집에도 쓸 수 있습니다. 모델로 "ideogram-v4.6-edit"를 전달하면 됩니다.

Ideogram 4.6 API의 모든 입력 모드

모든 필드는 input 안에 넣습니다. 모델 ID와 선택 사항인 callback_url은 최상위에 둡니다.

4K 텍스트-이미지

{
  "model": "ideogram-v4.6",
  "input": {
    "prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
    "size": "2048x3072",
    "quality": "high",
    "n": 2
  }
}

2048x3072는 6,291,456픽셀로 4,194,304를 넘으므로 4K 티어이며, 이 크기에서는 very_low를 사용할 수 없습니다.

투명 배경과 고정 시드

{
  "model": "ideogram-v4.6",
  "input": {
    "prompt": "A flat sticker of a smiling coffee cup",
    "size": "1:1 HD",
    "quality": "low",
    "background": "transparent",
    "seed": 42
  }
}

transparent는 알파 채널이 있는 이미지를 반환하고, opaque는 단색 배경을 강제합니다. 같은 결과를 다시 얻으려면 같은 본문을 같은 seed로 보내십시오.

일반 편집

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Replace the background with a blue photo studio",
    "image_urls": [
      "https://example.com/source.png"
    ]
  }
}

일반 편집은 프롬프트를 바탕으로 이미지를 다시 생성합니다. image_urls는 이미지를 정확히 한 장 담은 배열이어야 하며, 공개 HTTP(S) URL 또는 base64 data URI로 지정합니다. 로컬 파일을 보내려면 먼저 PoYo의 파일 업로드 엔드포인트로 업로드하십시오.

참조 이미지로 스타일 변경

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Restyle the product shot to match the reference",
    "image_urls": [
      "https://example.com/product.png"
    ],
    "reference_image_urls": [
      "https://example.com/style.png"
    ],
    "size": "2048x2048",
    "quality": "low",
    "n": 2
  }
}

참조 이미지는 최대 4장, 마스크를 쓰면 3장까지 허용됩니다. 마스크 없는 일반 편집이므로 여기서는 사용자 지정 size를 쓸 수 있습니다.

이미지 전체의 고정밀 편집

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Change only the date line to \"JULY 3-5 · RIVERSIDE PARK\". Keep everything else exactly the same.",
    "image_urls": [
      "https://example.com/poster.png"
    ],
    "edit_precision": "high",
    "context_window": "none",
    "size": "auto",
    "quality": "high"
  }
}

이것은 출시일 편집(작업 672JRU198S22NS8D, 2026년 11월 20일)의 본문이며, 소스 URL만 바꿨습니다. 소스는 2304×3072 포스터였고, 출력은 그 크기를 유지한 채 날짜 줄만 바뀌었으며, 작업은 4K high 편집 요금인 120 credits($0.60)로 과금되었습니다.

국소 마스크 편집

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Change the sign text to \"OPEN LATE\"",
    "image_urls": [
      "https://example.com/storefront.png"
    ],
    "mask_url": "https://example.com/sign-mask.png",
    "edit_precision": "high",
    "context_window": "auto",
    "quality": "high"
  }
}

마스크는 소스와 크기가 같아야 하고, 검은색(편집)과 흰색(유지) 영역을 모두 포함해야 합니다. context_window: auto를 쓰면 마스크 주변 영역만 소스 해상도로 편집됩니다. 마스크가 너무 크면 이미지 전체 편집으로 대체됩니다.

필드 검증 규칙

잘못된 요청이 빨리 실패하도록, 제출 전에 직접 검증하십시오.

필드규칙
modelideogram-v4.6 또는 ideogram-v4.6-edit
prompt필수, 1~10,000자, 공백만으로는 불가
sizeauto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 또는 소문자 x를 쓴 WIDTHxHEIGHT
사용자 지정 크기각 변 2564096이며 32의 배수, 종횡비는 1:66:1 범위
qualityvery_low는 출력이 4,194,304픽셀 이하일 때만
n1~8의 정수, 문자열과 불리언은 거부
image_urls편집 전용, 이미지를 정확히 한 장 담은 배열
mask_url, edit_precision: highsize: auto(또는 size 생략) 필요
backgroundedit_precision이 high이면 거부
context_window: automask_url과 edit_precision: high 필요
알 수 없는 필드unsupported fields 오류로 거부

예: 2304x3072는 통과합니다(두 변 모두 32의 배수). 1296x3168은 Ideogram 4.5에서는 허용되었지만 1296이 32의 배수가 아니므로 실패합니다. 4096x512는 실패합니다(비율 8:1). 2048x3072에서 very_low도 실패합니다.

처리해야 할 오류

code의미대응
400잘못된 파라미터본문을 수정합니다. 그대로 재시도하지 마십시오
401API 키 누락 또는 무효Authorization: Bearer 헤더를 확인합니다
402크레딧 부족충전한 뒤 다시 제출합니다
429속도 제한 초과간격을 두고 나중에 재시도합니다
500, 502, 503서버, 업스트림 또는 가용성 오류백오프로 재시도합니다. 그 전에 작업 ID가 이미 반환되었는지 확인합니다

failed에 도달한 작업은 error_message에 원인을 담고 있습니다. 전체 목록은 Error Codes를 참고하십시오.

폴링 대신 콜백 사용하기

본문의 최상위(input 안이 아님)에 "callback_url": "https://your-app.example.com/poyo-webhook"를 추가합니다. 작업이 완료되거나 실패하면 PoYo는 작업 데이터를 해당 URL로 POST하며, X-Webhook-Signature 헤더에 HMAC-SHA256 서명을 붙입니다. 서명 규칙은 웹훅 문서에 있습니다. 콜백이 도착하지 않는 경우에 대비해 느린 폴링을 대체 수단으로 남겨 두십시오.

첫 청구액 계산 방법

Ideogram 4.6 API는 출력 이미지마다 과금합니다: 품질 및 크기 티어 가격 × n. 1 credit = $0.005입니다.

요청티어과금
기본값(auto, medium, n: 1)텍스트-이미지 medium 2K12 credits ($0.06)
very_low, 3:4, n: 1텍스트-이미지 very_low 2K1.6 credits ($0.008)
high, 1728x2304, n: 2텍스트-이미지 high 2K40 credits ($0.20)
high, 2304x3072, n: 1텍스트-이미지 high 4K40 credits ($0.20)
2304×3072 소스의 고정밀 편집, high편집 high 4K120 credits ($0.60)

very_low와 2304x3072 행은 출시일 작업에서 실제로 과금된 금액과 일치합니다. size: auto 편집의 가격은 소스 이미지 크기로 견적되고 전달된 이미지 기준으로 확정되며, 견적을 넘지 않습니다. 가격 글에 더 많은 계산 예시가 있습니다.

자주 묻는 질문

Ideogram 4.6 API는 OpenAI SDK와 호환됩니까? 아니요. 비동기 작업 API입니다. /api/generate/submit에 제출한 뒤 /api/generate/status/{task_id}를 폴링하거나 콜백을 받습니다. 일반 requests, fetch, cURL로 동작합니다.

Ideogram 4.6 API로 이미지를 어떻게 편집합니까? image_urls에 URL 하나를, prompt에 변경 내용을 넣어 ideogram-v4.6-edit를 호출합니다. 변경을 요청하지 않은 픽셀을 유지하려면 edit_precision: high를 추가하십시오.

ideogram-v4.6에 참조 이미지를 보낼 수 있습니까? 아니요. PoYo에서 참조 이미지는 ideogram-v4.6-edit의 reference_image_urls에 넣으며, 최대 4장, 마스크를 쓰면 3장까지입니다.

Ideogram 4.6 API 요청 한 번에 이미지가 몇 장 반환됩니까? 1~8장이며 n으로 지정합니다. 각 이미지는 티어 가격으로 과금됩니다.

Ideogram 4.6 API 요청이 크기 때문에 거부된 이유는 무엇입니까? 사용자 지정 크기의 각 변은 256~4096 사이의 32의 배수여야 하며, 마스크나 고정밀 편집에는 size: auto가 필요합니다.

Share: