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 密钥。完整的密钥仅会显示一次，请妥善保存在您的服务器上，并在每次发起 API 请求时将其作为 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 时，请填写 nano-banana。
`callback_url`	string	否	用于接收任务完成或失败回调的公网 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 媒体链接替换为您自己公网可直接访问的 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 时请增加重试间隔（退避），并在状态为 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（id）在您的接收端做好幂等处理。

你的回调接口需支持接收 POST 请求及 JSON 格式的请求体（Content-Type: application/json）。

创建带有 Webhook 回调的任务

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 错误时将返回一个包含 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 日志。重试时请保持谨慎；重新发送创建请求可能会创建新的计费任务。

错误使用 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。请在代码中加入退避重试逻辑，避免高频轮询。

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

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