how-tos

Panduan MAI Image 2.7 API: Gambar Pertama dengan cURL dan Python

Poyo.ai Team
8 min read
Share:

Panduan MAI Image 2.7 API dengan cURL dan Python

Panduan MAI Image 2.7 API ini membawa Anda dari API key sampai gambar jadi dengan cURL dan Python, lalu membahas setiap mode input yang diterima skema PoYo: text-to-image, edit satu gambar, komposisi multi-gambar, ukuran kustom, output 2K, serta PNG atau WebP transparan. Setiap body di bawah memakai ID model mai-image-2.7; ganti dengan mai-image-2.7-flash untuk tier yang lebih murah, karena kedua skema MAI Image 2.7 identik kecuali ID-nya.

Aturan field berasal dari referensi API PoYo. Untuk mengetahui apa model ini dan bagaimana perbandingannya, mulailah dari ikhtisar MAI Image 2.7 API.

Langkah 1: kirim request MAI Image 2.7 API dengan cURL

Buat key di dashboard PoYo dan export sebagai POYO_API_KEY. Simpan di server Anda, bukan di kode browser.

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"
    }
  }'

Submit yang berhasil mengembalikan code: 200 dan objek data berisi task_id, status: "not_started" dan created_time. Itu adalah task dalam antrean, bukan gambar. Selalu periksa code di body: beberapa error validasi dikembalikan dengan HTTP 200 dan code: 400.

Langkah 2: polling status task

curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Status bergerak dari not_started, running, lalu finished atau failed. Task yang selesai mencantumkan gambar di data.files sebagai objek dengan file_url dan file_type: "image", serta melaporkan tagihan di credits_amount. Task yang gagal menjelaskan penyebabnya di error_message.

Langkah 3: loop polling Python dengan batas waktu

Loop ini memeriksa status HTTP dan code di body, berhenti saat failed, dan menyerah setelah 10 menit tanpa mengirim ulang. Dalam uji peluncuran kami pada 19 November 2026, gambar 2K 16:9 butuh sekitar 66 detik di MAI Image 2.7 dan sekitar 42 detik di Flash, jadi interval polling 5 detik sudah cukup.

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)

Timeout berarti "periksa lagi task ID yang sama nanti". Mengirim ulang akan memulai task kedua yang ikut ditagih.

Semua mode input MAI Image 2.7 API

Semua field berada di dalam input. ID model dan callback_url opsional berada di level atas.

Text-to-image

Hanya prompt yang wajib. Tanpa size, outputnya 1:1; tanpa resolution, outputnya 1K (1024x1024 untuk persegi).

{
  "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"
  }
}

Edit satu gambar

Kirim satu URL di image_urls. Nilainya harus berupa array meskipun hanya satu gambar.

{
  "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"]
  }
}

Tanpa size, hasil edit mempertahankan rasio aspek gambar referensi pertama pada sekitar 1 megapiksel. Tambahkan size jika Anda ingin rasio lain atau ukuran kustom.

Gabungkan 2 sampai 5 gambar

Beberapa URL digabungkan menjadi satu gambar baru. Sebut gambar-gambar itu di prompt berdasarkan perannya agar model tahu gambar mana menyumbang apa.

{
  "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"
  }
}

Gambar referensi dipakai hingga sekitar 1 megapiksel, jadi tidak perlu mengirim file yang jauh lebih besar dari itu.

Ukuran kustom

String WIDTHxHEIGHT dipakai persis seperti yang diberikan.

{
  "model": "mai-image-2.7",
  "input": {
    "prompt": "A wide panoramic banner of a mountain range at sunrise",
    "size": "3072x1344"
  }
}

Latar belakang transparan dan format output

