Nano Banana 2 API

Generate one image asynchronously per request. Supports text-to-image and image-to-image generation with your Seevio API key.

POST https://api.seevio.ai/v1/images/generations

対応機能

機能	対応している値
生成モード	`text-to-image, image-to-image`
出力解像度	`1K, 2K, 4K`
アスペクト比	`auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9, 4:1, 1:4, 8:1, 1:8`
参照画像	Public HTTPS PNG / JPEG / WebP URLs. Image-to-image requires 1–14 images, each up to 30 MB. Text-to-image requires an empty array.
プロンプト	Required non-empty prompt, up to 20000 characters.
出力形式	`png, jpg`

料金とクレジット

Each image costs 4 credits, including all supported resolutions and formats. Credits are reserved on acceptance, settled on success and refunded on failure. Generation times out after 30 minutes; refund_failed means refund recovery is pending.

Request idempotency is not supported. Each valid POST creates a new billable task. If a submission outcome is uncertain, query the returned taskId; retrying POST can create another task.

認証

ダッシュボードでAPIキーを作成してください。APIキーの全体が表示されるのは作成時の1回のみです。キーは安全なサーバー上で管理し、すべてのリクエストのヘッダーに Bearer トークンとして含めて送信してください。

APIキーを作成 APIダッシュボード

ベースURL

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

これらのサンプルコードを実行する前に、環境変数 SEEVIO_API_KEY を設定してください。JavaScriptのサンプルはサーバー上の Node.js で、Pythonのサンプルは requests ライブラリを使用して実行します。

リクエストボディ

フィールド	データ型	必須	説明と制約条件
`model`	string	はい	モデルID。Nano Banana 2を使用するには、このフィールドをnano-banana-2に設定してください。
`callback_url`	string	いいえ	タスク完了時または失敗時に POST コールバックを受け取るための、一般公開されている HTTPS エンドポイント。プライベートネットワークや localhost は指定できません。例: `https://example.com/webhooks/seevio`
`input`	object	はい	生成の設定。空でないプロンプト（prompt）を含める必要があります。

入力パラメータ

フィールド	データ型	必須	デフォルト値	説明と制約条件
`input.prompt`	string	はい	`—`	Required non-empty prompt, up to 20000 characters. 例: `A minimalist ceramic teapot on a stone pedestal, soft studio lighting`
`input.generation_type`	string	いいえ	`text-to-image`	For image editing, set generation_type to image-to-image and provide image_urls. All other parameters use the same contract. 対応している値 `text-to-image \| image-to-image`
`input.image_urls`	string[]	条件付き	`[]`	Public HTTPS PNG / JPEG / WebP URLs. Image-to-image requires 1–14 images, each up to 30 MB. Text-to-image requires an empty array. 例: `["https://example.com/teapot.png"]`
`input.aspect_ratio`	string	いいえ	`auto`	アスペクト比対応している値 `auto \| 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 3:2 \| 2:3 \| 5:4 \| 4:5 \| 21:9 \| 4:1 \| 1:4 \| 8:1 \| 1:8` 例: `1:1`
`input.resolution`	string	いいえ	`2K`	ここに記載されているサポート対象の出力解像度のいずれかを使用してください。対応している値 `1K \| 2K \| 4K` 例: `2K`
`input.output_format`	string	いいえ	`png`	対応している値 `png \| jpg` 例: `png`

Aspect ratio defaults to auto. Unknown fields, including output quantity, are rejected. Each request generates exactly one image.

クイックスタート

この最小限のリクエストを送信し、返された taskId を保存した上で、後述のタスクステータス確認の例を実行してください。作成レスポンスに含まれる credits の値は、確保（仮売上）されたクレジット量を示しています。

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

タスク作成時のレスポンス例

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 4
}

テキストから画像を生成

Generate one image asynchronously per request. Supports text-to-image and image-to-image generation with your Seevio API key.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

画像から画像を生成

For image editing, set generation_type to image-to-image and provide image_urls. All other parameters use the same contract.

example.com のメディアURLは、ご自身でホストしている公開済みの HTTPS ファイルのURLに置き換えてください。サンプルのURLはリクエストの構造を示すためのものであり、ダウンロード可能なアセットではありません。

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

タスクのステータス確認

GET https://api.seevio.ai/v1/tasks/{taskId}

サンプルのIDを、作成時に返された taskId に置き換えてください。ステータス確認は、そのAPIキーを所有するユーザーのタスクのみ可能です。権限がない、または存在しないIDの場合は HTTP 404 が返されます。

最初は10〜20秒間隔でポーリングを開始し、HTTP 429（レートリミット）が発生した場合は間隔を空け、ステータスが completed または failed になったら終了します。本番環境ではウェブフックの使用を推奨します。以下の各コード例は、1回のステータス確認リクエストを行うものです。

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

ステータス	Allowed values and requirements
queued	受け付けられ、処理待ちの状態です。
generating	画像を生成中です。
completed	生成成功（最終状態）。有効期限が切れる前に data.results から画像をダウンロードしてください。
failed	生成失敗（最終状態）。failed_reason と billing_status を確認してください。

