KovAPIKovAPI
POST https://kovapi.com/v1/images/generations

Google Nano Banana 2 Lite(Gemini 3.1 Flash Lite Image)による画像生成 API(非同期ジョブ)です。Nano Banana ファミリーで最も速く、最も安いモデルです。テキストからの生成は prompt だけで済み、編集は参照画像を image または images(URL、data:、base64)に入れるか /v1/images/edits を呼びます。送信するとすぐにジョブ id(HTTP 202)が返り、GET /v1/images/jobs/{id} をポーリングして画像を受け取ります。出力は 1K のみで、1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、21:9、4:1、1:4、8:1、1:8 の 14 種類の比率に対応します。2K / 4K を指定すると送信時に拒否され、課金されません。1 枚単位の課金で、失敗したリクエストは課金されません。

Playground で試す →

クイックスタート

3 ステップで動きます:ジョブを送信 → 結果を照会 → 画像リンクを受け取る。YOUR_API_KEY をご自身のキーに置き換えれば、下のコマンドはそのまま実行できます。

ステップ 1 · 送信(すぐにジョブ ID を返します。HTTP 202)
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2-lite", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "16:9", "resolution": "1K"}'
レスポンス(HTTP 202)
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281500,
  "model": "nano-banana-2-lite"
}
ステップ 2 · status が succeeded か failed になるまで 2〜3 秒ごとに照会
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
成功時のレスポンス
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281500,
  "model": "nano-banana-2-lite",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.jpg"}
  ],
  "usage": {"images": 1, "resolution": "1K", "model": "nano-banana-2-lite"}
}

ステップ 3 · data[0].url が画像(上流のオリジナル画像、JPEG 形式)です。保存期間は 7 日なので、長く使う場合はご自身のストレージにダウンロードしてください。

完全なサンプル(Python:送信 → 待機 → ローカルに保存)
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. 送信
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "nano-banana-2-lite",
    "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field",
    "size": "16:9",
    "resolution": "1K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 終わるまで 3 秒ごとに照会
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. 画像をダウンロード
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("nano-banana-2-lite.jpg", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["message"])

認証

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

コンソールで API Key を作成すると利用を開始できます。

リクエストボディ

パラメータ種別必須説明
model string はい モデル ID。ここでは nano-banana-2-lite です。
prompt string はい 画像を説明するテキストプロンプト。
size string いいえ 出力の画面比率。1:1、3:4、2:3、9:16、4:3、3:2、16:9 のいずれかの比率を渡すのがおすすめで、モデルはその比率でネイティブに描画するため被写体が切れません。ピクセル指定(1024x1024、1024x1536、1536x1024 など)も受け付けます。既定は 1:1(正方形)です。
resolution string いいえ 解像度:1K のみ(既定なので省略可)。resolution に 2K / 4K を指定すると、送信時に 400 unsupported_resolution を返し、課金されません。size にピクセルサイズを書く場合、Lite の 14 種類の 1K ネイティブサイズ(例:2928x352、1584x672)はすべて 1K として扱います。
thinking_level string いいえ 思考レベル。nano-banana-2-lite のみ対応:minimal(既定。省略可)または high。high は描く前に考えるため 3〜6 秒長くかかり、料金は同じです。複雑な構図、正確な数、文字の配置で試す価値があります。当社のテストでは画像の差ははっきりしませんでした。ほかのモデルで high を指定すると送信時に 400 を返し、課金しません。
n integer いいえ 常に 1:1 つのジョブで 1 枚を生成します。大きな値を指定しても 1 枚だけが返り、1 枚分だけ課金されます。複数枚ほしい場合は複数のジョブを同時に送信してください。
image string いいえ 画像から画像:参照画像を公開 URL、data: URI、生の base64 のいずれかで渡します。指定すると、人物や被写体を保ったままの本物の画像から画像として、選んだサイズ・比率で生成します。/v1/images/edits の呼び出しと同等です。
images array いいえ 複数の参照画像、最大 8 枚(それ以上送ると先頭の 8 枚だけを使います):文字列の配列、または {"image_url": "..."} オブジェクトの配列。各画像は公開 URL、data: URI、base64 のいずれかで、1 枚 16MB まで。指定すると画像から画像になり、/v1/images/edits と同じです。1 枚だけなら上の image フィールドも使えます。

リクエスト例

cURL
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://kovapi.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-2-lite", "prompt": "a serene ink-wash poster, lots of negative space", "size": "16:9", "resolution": "1K"}'
# 2) poll until status=succeeded
curl https://kovapi.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'

レスポンス

200 · JSON
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "nano-banana-2-lite"
}

料金

画像 1 枚ごとの課金で、料金は解像度のグレードだけで決まり、比率やテキストから画像 / 画像から画像の違いは関係ありません。送信時にグレードの料金を確保し、ジョブが失敗した場合は全額返金します。1 クレジット = $0.005。

グレード1 枚あたりのクレジット1 枚あたりの料金(USD)
1K2$0.01

1 つのジョブで生成されるのは常に 1 枚です。n に何を指定しても 1 枚が返り、1 枚分だけ課金されます。複数枚ほしい場合は複数のジョブを同時に送信してください(1 アカウントで同時に 50 枚まで生成できます)。

比率・解像度・出力サイズ

size に比率を指定します。resolution は省略できます(グレードは 1K のみ)。モデルは選んだ比率で直接描画し、上流のオリジナル画像を切り抜きも拡大・縮小もせずにお届けします。比率ごとのピクセルサイズは固定で、下の表のとおりです:

