Z Image Turbo は Novita AI 上で2つの非同期エンドポイントを通じて利用できます。標準のテキスト→画像生成には POST https://api.novita.ai/v3/async/z-image-turbo、LoRAスタイルモデルを用いた生成には POST https://api.novita.ai/v3/async/z-image-turbo-lora を使用します。どちらも Novita AI の標準的な非同期パターンに従います——リクエストを送信して task_id を受け取り、GET /v3/async/task-result をポーリングして画像の準備が整うのを待ちます。このガイドでは、両方のエンドポイントを最初のリクエストからポーリングループ、LoRAの使い方、本番コードを書く前に必要なパラメータリファレンスまで、一貫してカバーします。
このクイックスタートを使うべきケース
エラーハンドリングやバッチ処理、本番ロジックを追加する前に、Z Image Turbo の確認済み動作リクエストが必要な場合にこのガイドを使用してください。
Z Image Turbo は高速なスループットを目的に設計されています。以下のワークフローに適しています。
- 速度が品質よりも重要——プロトタイプパイプライン、バッチプレビュー生成、レイテンシが厳しい制約となるリアルタイムアプリケーション。
- 完全な
txt2imgパラメータセットを設定せずにLoRAベースのスタイル変換を利用したい場合。専用のLoRAエンドポイントはloras配列を受け入れ、残りは自動で処理します。 - 最小限のリクエストボディで、プロンプトを入力し画像を出力するシンプルなインターフェースが必要な場合。
Z Image Turbo は、完全な Stable Diffusion 設定（steps, guidance_scale, sampler_name, negative_prompt, hires_fix, リファイナーモデルなど）が必要な場合には適していません。そのような制御が必要な場合は、標準の POST /v3/async/txt2img エンドポイントを使用してください。
このガイドは Novita AI ホスト型 API 経路のみを対象としています。セルフホスティングやファインチューニングについては扱いません。
ステップ1: Novita APIキーを取得する
Novita AI アカウントを作成し、APIキー管理に移動します。キーを生成してエクスポートします。
export NOVITA_API_KEY="your_api_key_here"
キーはバージョン管理、クライアントサイドバンドル、Dockerイメージレイヤーに含めないでください。
ステップ2: エンドポイントを確認する
Novita AI 上の Z Image Turbo は、2つの個別サブミッションエンドポイントと1つの共通結果エンドポイントを使用します。
| 基本 T2I | LoRA T2I | |
|---|---|---|
| サブミッション | POST https://api.novita.ai/v3/async/z-image-turbo |
POST https://api.novita.ai/v3/async/z-image-turbo-lora |
| 結果ポーリング | GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
| APIリファレンス | Z Image Turbo ドキュメント | Z Image Turbo LoRA ドキュメント |
どちらのサブミッションエンドポイントも task_id のみを返します。結果ポーリングエンドポイントは両方で同一です——ポーリングループが一方で動作すれば、もう一方でもそのまま使えます。
ステップ3: 最初のリクエストを送信する
基本エンドポイントには prompt と size が必要です。オプションパラメータを追加する前に、まずここから始めてください。
curl -s -X POST https://api.novita.ai/v3/async/z-image-turbo \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A futuristic city skyline at dusk, neon lights, photorealistic, ultra-detailed",
"size": "1024*1024"
}'
成功した200応答は以下を返します。
{
"task_id": "abc123..."
}
task_id を保存してください。サブミッション時にはこれ以外は返されません——生成は非同期で実行されます。
基本エンドポイントでは2つのオプションパラメータが利用可能です。
seed（整数）：再現可能な出力のための固定値。同じプロンプトとシードの組み合わせで一貫した結果が得られます。enable_base64_output（ブール値）：trueの場合、結果にはホスト型URLの代わりに画像がbase64エンコードされた文字列として含まれます。
ステップ4: 結果をポーリングする
タスク結果エンドポイントに task_id をクエリパラメータとしてGETリクエストを送信します。
curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
-H "Authorization: Bearer $NOVITA_API_KEY"
完了したタスクは以下を返します。
{
"task": {
"task_id": "abc123...",
"status": "TASK_STATUS_SUCCEED",
"progress_percent": 100,
"eta": 0
},
"images": [
{
"image_url": "https://...",
"image_url_ttl": 3600,
"image_type": "png"
}
]
}
task.status が TASK_STATUS_SUCCEED または TASK_STATUS_FAILED になるまで、1〜2秒ごとにポーリングしてください。task.eta フィールドは、タスクがまだキューにある場合の推定残り秒数を示します。
image_url_ttl はURLの有効期間（秒単位）です。TTLが切れる前に画像をダウンロードして保存してください——ホスト型URLは永続的ではありません。
ステップ5: 料金、制限、一般的なエラーを確認する
Z Image Turbo の現在の料金は、Novita AI 料金ページ と Z Image Turbo モデルページ に掲載されています。料金は変更される可能性があるため、コスト見積もりを立てる前にレートを確認してください。
一般的なエラー:
| エラー | 原因 | 修正方法 |
|---|---|---|
| 401 Unauthorized | APIキーがない、または不正 | ヘッダーが Authorization: Bearer <key> であることを確認 |
| 400 Bad Request | リクエストボディが無効 | prompt と size が文字列であること、seed が指定される場合は整数であることを確認 |
TASK_STATUS_FAILED |
生成が拒否またはエラー | 結果レスポンスの task.reason を読み、具体的な失敗メッセージを確認 |
| 画像URLが403を返す、または期限切れ | TTL経過後にURLにアクセス | image_url_ttl 秒が経過する前に画像をダウンロードして保存 |
Python サンプル
フルワークフロー——サブミット、ポーリング、画像URLを返す:
import os
import time
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def generate_image(prompt: str, size: str = "1024*1024", seed: int = None) -> str:
payload = {"prompt": prompt, "size": size}
if seed is not None:
payload["seed"] = seed
resp = requests.post(
"https://api.novita.ai/v3/async/z-image-turbo",
json=payload,
headers=HEADERS,
)
resp.raise_for_status()
task_id = resp.json()["task_id"]
while True:
result = requests.get(
f"https://api.novita.ai/v3/async/task-result?task_id={task_id}",
headers=HEADERS,
)
result.raise_for_status()
data = result.json()
status = data["task"]["status"]
if status == "TASK_STATUS_SUCCEED":
return data["images"][0]["image_url"]
if status == "TASK_STATUS_FAILED":
raise RuntimeError(f"Generation failed: {data['task'].get('reason', 'unknown')}")
time.sleep(1)
if __name__ == "__main__":
url = generate_image(
"A futuristic city skyline at dusk, neon lights, photorealistic",
size="1024*1024",
seed=42,
)
print(url)
LoRA 生成
LoRA エンドポイントはリクエストに loras 配列を追加します。各エントリには path（Novita AI モデルハブからのLoRAモデル識別子）と scale（影響の重み）が必要です。
curl -s -X POST https://api.novita.ai/v3/async/z-image-turbo-lora \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "a portrait in anime style, soft lighting, detailed face",
"size": "768*1024",
"loras": [
{
"path": "<lora-model-path>",
"scale": 0.8
}
],
"seed": 42
}'
<lora-model-path> は Novita AI モデルハブ から確認したパスに置き換えてください。path の形式と互換性のあるLoRAモデルは Z Image Turbo LoRA APIリファレンス に記載されています——モデルパスは推測せず、確認済みのハブエントリのみを使用して、解決不能なパスによる TASK_STATUS_FAILED を避けてください。
LoRA結果のポーリングは基本エンドポイントとまったく同じです。
同じLoRAワークフローのPython版:
import os
import time
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def generate_with_lora(
prompt: str,
lora_path: str,
lora_scale: float = 0.8,
size: str = "1024*1024",
seed: int = None,
) -> str:
payload = {
"prompt": prompt,
"size": size,
"loras": [{"path": lora_path, "scale": lora_scale}],
}
if seed is not None:
payload["seed"] = seed
resp = requests.post(
"https://api.novita.ai/v3/async/z-image-turbo-lora",
json=payload,
headers=HEADERS,
)
resp.raise_for_status()
task_id = resp.json()["task_id"]
while True:
result = requests.get(
f"https://api.novita.ai/v3/async/task-result?task_id={task_id}",
headers=HEADERS,
)
result.raise_for_status()
data = result.json()
status = data["task"]["status"]
if status == "TASK_STATUS_SUCCEED":
return data["images"][0]["image_url"]
if status == "TASK_STATUS_FAILED":
raise RuntimeError(f"Generation failed: {data['task'].get('reason', 'unknown')}")
time.sleep(1)
LoRA スケールのガイダンス
scale はLoRAスタイルが適用される強さを制御します。0.8 が適切なデフォルト値です。プロンプトの詳細がLoRAスタイルによって上書きされすぎる場合は低い値（0.4〜0.6）、スタイルが十分に現れていない場合は高い値（0.9〜1.0）を試してください。複数のLoRAを高いスケール値で重ねると、一貫性が損なわれる可能性があります——最初は各LoRAを個別にテストしてください。
一部のLoRAモデルは、スタイルを有効にするためにプロンプト内にトリガーワードが必要です。テストする前に、Novita AI ハブのモデル一覧で必要なキーワードを確認してください。
主要パラメータ
基本エンドポイント (/v3/async/z-image-turbo)
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
prompt |
文字列 | はい | 対象画像のテキスト記述 |
size |
文字列 | はい | "幅*高さ" 形式の出力寸法（例: "1024*1024"） |
seed |
整数 | いいえ | 再現性のための固定値; 同じシード + プロンプトで一貫した出力 |
enable_base64_output |
boolean | いいえ | true の場合、画像をホスト型URLではなくbase64文字列で返す |
LoRA エンドポイント (/v3/async/z-image-turbo-lora)
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
prompt |
文字列 | はい | テキストプロンプト; 必要な場合はLoRAトリガーワードを含める |
size |
文字列 | はい | "幅*高さ" 形式の出力寸法 |
loras |
配列 | はい | 1つ以上のLoRAオブジェクト |
loras[].path |
文字列 | はい | Novita AI モデルハブからのLoRAモデルパス |
loras[].scale |
数値 | はい | 影響の重み; 0.8 が一般的な開始点 |
seed |
整数 | いいえ | 再現性のための固定値 |
enable_base64_output は現在のドキュメントではLoRAエンドポイントに記載されていません。画像取得にはポーリングの結果URLを使用してください。
トラブルシューティング
タスクが予想以上に TASK_STATUS_PENDING のままになる。 キューの深さはプラットフォームの負荷によって異なります。ポーリング応答の task.eta フィールドは推定待機時間（秒）を返します。レイテンシに敏感な本番パスでは、複数のタスクIDにわたってリクエストを送信し、並行してポーリングすることを検討してください。
TASK_STATUS_FAILED が即座に、または短い待機後に発生する。 結果の task.reason を読んでください。一般的な原因: 無効な size 文字列形式、解決できないLoRA path、コンテンツフィルタリングをトリガーしたプロンプト。最小リクエストで切り分けてください。
画像URLが403を返す。 URLの有効期間は image_url_ttl（秒）で制御されます。その期間を過ぎてURLを要求するとアクセスが拒否されます。ポーリングが成功したらすぐに画像データを取得して保存してください。
LoRAスタイルが出力に現れない。 scale を1.0に向けて増やしてみてください。LoRAにトリガーワードが必要ないか確認し、必要な場合はプロンプトに追加してください。
LoRAエンドポイントで 400 Bad Request が発生する。 loras フィールドが配列（オブジェクトではない）であること、および各エントリに path と scale の両方が存在することを確認してください。
FAQ
Z Image Turbo は何のために設計されていますか？
Z Image Turbo は高速なテキスト→画像生成に最適化されています。プレビュー生成、バッチパイプライン、LoRAベースのスタイリングがSDXLワークフローの細かい制御よりも重要なユースケースに適しています。
Z Image Turbo はどのサイズをサポートしていますか？
size パラメータは "幅*高さ" 文字列を受け取ります。確認済みのサポート値は Z Image Turbo モデルページ に記載されています。正方形（1024*1024）と縦長（768*1024）のフォーマットは、他のNovita AI画像エンドポイントと同様に安全な開始点です。
1つのリクエストで複数のLoRAを適用できますか？
loras 配列は複数のエントリを受け入れます。実際には、高い scale 値でLoRAを重ねると出力品質が低下することがよくあります。最初は各LoRAを個別にテストし、その後控えめなスケール値（エントリあたり0.5〜0.7）で組み合わせてください。
互換性のあるLoRAパスはどこで見つけられますか？
Novita AI モデルハブ を閲覧し、Z Image Turbo LoRA APIリファレンス で確認済みのパス形式を確認してください。外部ソースのパスは、Novitaプラットフォームで解決できることを確認せずに使用しないでください。
negative_prompt はサポートされていますか？
現在のドキュメントでは、どちらの Z Image Turbo エンドポイントにも negative_prompt パラメータは記載されていません。被写体やスタイルを除外する必要がある場合は、プロンプトで肯定的な表現を使用して不要な内容を避けるか、negative_prompt を直接サポートする標準の txt2img エンドポイントを評価してください。
1回の呼び出しで複数の画像を生成できますか？
現在のドキュメントでは、どちらの Z Image Turbo エンドポイントにも image_num パラメータは記載されていません。バッチ生成の場合は、複数のリクエストを並行して送信し、それらの task_id 値を同時にポーリングしてください——各リクエストは独立しています。
Z Image Turbo は標準の txt2img エンドポイントとどのように比較されますか？
標準の txt2img エンドポイントは、steps、guidance_scale、sampler、negative_prompt、Hi-Res Fix、リファイナーモデルなど、幅広い設定面をサポートします。Z Image Turbo はその構成可能性を速度とシンプルなリクエスト形式と引き換えにしています。パラメータ制御が重要な場合は txt2img を、スループットまたはシンプルさが優先される場合は Z Image Turbo を使用してください。