Field	データ型	Allowed values and requirements
id	string	タスク識別子。作成時のレスポンスに含まれる taskId と同一です。
created_at	number	Unixタイムスタンプ（秒）で表されるタスク作成日時。
model	string	このタスクに使用された公開モデルのID。
billing_status	string	reserved（仮確保）、charged（決済完了）、refunded（返金済み）、または refund_failed（返金失敗）。
credits	number	このタスクのために仮確保されたクレジット。返金された後もこの値は保持されます。実際の課金結果を判断するには billing_status を参照してください。
failed_reason	string \| null	タスクが失敗した場合のエラー理由。それ以外は null。ステータス確認時にタスクが失敗している場合、レスポンスに data は含まれません。
data	object	タスクが失敗していない場合に返されます。出力結果と処理の詳細が含まれます。
data.results	string[]	画像 URL の配列。完了前および期限切れ後は空です。
data.image_expires_at	string \| null	画像の有効期限（ISO 8601）。未確定の場合は null。
data.processing_time	number \| null	プロバイダー側での処理時間（秒）。取得できない場合は null。

待機中

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

完了

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

失敗

クエリのレスポンスとしてstatus=failedが返された場合は、画像生成が正常に終了しなかったことを意味します。失敗の理由はfailed_reasonで、返金結果はbilling_statusで確認できます。この例では、refundedとなっておりクレジットが返却されたことを示しています。creditsには最初に確保された額がそのまま表示され、レスポンスにdataは含まれません。

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed."
}

Result links are provided for 30 days after storage. After expiry, results is empty.

ウェブフック

作成リクエスト時に callback_url を設定すると、タスクが完了または失敗した際、JSONデータが POST リクエストで送信されます。受信側は15秒以内に 2xx レスポンスを返してください。配信に失敗した場合は再試行されます。同一のタスクIDで重複してコールバックを受信することがあるため、冪等（べきとう）な処理を行ってください。

コールバックエンドポイントは、JSON形式のリクエストボディ（Content-Type: application/json）を含むPOSTリクエストを受け付ける必要があります。

コールバックを指定してタスクを作成

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Callbacks use the task query response structure; refunded failure notifications also include top-level credits_refunded. Use id to identify the task and status to distinguish completed from failed. Notifications may repeat: process them idempotently by id and status. Callbacks are unsigned; verify the task with the authenticated query endpoint. Delivery failure does not refund a successful task.

タスク完了：処理成功時のコールバックペイロード

created_at はイベント作成時刻、task_created_at はタスク作成時刻で、どちらも Unix 秒です。例では推奨フィールドを示しています。応答には追加フィールドが含まれる場合があります。

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

タスク失敗：処理失敗時のコールバックペイロード

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed.",
  "task_created_at": 1789171200,
  "credits_refunded": 4
}

レシーバーの実装例

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

このNext.jsのサンプルコードは、JSON形式のコールバックボディを読み込み、成功したタスクと失敗したタスクを直接処理します。実際のアプリケーション開発では、永続化処理やタスクIDの重複排除を追加してください。また、時間のかかる処理はキューに登録してから、コールバックへの応答を返すようにしてください。

エラー

HTTPエラーは、code と message を含む error オブジェクトを返します。正常に受け付けられたタスクであっても後から失敗することがあるため、タスクのステータスを確認するか、失敗時のコールバックを適切に処理してください。

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

HTTP	フィールド	対処方法
400	`invalid_request`	JSONの構文、プロンプトの有無、パラメータの範囲、またはメディアURLに問題があります。修正して再試行してください。
401	`invalid_api_key`	Bearer トークンが正しいか、およびAPIキーが有効化されているかを確認してください。
402	`insufficient_credits`	クレジットを追加するか、タスクの消費想定を減らしてください。レスポンスには、必要なクレジット数と現在の保有クレジット数が含まれる場合があります。
403	`forbidden`	エラーメッセージに記載されているアカウントレベルの制限事項を確認してください。
404	`not_found`	タスクIDが正しいか、およびそのキーがタスクの作成者と一致しているかを確認してください。
429	`rate_limited`	Retry-After ヘッダーに示された秒数が経過した後に再試行してください。
500	`internal_error`	エラーメッセージとAPIログを確認してください。注意深く再試行してください。作成リクエストを再送信すると、新たに課金対象となるタスクが作成される可能性があります。

Errors use error.code and error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Insufficient provider balance is not a customer 402 error.

レートリミット

タスクの作成：デフォルトでは、APIキー1つにつき1分あたり最大100回のリクエストが可能です。現在、カスタムレート制限の設定はご利用いただけません。

タスクの照会：デフォルトでは、APIキー1つにつき1分あたり最大120回のリクエストが可能です。照会リクエストとタスク作成リクエストは別々にカウントされます。

Image and video creation requests share the same API key rate limit.

HTTP 429 レスポンスの Retry-After は、タスク作成時には 60、タスク確認時には 5 が設定されます。エクスポネンシャルバックオフなどの仕組みを導入し、必要以上の頻度でポーリングを行わないようにしてください。

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}