比率1K
1:11024x1024
16:91376x768
9:16768x1376
4:31200x896
3:4896x1200
3:21264x848
2:3848x1264
4:5928x1152
5:41152x928
21:91584x672
1:4512x2064
4:12064x512
1:8352x2928
8:12928x352

対応しているのは表の比率だけです(size にピクセルサイズを書いた場合は、差が 1.5% 以内のいちばん近い比率として扱います)。それ以外の比率はその場で失敗となり、料金はかかりません。描画してから切り抜くことはしません。

size にはピクセルサイズも書けます。表にあるサイズ(例:2928x352、1584x672)は 1K で描画し、それ以外のピクセルサイズは最も近い比率(差 1.5% 以内)の 1K ネイティブサイズで描画します。長辺が 1536 を超えるものは 2K / 4K とみなし、送信時に拒否します。resolution は 1K のみで、2K / 4K を指定すると送信時に 400 unsupported_resolution を返し、ジョブは作られず課金もされません。size を省略すると 1:1 の正方形になります。

画像から画像と参照画像

  • image(1 枚)または images(複数枚、最大 8 枚。それ以上送ると先頭の 8 枚だけを使います)を渡すと画像から画像になります。何をどう変えるかはプロンプトに書いてください。POST /v1/images/edits も同じパラメータで使えます。
  • 参照画像は公開された画像 URL(http / https)、data: URI、またはそのままの base64 で、1 枚 16MB まで、JPEG・PNG・WebP などの一般的な形式に対応します。
  • URL は画像そのものをダウンロードできる必要があります(Web ページ、ログインが必要な URL、直リンク禁止の URL は不可)。読み込めない参照画像は送信時に 400 と理由を返し、ジョブは作られず課金もされません。
  • 出力の比率は参照画像ではなく size で決まります。元の比率を保ちたい場合は size を元画像と同じ比率にしてください。
  • 参照画像は当サイトで代わりにホストし、7 日間保存します。
curl · 参照画像 2 枚で画像から画像
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2-lite", "prompt": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "1K"}'

ジョブの状態と返却フィールド

GET /v1/images/jobs/{id} は常に id、object(image.generation.job)、status、created(Unix 秒)、model を返し、そのほかのフィールドは状態によって付きます。

status意味追加されるフィールド
queued待機中queue_position(前にあるジョブの数)、eta_seconds(待ち時間の目安、秒)
processing生成中—
succeeded完了data[].url(画像リンク。当サイトの画像ホストで 7 日間保存)、usage.images(納品枚数)、usage.resolution(課金グレード)
failed失敗(送信時に確保した料金は全額返金済み)error.message、error.type、error.code

照会は 2〜3 秒ごとがおすすめです。1 アカウントで同時に生成できるのは 50 枚までで、それを超えるジョブは送信順に待機します。15 分待っても開始されないジョブは自動的に失敗となり、全額返金されます。ジョブの記録は 3 日間保存され、その後はジョブ ID で照会すると 404 になりますが、画像リンクは 7 日間有効です。ジョブは送信したアカウントからしか照会できません。

生成にかかる時間

送信から結果までの一般的な所要時間です(目安)。画像から画像はテキストから画像より数秒〜十数秒長くかかり、自動で再試行されたジョブは 1〜2 分かかることがあります。

グレード所要時間の目安
1K5–15 秒

エラーと返金

エラーはすべて {"error": {"message", "type", "code", "param"}} という同じ形式です。code で分岐してください。

送信時に返るエラー(ジョブは作られず、課金もされません)

HTTPcode原因対処
400missing_promptprompt が空prompt を入れる
400model_not_foundmodel の ID が誤っているか、現在利用できないID を確認(利用可能なモデルは /v1/models)
400invalid_request参照画像を読み込めない(リンク切れ、画像ではない、16MB 超など)。どの画像かと理由は message に記載画像の直リンクを使うか base64 で送る
401invalid_api_keyキーが誤っている、削除済み、または無効コンソールでキーを確認
402insufficient_quota残高がこのジョブの確保額に足りないチャージして再試行
429rate_limit_exceededこのキーに設定した 1 分あたりの上限を超えた頻度を下げるか、コンソールでキーの上限を上げる
503model_maintenanceモデルがメンテナンス中しばらくして再試行(ステータスページを参照)
503service_unavailable当サイト側の一時的なエラー(参照画像の保存失敗など)少し待って再試行

失敗したジョブ(受け付け後に status が failed で終了。確保した料金は全額返金)

状況表示される内容対処
プロンプトか参照画像が Google の安全審査を通らなかったerror.message に Content blocked などの審査メッセージプロンプトを書き換えるか参照画像を変える。そのまま再送信してもたいてい再び拒否されます
上流の一時的な障害やタイムアウト(先に自動で再試行し、それでも失敗したときだけ失敗を返します)error.code が upstream_error や upstream_timeout など。理由は message に記載そのまま再送信
15 分待っても開始されなかったerror.message にその旨しばらくして再送信

ポーリングの代わりに Webhook を使う

本番環境では、送信時に callback_url を付けることをおすすめします。ジョブが終わると(成功でも失敗でも)、照会エンドポイントと同じ JSON をその URL に image.completed または image.failed として POST し、送信元を検証できる署名ヘッダーも付けます。「設定 → Webhook」でアカウント全体の URL を設定することもできます。 Webhook ドキュメント

curl · callback_url
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2-lite", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'