把想法，
写进你的产品。

01 / 准备接入

请求鉴权

API 请求统一使用 https://i.banan.xin/api/v1 作为基础地址。联系商务获取 API Key，并仅在自己的服务端设置密钥。

export BANANA_API_KEY='YOUR_API_KEY'

Authorization必填 · 请求头

使用 Bearer YOUR_API_KEY。提交生成、查询任务与查询用量均需要鉴权；任务只能由提交时使用的密钥查询。旧版 X-API-Key 请求头继续兼容，请选择一种方式发送。

Content-Type提交生成

设置为 application/json，请求体以 JSON 发送。

Idempotency-Key可选 · 强烈建议提供

同一次生成使用固定且唯一的键，长度 1–128 个可见 ASCII 字符。网络断连或超时重试时必须复用原键与原内容；同步、异步两种方式共用幂等规则，返回同一 task_id，不会重复生成或扣次数。同键不同内容返回 409。

API Key 仅保存在服务端，不要放进网页、小程序或公开代码仓库。可选签名接入需另行确认；基础示例不发送签名请求头。

02 / 提交生成

图像生成接口

所有开放平台任务从受理起最多 180 秒，包含排队、生成和保存结果。同步成功返回图片地址；任务超时返回 HTTP 504、status: failed、error: generation_timeout，不扣次数。同步等待名额已满，或当前请求等待结束但任务尚未到期时，返回 HTTP 202 和任务 ID，继续查询原任务。客户端请求超时建议设为 210 秒，为上传和响应传输留出余量。

180 秒是任务处理期限，不是网络响应送达保证。异步接口没有主动回调，业务方应每 3 秒查询；实际获知结果还取决于轮询间隔和网络延迟。连接断开或网络超时不代表任务失败，请使用原任务 ID 或原幂等键确认状态。

业务方建议在取得任务 ID 后保留最多 210 秒等待窗口（平台处理 180 秒，加轮询和网络余量），每 3 秒查询一次、单次查询超时 15 秒。若业务总计时还包含原图下载、编码和上传，可先设置为 240 秒，并根据实际耗时调整；这不会延长平台的 180 秒任务期限。收到明确失败立即结束，不必等满等待窗口。客户端超时但尚未取得终态时，应反馈“状态待确认”，切备用前核实原任务，避免重复生成。

异步调用提交后立即取得 task_id，再查询生成结果。两种调用方式使用相同参数与额度：每个成功生成并保存结果的任务扣除 1 次总额度；失败不扣，查询不扣。次数长期有效，不按天或按月重置，用完可续购。

promptstring · 必填

非空的文字提示词，去除首尾空白后最多 8,000 个字符。

reference_imagesstring[] · 可选

最多 9 张 PNG、JPEG、GIF 或 WebP 图片的 Base64 字符串数组，也可使用 data URL。每张解码后不超过 16 MiB，全部图片解码后合计不超过 32 MiB。不接受图片 URL 或本地路径。提供参考图时按图生图处理；省略则为文生图。

reference_imagestring · 旧版兼容

兼容原有的单张 Base64 / data URL 参考图，单张限制相同。不能与 reference_images 同时传入。

JSON 请求体默认上限为 50 MiB，包含 Base64 编码与提示词；Base64 编码会增加传输大小。请同时满足请求体与解码后的图片大小限制。

curl --max-time 210 --request POST 'https://i.banan.xin/api/v1/open/generate/sync' \
  --header "Authorization: Bearer ${BANANA_API_KEY}" \
  --header 'Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"prompt":"一张极简香蕉主题海报，奶油白背景，黑色线条，黄色点缀"}'

切换调用模式和语言后可复制对应示例。JavaScript 使用 Node.js 内置 HTTPS 模块；收到 202 后按原任务 ID 查询，不重新提交。请替换并保存幂等键；查询超时后用原任务 ID 续查，提交断连或超时后用原幂等键与原内容重试。

{
  "prompt": "保留参考图主体，将背景改为奶油白色",
  "reference_images": ["YOUR_FIRST_IMAGE_BASE64", "YOUR_SECOND_IMAGE_BASE64"]
}

03 / 取得结果

从任务 ID，到结果。

同步成功时返回 HTTP 200，根级字段 image_url 是已保存的图片地址。保留 task_id 用于后续查询，request_id 用于排查本次 HTTP 请求。

{
  "success": true,
  "task_id": "00000000-0000-4000-8000-000000000002",
  "status": "success",
  "image_url": "https://example.com/generated/result.png",
  "image_base64": null,
  "request_id": "00000000-0000-4000-8000-000000000001",
  "reused": false
}

同步返回 HTTP 202 表示本次等待未取得终态，响应头 Retry-After: 3 建议 3 秒后查询。reason: wait_timeout 表示当前请求等待结束；reason: sync_capacity_busy 表示同步等待名额已满。两种情况都使用已有 task_id 续查，不会重新开始任务的 180 秒期限。

{
  "success": true,
  "task_id": "00000000-0000-4000-8000-000000000002",
  "status": "generating",
  "reason": "wait_timeout",
  "query_url": "/api/v1/open/generate/00000000-0000-4000-8000-000000000002",
  "request_id": "00000000-0000-4000-8000-000000000001",
  "reused": false
}

异步提交受理成功时返回 HTTP 202；success: true 仅表示任务已受理，完成与否以 status 为准。相同幂等键重试时返回原任务并标记 reused: true，原任务可能已完成或失败。

{
  "success": true,
  "task_id": "00000000-0000-4000-8000-000000000002",
  "status": "queued",
  "request_id": "00000000-0000-4000-8000-000000000001",
  "reused": false
}

使用提交时的 API Key 查询。响应中的 status 为 queued、generating、success 或 failed。success: true 仅表示查询成功；任务完成与否以 status 为准。

curl 'https://i.banan.xin/api/v1/open/generate/YOUR_TASK_ID' \
  --header "Authorization: Bearer ${BANANA_API_KEY}"

{
  "success": true,
  "task_id": "00000000-0000-4000-8000-000000000002",
  "status": "generating"
}

{
  "success": true,
  "task_id": "00000000-0000-4000-8000-000000000002",
  "status": "success",
  "image_url": "https://example.com/generated/result.png",
  "image_base64": null
}

{
  "success": true,
  "task_id": "00000000-0000-4000-8000-000000000002",
  "status": "failed",
  "error": "generation_failed",
  "message": "Generation failed"
}

鉴权通过且任务存在时，查询返回 HTTP 200，success: true 只表示查询成功，包括 status: failed 的任务。成功结果返回 OSS 持久图片地址 image_url，image_base64 为 null；失败读取 error 和 message。已失败任务使用原幂等键仍返回原失败；确认要重新生成时才使用新键。

04 / 查看用量

密钥与额度

返回累计总次数 quota_total、已成功消耗次数 quota_used、处理中占用 pending_calls 和可用次数 remaining_calls。可用次数 = 总次数 − 已用次数 − 处理中占用。任务排队时先占用名额，失败后释放，成功后转为已用；跨天不会释放。这里的 status 是密钥状态；额度用尽后仍可查询任务和用量。

curl 'https://i.banan.xin/api/v1/open/status' \
  --header "Authorization: Bearer ${BANANA_API_KEY}"

{
  "success": true,
  "data": {
    "key_name": "example-enterprise",
    "quota_mode": "total",
    "quota_total": 1000,
    "quota_used": 120,
    "pending_calls": 2,
    "remaining_calls": 878,
    "status": "active"
  }
}

05 / 服务检查

健康检查

用于确认开放 API 服务可响应。返回健康状态不代表模型渠道可用，也不代表一次图像生成已经成功。

curl 'https://i.banan.xin/api/v1/open/health'

06 / 异常处理

知道发生了什么。

每次提交和查询都必须检查 HTTP 状态及任务状态，不能只处理首次提交的错误。status: success 或 status: failed 均须退出轮询；只有 queued / generating 才继续等待。不要只判断顶层 success。

从受理起满 180 秒仍未完成，任务终态为 failed、错误码为 generation_timeout：异步查询返回 HTTP 200，同步返回 HTTP 504。业务方应停止轮询并可切备用；平台释放占用、不扣次数，迟到结果不会把任务改回成功。同一幂等键始终复用原任务。平台不保证撤销已经发给上游的请求。

网络异常、非 JSON 网关错误或客户端等待超时并不等同于任务终态失败。业务方应结束当前前台等待、反馈“状态待确认”并保留任务 ID 和幂等键，避免无限阻塞；确认原任务失败前，切备用需考虑重复生成。

400参数错误

missing_prompt、prompt_too_long、invalid_reference_image、invalid_idempotency_key 等：检查提示词、参考图和请求头。参考图字段不可同时传入；启用可选签名后，缺少、过期或格式错误的时间戳也会返回 400。

401鉴权失败

missing_api_key、invalid_api_key 或 invalid_signature：停止当前自动重试或轮询，检查密钥与签名配置。密钥禁用也返回 invalid_api_key；查询鉴权失败不代表原任务已取消。

404任务不存在

task_not_found：任务 ID 不存在，或该任务不属于当前 API Key；请使用提交任务时的密钥查询。

409幂等键冲突

idempotency_conflict：同一 API Key 的相同幂等键已用于不同请求内容。请确认是在重试原请求，还是创建新任务。

413请求体过大

JSON 请求体超过默认 50 MiB 上限；请缩小参考图，同时满足单张 16 MiB、合计 32 MiB 的解码后限制。

429调用受限

可用次数不足时返回 quota_exhausted，本次没有新建任务，应退出提交重试。首次提交明确被拒绝时可切备用；若之前提交曾断连、受理状态未知，应先核实原任务。处理中任务会暂占额度；任务失败后释放，成功后转为已用。额度不足时等待成功任务结束不会恢复次数，需联系商务续购。提交或查询过于频繁也会返回 429，应按 Retry-After（若有）退避重试，不能当作欠费；频率限制响应不保证为 JSON。

502 / 503 / 500同步生成失败

同步生成终态失败分别返回 502 / generation_failed、503 / worker_interrupted 或 500 / internal_error，并保留 task_id、status: failed、error 和 message。提交前发生的内部异常也可能返回 500，尚未受理时没有任务 ID。记录已有任务 ID 与请求 ID 以便排查。

{
  "success": false,
  "task_id": "00000000-0000-4000-8000-000000000002",
  "status": "failed",
  "error": "generation_failed",
  "message": "Image generation failed",
  "request_id": "00000000-0000-4000-8000-000000000001"
}

{
  "success": false,
  "error": "missing_prompt",
  "message": "Prompt is required"
}