{
  "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 juga berlaku untuk gambar opaque: kirim "jpeg" untuk file foto yang lebih kecil. Panduan latar belakang transparan membahas pengecekan alpha dan run stiker yang kami ukur.

Aturan validasi field

Validasi di sisi Anda sebelum submit agar request yang salah cepat gagal:

FieldAturan
modelmai-image-2.7 atau mai-image-2.7-flash
promptWajib, 1 sampai 32,000 karakter, tidak boleh hanya spasi
image_urlsArray berisi 1 sampai 5 URL HTTP atau HTTPS publik, JPEG, PNG atau WebP
size1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 atau WIDTHxHEIGHT
Ukuran kustomKedua sisi habis dibagi 16, tiap sisi minimal 768, lebar x tinggi maksimal 4,194,304
resolution1K (sekitar 1 MP) atau 2K (sekitar 4 MP, 16:9 adalah 2720x1536); berlaku untuk ukuran rasio aspek
backgroundopaque atau transparent; transparent membutuhkan output_format png atau webp
output_formatpng, jpeg atau webp
Field tak dikenalDitolak; skema tidak mengizinkan properti tambahan, jadi hapus field seperti enable_web_search dari request MAI Image 2.6

Contoh: 2048x2048 dan 3072x1344 lolos; 3000x1400 gagal (bukan kelipatan 16); 640x1600 gagal (ada sisi di bawah 768); 2400x2400 gagal (5,760,000 piksel). "background": "transparent" dengan "output_format": "jpeg" gagal karena JPEG tidak punya alpha channel.

Error yang perlu ditangani

codeArtiYang harus dilakukan
400Parameter tidak validPerbaiki body; jangan ulangi tanpa perubahan
401API key tidak ada atau tidak validPeriksa header Authorization: Bearer
402Kredit tidak cukupIsi ulang, lalu kirim ulang
429Batas rate terlampauiTunda, lalu coba lagi nanti
500, 502, 503Error server, upstream atau ketersediaanCoba lagi dengan backoff; periksa dulu apakah task ID sudah dikembalikan

Task yang mencapai failed setelah submit membawa alasannya di error_message, misalnya penolakan kebijakan konten. Lihat Error Codes untuk daftar lengkapnya. Jika aplikasi Anda menerima unggahan pengguna sebagai image_urls, menyaringnya lebih dulu bisa mengurangi task gagal; panduan moderasi gambar menunjukkan salah satu caranya.

Gunakan callback alih-alih polling

Tambahkan "callback_url": "https://your-app.example.com/poyo-webhook" di level atas body. Saat task selesai atau gagal, PoYo melakukan POST data task (bentuknya sama dengan data di respons status) ke URL tersebut, ditandatangani dengan HMAC-SHA256 di header X-Webhook-Signature. Dokumentasi webhook menjelaskan aturan tanda tangannya. Tetap siapkan polling lambat sebagai cadangan untuk callback yang tidak pernah datang.

Cara tagihan pertama Anda dihitung

MAI Image 2.7 API menagih token: input teks, input gambar (untuk image_urls), dan output gambar. Di PoYo, output sekitar satu token per 1,024 piksel.

ModelInput teksInput gambarOutput gambar (per 1 juta token)
mai-image-2.71,000 kredit ($5.00)1,600 kredit ($8.00)6,800 kredit ($34.00)
mai-image-2.7-flash350 kredit ($1.75)500 kredit ($2.50)2,000 kredit ($10.00)

Uji hari peluncuran kami (API produksi PoYo, 19 November 2026) menunjukkan artinya dalam praktik. Request kafe 2K 16:9 yang sama menghasilkan 2720x1536 di kedua tier dan, pada tarif saat ini, berbiaya 27.802 kredit (sekitar $0.139) di mai-image-2.7 dan 8.1803 kredit (sekitar $0.041) di mai-image-2.7-flash. Estimasi turunan: 2720x1536 adalah 4,177,920 piksel, sekitar 4,080 token output, yang setara 27.744 dan 8.16 kredit; sisa kecil pada masing-masing cocok dengan sekitar 58 token prompt. Artikel harga berisi tabel biaya untuk setiap ukuran.

Pertanyaan yang sering diajukan

Apakah MAI Image 2.7 API kompatibel dengan OpenAI SDK? Tidak. Ini adalah API task asinkron: submit ke /api/generate/submit, lalu polling /api/generate/status/{task_id} atau terima callback. requests, fetch atau cURL biasa sudah cukup.

Bagaimana cara mengedit gambar dengan MAI Image 2.7 API? Tambahkan image_urls berisi satu URL gambar publik dan jelaskan perubahannya di prompt. Dengan 2 sampai 5 URL, gambar-gambar itu digabungkan.

Bisakah saya menetapkan ukuran piksel persis di MAI Image 2.7 API? Bisa, kirim size sebagai WIDTHxHEIGHT dengan kedua sisi habis dibagi 16, tiap sisi minimal 768, dan total maksimal 4,194,304 piksel.

Berapa gambar yang dikembalikan satu request MAI Image 2.7 API? Satu. Kirim beberapa task secara paralel untuk variasi.

Apakah MAI Image 2.7 API bisa mengembalikan JPEG? Ya, dengan "output_format": "jpeg", selama background bernilai opaque. PNG adalah default dan WebP juga tersedia.

Share: