
このMAI Image 2.7 APIガイドでは、APIキーの用意からcURLとPythonで画像を完成させるまでを説明し、続いてPoYoのスキーマが受け付けるすべての入力モードを扱います。テキストから画像生成、1枚の画像の編集、複数画像の合成、カスタムサイズ、2K出力、透過PNGまたはWebPです。以下のボディはすべてモデルIDmai-image-2.7を使っています。安いティアを使う場合はmai-image-2.7-flashに置き換えてください。2つのMAI Image 2.7スキーマはIDを除いて同一です。
フィールドのルールはPoYo APIリファレンスに基づいています。モデルの概要や比較については、まずMAI Image 2.7 APIの概要をご覧ください。
ステップ1:cURLでMAI Image 2.7 APIリクエストを送信する
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と、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を後でもう一度確認する」という意味です。再送信すると課金対象のタスクがもう1つ始まります。
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つ渡します。画像が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枚目の参照画像のアスペクト比を保ち、約1メガピクセルになります。別の比率やカスタムサイズにしたい場合はsizeを追加します。
2〜5枚の画像を合成する
複数のURLは1枚の新しい画像に合成されます。どの画像が何を提供するのかモデルにわかるよう、プロンプトでは役割で画像を指定してください。
{
"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。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で署名します。署名のルールはWebhookのドキュメントにあります。コールバックが届かない場合に備え、低頻度のポーリングをフォールバックとして残しておいてください。
最初の請求額の計算方法
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を1つ入れたimage_urlsを追加し、promptで変更内容を記述します。URLが2〜5個なら画像が合成されます。
MAI Image 2.7 APIで正確なピクセルサイズを指定できますか?
はい。sizeをWIDTHxHEIGHTとして送ります。両辺が16で割り切れ、各辺768以上、合計4,194,304ピクセル以下である必要があります。
MAI Image 2.7 APIの1リクエストで返される画像は何枚ですか? 1枚です。バリエーションが欲しい場合は複数のタスクを並行して送信してください。
MAI Image 2.7 APIはJPEGを返せますか?
はい。backgroundがopaqueであれば"output_format": "jpeg"で返せます。デフォルトはPNGで、WebPも利用できます。