Nano Banana API

使用 Seevio API Key 异步生成图片，支持文生图和图生图，每次请求生成一张。

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

模型功能

功能	支援的值
生成模式	`text-to-image, image-to-image`
輸出解析度	`input.resolution` — 此模型不接受该参数。
長寬比	`auto, 1:1, 9:16, 16:9, 3:4, 4:3, 3:2, 2:3, 5:4, 4:5, 21:9`
參考圖片	公网 HTTPS 的 PNG / JPEG / WebP 图片。图生图需要 1–10 张，每张不超过 10 MB；文生图必须为空数组。
提示詞	必填，非空提示词，最多 5000 个字符。
輸出格式	`png, jpg`

計費與額度

每张消耗 2 积分，支持的分辨率和格式均同价。受理时预扣，成功结算，失败退款。生成超过 30 分钟超时退款；refund_failed 表示退款尚在恢复处理中。

不支持请求幂等。每次有效 POST 都会新建任务并预扣。提交结果不明确时请查询返回的 taskId，重新 POST 可能产生额外任务。

身分驗證

請至控制台建立 API 金鑰。完整的金鑰內容僅會顯示一次，請妥善保存在您的伺服器端，並在每次發送請求時，將其作為 Bearer 權杖（Token）帶入標頭。

建立 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，請將此欄位設為 nano-banana。
`callback_url`	string	否	用於接收完成和失敗 POST 回呼的公開 HTTPS 端點。不支援私有網路與 localhost。範例: `https://example.com/webhooks/seevio`
`input`	object	是	生成設定。必須包含非空字串的 prompt 提示詞。

輸入參數

欄位	類型	必填	預設值	說明與限制
`input.prompt`	string	是	`—`	必填，非空提示词，最多 5000 个字符。範例: `A minimalist ceramic teapot on a stone pedestal, soft studio lighting`
`input.generation_type`	string	否	`text-to-image`	图生图时，将 generation_type 设为 image-to-image，并提供 image_urls，其他参数保持一致。支援的值 `text-to-image \| image-to-image`
`input.image_urls`	string[]	條件式必填	`[]`	公网 HTTPS 的 PNG / JPEG / WebP 图片。图生图需要 1–10 张，每张不超过 10 MB；文生图必须为空数组。範例: `["https://example.com/teapot.png"]`
`input.aspect_ratio`	string	否	`auto`	長寬比支援的值 `auto \| 1:1 \| 9:16 \| 16:9 \| 3:4 \| 4:3 \| 3:2 \| 2:3 \| 5:4 \| 4:5 \| 21:9` 範例: `1:1`
`input.resolution`	string	不支援	`—`	此模型不接受该参数。
`input.output_format`	string	否	`png`	支援的值 `png \| jpg` 範例: `png`

比例默认为 auto。拒绝未知字段，包括输出数量参数；每次固定生成一张。

快速上手

提交此最簡請求並保存回傳的 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",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

建立任務的回傳範例

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

文生圖呼叫範例

使用 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",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

圖生圖呼叫範例

图生图时，将 generation_type 设为 image-to-image，并提供 image_urls，其他参数保持一致。

請將範例中的 example.com 媒體 URL 替換為您自己可公開存取的 HTTPS 檔案。範例 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",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "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 則請放慢頻率（Backoff），並在狀態轉為 completed 或 failed 時停止。生產環境建議優先採用 Webhook。下方的每個程式碼範例僅執行單次查詢。

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

狀態	允许值与要求
queued	已接收並等待提交處理。
generating	圖片正在生成中。
completed	生成成功。請在過期前下載 data.results 中的圖片。
failed	生成失敗。請檢查 failed_reason 和 billing_status。

字段	類型	允许值与要求
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",
  "credits": 2,
  "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",
  "credits": 2,
  "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",
  "credits": 2,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed."
}

结果转存后 30 天内可获取结果链接，过期后 results 为空。

Webhook

在建立任務的請求中設定 callback_url，即可在任務完成或失敗時接收 JSON POST 請求。您的伺服器必須在 15 秒內回傳 2xx 回應。發送失敗的回呼會進行重試；請根據任務 ID 進行等冪（Idempotent）處理，以防重複發送。

您的回呼端點必須接受含有 JSON 請求主體的 POST 請求 (Content-Type: application/json)。

建立包含回呼設定的任務

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",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

回呼使用任務查詢回應的資料結構；已退款的失敗通知額外包含頂層 credits_refunded。使用 id 關聯任務，使用 status 判斷 completed 或 failed。通知可能重複，請按 id 和 status 做冪等處理。回呼不簽名，請透過驗證身分的查詢介面核實。通知失敗不會對成功任務退款。

任務完成：成功回呼的承載資料

created_at 為回呼事件建立時間，task_created_at 為任務建立時間，均為 Unix 秒級時間戳記。範例展示建議使用的欄位，實際回應可能包含額外欄位。

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana",
  "credits": 2,
  "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",
  "credits": 2,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed.",
  "task_created_at": 1789171200,
  "credits_refunded": 2
}

接收端範例

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 錯誤會包含一個 error 物件，內有 code（錯誤碼）和 message（錯誤訊息）。即使任務成功建立，後續仍可能生成失敗；請持續查詢任務狀態或處理失敗回呼。

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

HTTP	欄位	建議處理方法
400	`invalid_request`	請在重試前修正 JSON 格式、缺少的提示詞、無效的參數範圍或媒體 URL。
401	`invalid_api_key`	請檢查 Bearer 權杖（Token）以及 API 金鑰是否處於啟用狀態。
402	`insufficient_credits`	請儲值額度或降低任務成本。回應中可能會顯示所需的額度與目前可用額度。
403	`forbidden`	請檢查錯誤訊息中說明的帳戶權限限制。
404	`not_found`	請檢查任務 ID 是否正確，以及該金鑰是否屬於建立該任務的使用者。
429	`rate_limited`	請在 Retry-After 指定的間隔時間過後再重試。
500	`internal_error`	請檢查錯誤訊息和 API 日誌。請謹慎重試；重複送出建立請求可能會產生新的計費任務。

错误使用 error.code 和 error.message：400 invalid_request、401 invalid_api_key、402 insufficient_credits、403 forbidden、404 not_found、429 rate_limited、500 internal_error。上游余额不足不会作为用户 402 返回。

速率限制

建立任務：預設情況下，每個 API 金鑰每分鐘最多允許 100 次請求。目前不提供自訂速率限制。

查詢任務：預設情況下，每個 API 金鑰每分鐘最多允許 120 次請求。查詢請求與任務建立請求為分開計算。

圖片與影片的建立請求共用同一個 API Key 的速率限制額度。

回傳 HTTP 429 時，建立任務會包含 Retry-After: 60，查詢任務會包含 Retry-After: 5。請使用退避演算法（Backoff），避免過於頻繁地進行輪詢。

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

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