
이 MAI Image 2.7 API 가이드는 API 키에서 시작해 cURL과 Python으로 완성된 이미지를 얻기까지를 안내하고, 이어서 PoYo 스키마가 받는 모든 입력 모드를 다룹니다. 텍스트-이미지, 단일 이미지 편집, 다중 이미지 합성, 사용자 지정 크기, 2K 출력, 투명 PNG 또는 WebP입니다. 아래의 모든 본문은 모델 ID mai-image-2.7을 사용합니다. 더 저렴한 티어를 쓰려면 mai-image-2.7-flash로 바꾸세요. 두 MAI Image 2.7 스키마는 ID를 제외하면 동일합니다.
필드 규칙은 PoYo API 레퍼런스를 따릅니다. 모델이 무엇이고 어떻게 비교되는지는 MAI Image 2.7 API 개요부터 보세요.
1단계: cURL로 MAI Image 2.7 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": "mai-image-2.7",
"input": {
"prompt": "A university campus poster at dusk with the title \"Open Day 2026\", photorealistic, cinematic light",
"size": "16:9",
"resolution": "2K"
}
}'
제출에 성공하면 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에서 멈추며, 재제출 없이 10분 후 포기합니다. 2026년 11월 19일 출시 테스트에서 2K 16:9 이미지는 MAI Image 2.7에서 약 66초, Flash에서 약 42초가 걸렸으므로 5초 폴링 간격이면 충분합니다.
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 generate(input_body, model="mai-image-2.7", 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[0], task.get("credits_amount")
raise TimeoutError("Still running, check this task later: " + task_id)
url, credits = generate({
"prompt": "A rainy-night cafe with a neon sign reading \"OPEN LATE\"",
"size": "16:9",
"resolution": "2K",
})
print(url, credits)
타임아웃은 "같은 작업 ID를 나중에 다시 확인하라"는 뜻입니다. 재제출하면 과금되는 작업이 하나 더 시작됩니다.
MAI Image 2.7 API의 모든 입력 모드
모든 필드는 input 안에 들어갑니다. 모델 ID와 선택 사항인 callback_url은 최상위에 둡니다.
텍스트-이미지
prompt만 필수입니다. size가 없으면 출력은 1:1, resolution이 없으면 1K(정사각형이면 1024x1024)입니다.
{
"model": "mai-image-2.7",
"input": {
"prompt": "A university campus poster at dusk with the title \"Open Day 2026\", photorealistic, cinematic light",
"size": "16:9",
"resolution": "2K"
}
}
이미지 1장 편집
image_urls에 URL 하나를 전달합니다. 이미지가 1장이어도 배열이어야 합니다.
{
"model": "mai-image-2.7",
"input": {
"prompt": "Change the bicycle to blue and add a small dog next to it",
"image_urls": ["https://example.com/bicycle.png"]
}
}
size가 없으면 편집 결과는 첫 번째 참조 이미지의 종횡비를 유지하며 약 1메가픽셀입니다. 다른 비율이나 사용자 지정 크기를 원하면 size를 추가하세요.
이미지 2~5장 합성
여러 URL은 하나의 새 이미지로 합성됩니다. 모델이 어떤 이미지가 무엇을 제공하는지 알 수 있도록 프롬프트에서 역할로 이미지를 지칭하세요.
{
"model": "mai-image-2.7",
"input": {
"prompt": "Place the sneaker from image 1 on the wooden boards from image 2, at the pier from image 3, golden hour",
"image_urls": [
"https://example.com/sneaker.png",
"https://example.com/boards.png",
"https://example.com/pier.png"
],
"size": "16:9"
}
}
참조 이미지는 최대 약 1메가픽셀로 사용되므로, 그보다 훨씬 큰 파일을 보낼 필요는 없습니다.
사용자 지정 크기
WIDTHxHEIGHT 문자열은 지정한 그대로 사용됩니다.
{
"model": "mai-image-2.7",
"input": {
"prompt": "A wide panoramic banner of a mountain range at sunrise",
"size": "3072x1344"
}
}
투명 배경과 출력 형식
{
"model": "mai-image-2.7",
"input": {
"prompt": "A flat vector logo of a red fox head, clean edges, no background",
"background": "transparent",
"output_format": "webp"
}
}
output_format은 불투명 이미지에도 사용할 수 있습니다. 사진류 파일을 더 작게 하려면 "jpeg"를 보내세요. 알파 검사와 측정한 스티커 실행은 투명 배경 가이드에서 다룹니다.
필드 검증 규칙
잘못된 요청이 빨리 실패하도록 제출 전에 직접 검증하세요.
| 필드 | 규칙 |
|---|---|
model | mai-image-2.7 또는 mai-image-2.7-flash |
prompt | 필수, 1~32,000자, 공백만으로는 불가 |
image_urls | 공개 HTTP 또는 HTTPS URL 1~5개의 배열, JPEG·PNG·WebP |
size | 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 또는 WIDTHxHEIGHT |
| 사용자 지정 크기 | 양변이 16으로 나누어떨어지고, 각 변 768 이상, 너비 x 높이 4,194,304 이하 |
resolution | 1K(약 1 MP) 또는 2K(약 4 MP, 16:9는 2720x1536). 종횡비 크기에 적용 |
background | opaque 또는 transparent. transparent는 output_format png 또는 webp 필요 |
output_format | png, jpeg 또는 webp |
| 알 수 없는 필드 | 거부됨. 스키마가 추가 속성을 허용하지 않으므로 MAI Image 2.6 요청의 enable_web_search 같은 필드는 삭제 |
예시: 2048x2048과 3072x1344는 통과합니다. 3000x1400은 실패합니다(16의 배수가 아님). 640x1600은 실패합니다(768 미만인 변). 2400x2400은 실패합니다(5,760,000픽셀). "background": "transparent"와 "output_format": "jpeg"의 조합은 JPEG에 알파 채널이 없으므로 실패합니다.
처리해야 할 오류
code | 의미 | 조치 |
|---|---|---|
| 400 | 잘못된 파라미터 | 본문을 수정. 그대로 재시도하지 않음 |
| 401 | API 키 누락 또는 무효 | Authorization: Bearer 헤더 확인 |
| 402 | 크레딧 부족 | 충전 후 재제출 |
| 429 | 속도 제한 초과 | 간격을 두고 나중에 재시도 |
| 500, 502, 503 | 서버, 업스트림 또는 가용성 오류 | 백오프로 재시도. 먼저 작업 ID가 이미 반환되었는지 확인 |
제출 후 failed에 도달한 작업은 error_message에 이유(예: 콘텐츠 정책 거부)를 담고 있습니다. 전체 목록은 Error Codes를 참조하세요. 앱이 사용자 업로드를 image_urls로 받는다면, 먼저 검사하면 실패 작업을 줄일 수 있습니다. 한 가지 방법은 이미지 모더레이션 가이드에서 보여 줍니다.
폴링 대신 콜백 사용
본문 최상위에 "callback_url": "https://your-app.example.com/poyo-webhook"을 추가합니다. 작업이 완료되거나 실패하면 PoYo는 작업 데이터(상태 응답의 data와 같은 형태)를 해당 URL로 POST하며, X-Webhook-Signature 헤더에 HMAC-SHA256 서명을 넣습니다. 서명 규칙은 웹훅 문서에 있습니다. 도착하지 않는 콜백에 대비해 느린 폴링을 대체 수단으로 남겨 두세요.
첫 청구액 계산 방법
MAI Image 2.7 API는 토큰으로 과금합니다. 텍스트 입력, 이미지 입력(image_urls용), 이미지 출력입니다. PoYo에서 출력은 약 1,024픽셀당 1토큰입니다.
| 모델 | 텍스트 입력 | 이미지 입력 | 이미지 출력(100만 토큰당) |
|---|---|---|---|
mai-image-2.7 | 1,000크레딧($5.00) | 1,600크레딧($8.00) | 6,800크레딧($34.00) |
mai-image-2.7-flash | 350크레딧($1.75) | 500크레딧($2.50) | 2,000크레딧($10.00) |
출시일 테스트(PoYo 프로덕션 API, 2026년 11월 19일)가 실제 의미를 보여 줍니다. 같은 2K 16:9 카페 요청이 두 티어 모두에서 2720x1536을 반환했고, 현재 요율 기준으로 mai-image-2.7에서 27.802크레딧(약 $0.139), **mai-image-2.7-flash에서 8.1803크레딧(약 $0.041)**입니다. 추정치: 2720x1536은 4,177,920픽셀로 약 4,080 출력 토큰이며, 이는 27.744크레딧과 8.16크레딧에 해당합니다. 각각의 작은 나머지는 약 58 프롬프트 토큰과 일치합니다. 모든 크기의 비용표는 가격 글에 있습니다.
자주 묻는 질문
MAI Image 2.7 API는 OpenAI SDK와 호환되나요?
아니요. 비동기 작업 API입니다. /api/generate/submit으로 제출한 뒤 /api/generate/status/{task_id}를 폴링하거나 콜백을 받습니다. 일반 requests, fetch 또는 cURL로 동작합니다.
MAI Image 2.7 API로 이미지를 어떻게 편집하나요?
공개 이미지 URL 하나가 담긴 image_urls를 추가하고 prompt에 변경 내용을 설명하세요. URL이 2~5개면 이미지가 합성됩니다.
MAI Image 2.7 API에서 정확한 픽셀 크기를 지정할 수 있나요?
네. size를 WIDTHxHEIGHT로 보내세요. 양변이 16으로 나누어떨어지고, 각 변 768 이상, 총 4,194,304픽셀 이하여야 합니다.
MAI Image 2.7 API 요청 하나는 이미지를 몇 장 반환하나요? 1장입니다. 변형이 필요하면 여러 작업을 병렬로 제출하세요.
MAI Image 2.7 API는 JPEG를 반환하나요?
네. background가 opaque이면 "output_format": "jpeg"로 가능합니다. 기본값은 PNG이며 WebP도 사용할 수 있습니다.