how-tos

Руководство по MAI Image 2.7 API: первое изображение на cURL и Python

Poyo.ai Team
8 min read
Share:

Руководство по MAI Image 2.7 API с cURL и Python

Это руководство по 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", чтобы получить файлы-фотографии меньшего размера. В руководстве по прозрачному фону описаны проверки альфа-канала и наш измеренный прогон со стикером.

Правила валидации полей

Проверяйте запрос на своей стороне до отправки, чтобы ошибочные запросы отсеивались сразу:

ПолеПравило
modelmai-image-2.7 или mai-image-2.7-flash
promptОбязательно, от 1 до 32,000 символов, не только пробелы
image_urlsМассив из 1–5 публичных HTTP- или HTTPS-URL, 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; для прозрачности нужен output_format png или webp
output_formatpng, 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.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)

Наш тест в день запуска (продакшн-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.

Share: