
이 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를 쓰면 마스크 주변 영역만 소스 해상도로 편집됩니다. 마스크가 너무 크면 이미지 전체 편집으로 대체됩니다.
필드 검증 규칙
잘못된 요청이 빨리 실패하도록, 제출 전에 직접 검증하십시오.
| 필드 | 규칙 |
|---|---|
model | ideogram-v4.6 또는 ideogram-v4.6-edit |
prompt | 필수, 1~10,000자, 공백만으로는 불가 |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 또는 소문자 x를 쓴 WIDTHxHEIGHT |
| 사용자 지정 크기 | 각 변 256 |
quality | very_low는 출력이 4,194,304픽셀 이하일 때만 |
n | 1~8의 정수, 문자열과 불리언은 거부 |
image_urls | 편집 전용, 이미지를 정확히 한 장 담은 배열 |
mask_url, edit_precision: high | size: auto(또는 size 생략) 필요 |
background | edit_precision이 high이면 거부 |
context_window: auto | mask_url과 edit_precision: high 필요 |
| 알 수 없는 필드 | unsupported fields 오류로 거부 |
예: 2304x3072는 통과합니다(두 변 모두 32의 배수). 1296x3168은 Ideogram 4.5에서는 허용되었지만 1296이 32의 배수가 아니므로 실패합니다. 4096x512는 실패합니다(비율 8:1). 2048x3072에서 very_low도 실패합니다.
처리해야 할 오류
code | 의미 | 대응 |
|---|---|---|
| 400 | 잘못된 파라미터 | 본문을 수정합니다. 그대로 재시도하지 마십시오 |
| 401 | API 키 누락 또는 무효 | 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 2K | 12 credits ($0.06) |
very_low, 3:4, n: 1 | 텍스트-이미지 very_low 2K | 1.6 credits ($0.008) |
high, 1728x2304, n: 2 | 텍스트-이미지 high 2K | 40 credits ($0.20) |
high, 2304x3072, n: 1 | 텍스트-이미지 high 4K | 40 credits ($0.20) |
2304×3072 소스의 고정밀 편집, high | 편집 high 4K | 120 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가 필요합니다.