Z-Image Turbo API ガイド
まず結論 · Z-Image Turbo は MaxAPI で prunaai/z-image-turbo を指定し、画像生成と参照画像の編集に利用します。カタログ上の参照上限は 0 枚、掲載ルートは official です。素材、権限、出力設定は実際のルートで確認してください。
接続仕様の確認日 ·
MaxAPI の公開カタログ、ゲートウェイ実装、ローカル回帰ケースで確認した接続情報です。共通処理の確認は各モデルのエンドツーエンドテストではなく、上流の現在の稼働状況や性能の報告でもありません。
導入前の確認事項
以下は MaxAPI の公開設定です。選択したルートに追加の入力条件や利用条件がある場合があります。
- リクエストのモデル ID
prunaai/z-image-turbo- 出力の種類
- 画像
- Base URL
https://api.maxapi.dev- 生成フロー
- 同期応答／非同期タスク
- 解像度とサイズ
- 64–2048 px per edge · default 1024x1024 · num_outputs default 1
テキストからの画像生成のみです。prompt と size、または width と height を指定します。各辺は 64〜2048 の整数とし、参照画像やマスクは指定できません。
モデルの特徴と選び方
寸法を指定するテキスト画像生成
Z-Image Turbo は Replicate の prunaai/z-image-turbo を使用します。MaxAPI は 1 枚のテキスト画像生成、寸法指定、PNG・JPEG・WebP 出力を提供し、公式ルートは返却された課金情報で精算します。
出典確認 ·
このモデルの出典: Replicate · Z-Image Turbo API schema
比較するとよい用途
プロンプトによる下書きや構図の比較に使います。比較時はシード、寸法、ステップ数を固定し、採用前に実際の画像を確認してください。
制限と注意点
参照編集やマスクは利用できません。各辺は 64〜2048 ピクセルです。出力は丸められる場合があります（64→128、720→768）。課金単位は縦横の積ではなく、512×512 の実測では 0.5 段階で 1.25 単位です。リクエストした出力 1 枚あたりの基本予約額 0.025 クレジットを実費で精算し、アカウント倍率を適用します。
提供元の能力説明は MaxAPI の全機能を示すものではありません。この入口に記載したパラメータ、入力、ルートを使用してください。速度や品質の位置付けはサービス保証ではありません。
MaxAPI でのリクエスト処理
どのルートが優先される？
ルートの優先順は API キーの route_modes リスト → リクエストで明示したルート → モデルの既定ルートです。キーに空でないリストがある場合、リクエストの route_mode より優先します。ルート比較の前にキー設定を確認してください。
ユーザーの RPM は配下のキーで共有
ユーザーの有効な RPM 上限は配下のキーで共有します。キーはより厳しく制限できますが、ユーザー上限を超えて許可できません。ユーザーが 200 RPM ならキーごとに 200 RPM ではありません。サービス全体の RPM と同時実行制御も適用されます。
ルートと料金
公開ルート：official。画像／動画の JSON リクエストでは route_mode、Gemini ネイティブでは X-MaxAPI-Route-Mode を指定します。ルートは接続先と課金の選択であり、別の公開モデル ID ではありません。
| ルート | 公開基本料金 | 課金単位 |
|---|---|---|
official | $0.0025 | 0.5 · 返却された課金メガピクセルあたり |
official | $0.005 | 1 · 返却された課金メガピクセルあたり |
official | $0.01 | 2 · 返却された課金メガピクセルあたり |
official | $0.015 | 3 · 返却された課金メガピクセルあたり |
official | $0.02 | 4 · 返却された課金メガピクセルあたり |
1 クレジット = 1 米ドル。以下はカタログの基本料金で、アカウントの見積額ではありません。最終料金はアカウント倍率と有効な課金設定で決まります。トークン単価は画像 1 枚の固定料金ではありません。
現在の料金を確認最初のリクエスト
MaxAPI の API キーはサーバー環境の MAXAPI_KEY に設定し、ブラウザーに埋め込まないでください。キーのルート一覧が設定済みならリクエスト指定より優先され、一覧が空ならリクエスト指定、両方なければモデルの既定ルートを使います。API 呼び出しは課金される場合があります。
POST /v1/images/generationsGET /v1/images/generations/{task_id}
同期呼び出しは結果を待ちます。画像を非同期で生成するには JSON に async: true、Gemini ネイティブでは X-MaxAPI-Async: true を指定します。返されたタスク ID を保存し、上記の対応する GET エンドポイントを問い合わせてください。
curl -X POST "https://api.maxapi.dev/v1/images/generations" \
-H "Authorization: Bearer $MAXAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "prunaai/z-image-turbo",
"prompt": "a clean product photo of a glass cube",
"route_mode": "official",
"size": "1024x1024",
"n": 1
}'画像タスクの受付と完成は別です
OpenAI 互換画像エンドポイントで async=true を使うと id、status、poll_url 等を返します。同じアカウントの認証で poll_url を問い合わせます。queued／running は画像完成ではなく、問い合わせの HTTP 200 も生成成功とは限りません。
{
"id": "example-task-id",
"object": "image.generation.task",
"status": "queued",
"model": "prunaai/z-image-turbo",
"poll_url": "/v1/images/generations/example-task-id"
}最初の結果を確認
リクエスト仕様の確認 ·
公開カタログとゲートウェイのコードで確認した形式例です。有料モデルの実測、遅延測定、全ルートの現在の利用可能性を保証するものではありません。
送信する項目
model- この MaxAPI エントリーには prunaai/z-image-turbo を使います。モデル ID だけでは課金ルートは決まりません。
size / n- size=1024x1024、n=1 を使用します。各辺は 64〜2048 の 16 の倍数。size を使わない場合だけ width と height を同時に指定します。
Text-to-image only- 参照画像、マスク、編集要求は送信できません。課金は画素面積の推測ではなく、返却された resolution_target と image_output_megapixel_count を使います。
実際の結果を読む
data[]- 同期応答は data 内の url または b64_json を確認し、取得・デコード後の実寸と内容を検査します。
async=true- 非同期では id と poll_url を保存します。照会の HTTP 200 だけで成功とせず、status=succeeded と data を確認し、進捗確認のために POST を再送しないでください。
{
"data": [
{
"url": "https://example.com/generated-image.png"
}
]
}HTTP ステータスだけでなく症状で判断する
400必須項目の欠落・無効な設定
- 判断のポイント
- 400 だけでなく error.code を確認します。画像編集の空プロンプトは prompt_required です。パラメータ検証と上流の生成失敗を区別してください。
- 次の対処
- model、prompt、型、対応するサイズと品質を確認し、修正してから再送します。Gemini ネイティブでは数値の error.code と error.status を確認します。
無効な画像ファイル参照画像を読み込めない・受理されない
- 判断のポイント
- .png という名前だけでは有効な PNG と判断できません。URL がエラーページや不完全なファイルを返す場合もあります。上流の 400 が一般的な生成失敗になることもあり、ステータスだけでは原因の画像を特定できません。
- 次の対処
- 各参照を取得してローカルでデコードし、MIME と寸法を確認します。必要なら対応形式で書き出し、1 枚から順に増やして問題を特定します。無効なファイルをそのまま再送し続けないでください。
429rate_limit_exceeded / capacity_exhausted
- 判断のポイント
- 429 はユーザー／キーの RPM、サービス全体、生成容量などで発生します。Retry-After と返された X-RateLimit-*／X-Global-* ヘッダーを使って判断してください。
- 次の対処
- Retry-After があれば従い、原因に応じて頻度や同時処理数を下げ、回数制限付きで再試行します。全体容量は各アカウントの専用枠ではありません。
451content_policy_violation
- 判断のポイント
- 画像生成の失敗処理では、認識された上流のコンテンツ拒否を 451 に変換します。ネットワーク障害とは異なり、ローカル審査と上流の拒否も別の段階です。
- 次の対処
- 内容とポリシーを確認し、誤判定と思われる場合はリクエスト ID とともに問い合わせます。同じ拒否済み内容の再送や審査回避のルート変更は行わないでください。
502 / 503 / 504生成失敗・一時利用不可・タイムアウト
- 判断のポイント
- 互換画像エンドポイントでは generation_failed、generation_unavailable、generation_timeout を区別します。クライアントのタイムアウト時に、サーバー側の処理が続いている場合もあります。
- 次の対処
- タスク ID があれば再作成前に状態を確認します。ID がなければリクエスト ID と時刻を保存して調査し、一時的な失敗には回数を制限して再試行してください。
活用シーンとワークフロー
以下の用途とプロンプトは評価用の提案であり、提供元のベンチマークや実測出力ではありません。
AI で制作したコンセプト画像です。このモデルの出力例・評価結果ではありません。下記のプロンプトは出発点であり、画像の再現手順ではありません。
制作の実践・共通のヒント
プロンプトで構図を比較
被写体、照明の方向、余白を指定し、生成された構図を確認します。
イラストの下書き
短い視覚的な指示で色や形を試し、最終的な文字は編集ツールで加えます。
出力形式の選択
配信工程に合わせて PNG、JPEG、WebP を比較します。圧縮品質はモデルの推論段階ではありません。
用途に合わせて使えるプロンプト例
よいプロンプトは短い制作指示書です。被写体や制約を実際の要件に置き換え、サイズ、ルート、品質は文章だけでなく API パラメータでも指定してください。
01 / 幾何学的な陶器の静物
淡い灰色の机に青い陶器カップと小さなオレンジ色の球を置いた正方形の静物。左上から柔らかく照らし、無地の背景と余白を取る。物を分離して持ち手全体を見せ、文字やロゴは加えない。出力後の確認 · 物の分離、影、取得画像の実寸を確認します。
生成前に納品形式を決める
正方形の商品画像、横長バナー、縦長カバーでは焦点と安全領域が異なります。先に比率を決めて被写体を配置し、後からの切り取りで商品や文字の余白を失わないようにします。
上記の対応サイズ設定を使ってください。解像度名は特定の正方形サイズの保証ではなく、大きなファイルほど良いとも限りません。実際の寸法、細部、切り取りを確認し、厳密な組版はデザインツールで仕上げます。
指示から使える画像へ
具体的な指示を書く
被写体、構図、照明を指定します。テキスト専用なので参照画像やマスクは添付しません。
生成設定を固定する
1024x1024、1 枚、8 ステップから始め、シードを設定して同じ条件で指示を比較します。
出力ファイルを確認する
結果を取得してデコードし、実寸、構図、形式を確認してからアプリで使用します。
最終料金を確認する
リクエスト ID、指示、課金単位を保存します。成功時に予約額を実際の料金で精算します。
名前ではなく用途でモデルを選ぶ
以下はテストの指針で、実測ランキングではありません。参照上限は MaxAPI のカタログ設定です。ルート固有の制限も確認し、同じ入力、出力設定、合格基準で比較してください。
| モデル | 参照画像の設定上限 | テストで比較する点 |
|---|---|---|
| Nanobanana Pro | 14 | 参照を使う制作：被写体の細部、構図、目的の解像度を比較。 |
| Gemini 3.1 Flash Image Preview | 14 | 複数の解像度：用途への対応と実用的な成果物の費用を比較。 |
| Gemini 3.1 Flash Lite Image | 3 | 1K の納品：掲載先で必要な細部が得られるか確認。 |
| Gemini 2.5 Flash Image | 3 | プリセットサイズ：4K 指定を前提にせず構図を評価。 |
| GPT Image 2 | 16 | 生成と編集：指示の反映、素材の受理、実寸を比較。 |
テストから本番運用へ
本番と同じルートで試す
最初の比較はモデル、ルート、パラメータを固定します。通常の入力だけでなく大きなファイルや例外もテストしてください。公開仕様がすべての上流チャネルの動作を保証するわけではありません。
制限と生成エラーを分ける
429 ではリクエスト頻度や同時実行数を下げ、間隔を空けて再試行します。無効な入力は先に修正してください。調査用の ID を保存し、API キーや機密素材を公開ログに残さないでください。
利用可能な結果と実費を記録
アカウントの利用・請求記録で最終結果と料金を確認します。HTTP の成功がタスク受付のみを示す場合もあります。公開前に生成内容と参照素材の利用権を確認してください。
確認済みの接続ケース
MaxAPI の公開カタログ、ゲートウェイ実装、ローカル回帰ケースで確認した接続情報です。共通処理の確認は各モデルのエンドツーエンドテストではなく、上流の現在の稼働状況や性能の報告でもありません。
複数キーでユーザー上限を共有
ローカル回帰テスト・合格- テスト条件
- 同一アカウントの 2 キーと少量のユーザー枠をメモリー内の制限器で使用。
- 確認した結果
- 両キーのリクエストが同じユーザー枠を消費し、超過を制限。大きいキー枠はユーザー枠を上書きせず、小さいキー枠も有効。
内容拒否と容量不足を区別
ローカル回帰テスト・合格- テスト条件
- 模擬した上流の内容拒否と 429／503／504 を生成エラー変換処理に入力。
- 確認した結果
- 内容拒否は 451、容量不足・一時停止・タイムアウトは別の公開コードに変換。このテストの互換形式 429／503 は Retry-After: 2 を含みます。
画像の予約残高を終端状態で精算・解除
ローカル回帰テスト・合格- テスト条件
- ローカルのテスト DB で同期画像の成功・失敗の予約残高処理を実行。
- 確認した結果
- 成功時は利用記録とともに予約を消費し、失敗時は生成課金なしで解除。受測コードの結果であり、実アカウントの現在残高ではありません。
よくある質問
このモデルを選ぶ用途は？
プロンプトによる下書きや構図の比較に使います。比較時はシード、寸法、ステップ数を固定し、採用前に実際の画像を確認してください。
この入口で特に注意する制限は？
参照編集やマスクは利用できません。各辺は 64〜2048 ピクセルです。出力は丸められる場合があります（64→128、720→768）。課金単位は縦横の積ではなく、512×512 の実測では 0.5 段階で 1.25 単位です。リクエストした出力 1 枚あたりの基本予約額 0.025 クレジットを実費で精算し、アカウント倍率を適用します。
route_mode を変えてもルートが変わらないのはなぜ？
ルートの優先順は API キーの route_modes リスト → リクエストで明示したルート → モデルの既定ルートです。キーに空でないリストがある場合、リクエストの route_mode より優先します。ルート比較の前にキー設定を確認してください。
各 API キーにユーザーの RPM 枠が付くのですか？
ユーザーの有効な RPM 上限は配下のキーで共有します。キーはより厳しく制限できますが、ユーザー上限を超えて許可できません。ユーザーが 200 RPM ならキーごとに 200 RPM ではありません。サービス全体の RPM と同時実行制御も適用されます。
このローカル回帰テストは実稼働の性能を証明しますか？
ローカルテストは模擬リクエスト・応答とテスト用ストレージを使い、有料モデルには接続しません。画像品質、実稼働の成功率・遅延、参照上限のエンドツーエンド動作を証明するものではなく、配図もテスト出力ではありません。
Z-Image Turbo のモデル ID は？
prunaai/z-image-turbo を使用します。エンドポイント形式はサンプルに従ってください。Gemini ネイティブの URL は短いモデル名を使用します。
掲載料金はすべてのアカウント・ルートで同じですか？
1 クレジット = 1 米ドル。以下はカタログの基本料金で、アカウントの見積額ではありません。最終料金はアカウント倍率と有効な課金設定で決まります。トークン単価は画像 1 枚の固定料金ではありません。
失敗したリクエストにも課金されますか？
MaxAPI の公開ルールでは失敗したリクエストに課金しません。処理中に残高が一時的に予約される場合があるため、最終的なタスク結果と請求記録を確認してください。
API キーでルートを利用できないのはなぜですか？
モデル、アカウント権限、API キーで許可されたルートによって利用可否が決まります。料金の掲載は利用権限の付与ではありません。
参照画像の検証に失敗するのはなぜですか？
テキストからの画像生成のみです。prompt と size、または width と height を指定します。各辺は 64〜2048 の整数とし、参照画像やマスクは指定できません。
4K は必ず 4096×4096 ですか？
いいえ。解像度の名称とピクセル寸法は同じではありません。64–2048 px per edge · default 1024x1024 · num_outputs default 1 レイアウトには実際の出力寸法を確認してください。
失敗やタイムアウトの直後に再送すべきですか？
まず制限、入力エラー、処理中のタスクを区別します。タスク ID がある場合は新たに生成する前に状態を確認し、再試行可能なエラーにだけ回数制限付きのバックオフを使ってください。