how-tos

MAI Image 2.7 APIガイド:cURLとPythonで最初の画像を生成

Poyo.ai Team
3 min read
Share:

cURLとPythonで使うMAI Image 2.7 APIガイド

この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"を送ります。アルファチェックと計測したステッカーの実行例は透過背景ガイドで扱っています。

フィールドのバリデーションルール

不正なリクエストがすぐに失敗するよう、送信前に自分の側で検証してください。

フィールドルール
modelmai-image-2.7またはmai-image-2.7-flash
prompt必須、1〜32,000文字、空白のみは不可
image_urls1〜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。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で署名します。署名のルールはWebhookのドキュメントにあります。コールバックが届かない場合に備え、低頻度のポーリングをフォールバックとして残しておいてください。

最初の請求額の計算方法

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を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も利用できます。

Share: