
Это руководство по 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.
Правила полей взяты из справочника API PoYo. Чтобы узнать, что это за модель и как она выглядит на фоне других, начните с обзора MAI Image 2.7 API.
Шаг 1: отправьте запрос к MAI Image 2.7 API через cURL
Создайте ключ в панели PoYo и экспортируйте его как POYO_API_KEY. Храните его на сервере, а не в браузерном коде.
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 и объект data с task_id, status: "not_started" и created_time. Это задача в очереди, а не изображение. Каждый раз проверяйте 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 минут, не отправляя запрос повторно. В нашем тесте в день запуска, 19 ноября 2026 года, изображение 2K 16:9 заняло около 66 секунд на MAI Image 2.7 и около 42 секунд на Flash, так что интервала опроса в 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"
}
}
Правка одного изображения
Передайте один URL в image_urls. Это должен быть массив даже для одного изображения.
{
"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 | Массив из 1–5 публичных HTTP- или HTTPS-URL, 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; для прозрачности нужен output_format png или webp |
output_format | png, jpeg или webp |
| Неизвестные поля | Отклоняются; схема не допускает дополнительных свойств, поэтому уберите поля вроде enable_web_search из запросов MAI Image 2.6 |
Примеры: 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 | Ошибка сервера, апстрима или доступности | Повторите с backoff; сначала проверьте, не был ли уже возвращён ID задачи |
Если задача после отправки перешла в failed, причина указана в error_message, например отклонение по политике контента. Полный список — в Error Codes. Если ваше приложение принимает загрузки пользователей как image_urls, предварительная проверка сэкономит неудачные задачи; один из способов показан в руководстве по модерации изображений.
Callback вместо опроса
Добавьте "callback_url": "https://your-app.example.com/poyo-webhook" на верхнем уровне тела запроса. Когда задача завершится или упадёт, PoYo отправит POST с данными задачи (в той же форме, что data в ответе статуса) на этот URL, подписанный HMAC-SHA256 в заголовке X-Webhook-Signature. Правило подписи описано в документации по вебхукам. Оставьте медленный опрос как запасной вариант на случай, если callback так и не придёт.
Как считается первый счёт
MAI Image 2.7 API тарифицирует токены: текстовый ввод, ввод изображений (для image_urls) и вывод изображений. В PoYo на вывод приходится примерно один токен на 1,024 пикселя.
| Модель | Текстовый ввод | Ввод изображений | Вывод изображений (за 1M токенов) |
|---|---|---|---|
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) |
Наш тест в день запуска (продакшн-API PoYo, 19 ноября 2026 года) показывает, что это значит на практике. Один и тот же запрос 2K 16:9 с кафе вернул 2720x1536 на обоих уровнях и по текущим ставкам обходится в 27.802 кредита (около $0.139) на mai-image-2.7 и 8.1803 кредита (около $0.041) на mai-image-2.7-flash. Расчётная оценка: 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} или получение callback. Подойдут обычные requests, fetch или cURL.
Как отредактировать изображение через MAI Image 2.7 API?
Добавьте image_urls с одним публичным URL изображения и опишите изменение в prompt. При 2–5 URL изображения объединяются.
Можно ли задать точный размер в пикселях в MAI Image 2.7 API?
Да, передайте size как WIDTHxHEIGHT: обе стороны кратны 16, каждая не меньше 768 и всего не больше 4,194,304 пикселей.
Сколько изображений возвращает один запрос к MAI Image 2.7 API? Одно. Для вариаций отправляйте несколько задач параллельно.
Возвращает ли MAI Image 2.7 API JPEG?
Да, с "output_format": "jpeg", если background равен opaque. По умолчанию PNG, также доступен WebP.