how-tos

MAI Image 2.7 API 가이드: cURL과 Python으로 첫 이미지 생성

Poyo.ai Team
7 min read
Share:

cURL과 Python으로 보는 MAI Image 2.7 API 가이드

이 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"를 보내세요. 알파 검사와 측정한 스티커 실행은 투명 배경 가이드에서 다룹니다.

필드 검증 규칙

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

필드규칙
modelmai-image-2.7 또는 mai-image-2.7-flash
prompt필수, 1~32,000자, 공백만으로는 불가
image_urls공개 HTTP 또는 HTTPS URL 1~5개의 배열, JPEG·PNG·WebP
size1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 또는 WIDTHxHEIGHT
사용자 지정 크기양변이 16으로 나누어떨어지고, 각 변 768 이상, 너비 x 높이 4,194,304 이하
resolution1K(약 1 MP) 또는 2K(약 4 MP, 16:9는 2720x1536). 종횡비 크기에 적용
backgroundopaque 또는 transparent. transparent는 output_format png 또는 webp 필요
output_formatpng, 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잘못된 파라미터본문을 수정. 그대로 재시도하지 않음
401API 키 누락 또는 무효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.71,000크레딧($5.00)1,600크레딧($8.00)6,800크레딧($34.00)
mai-image-2.7-flash350크레딧($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도 사용할 수 있습니다.

Share: