API 文档

一、当前状态

当前阶段 API 仅供 内部使用（网页端 / 小程序端调用），未开放公网接入。

若你现在就需要批量生成图像，建议先使用网页工作台，通过模板 + 自定义变量配合脚本化提交工作流（每月配额自动结算）。

二、近期规划

预计开发节奏（最终时间表以公告为准）：

• Phase 1 · 内测（2026 Q3）：邀请制内测，开放图像生成 / 任务状态 / 模板查询 三类接口
• Phase 2 · 公测（2026 Q4）：开放注册公测，加入 Webhook 通知与批量任务
• Phase 3 · 正式（2027 Q1）：商业版本上线，包括 SLA、弹性计费、专属客户经理

三、接口预览

以下为接口设计草案，最终形态可能调整。

认证

通过控制台获取 API Key，每次请求在 Authorization: Bearer YOUR_API_KEY 中携带。

创建生成任务

POST /v1/images/generate

• scene：场景代码（wechat_cover / xhs_header 等）
• prompt：图像描述文本
• aspect_ratio：宽高比（如 4:5）
• style：风格（illustration / realistic）
• ref_image_url（可选）：参考图 URL

响应：

• task_id：任务 ID，用于查询状态
• status：queued / processing / success / failed
• estimated_seconds：预估完成时间

查询任务状态

GET /v1/images/tasks/{task_id}

响应包含状态、结果图 URL（有效期 1 小时）、生成耗时、消耗配额数等。

查询配额

GET /v1/account/quota

返回当前周期总配额 / 已用 / 剩余 / 超量数。

Webhook 回调

在控制台配置 Webhook URL 后，任务完成（成功 / 失败）会 POST 到该 URL，body 含 task_id、status、结果 URL。我们会重试最多 5 次（指数退避），所以服务端需保证幂等。

四、提前申请

如果你的业务场景需要 API 接入（如：批量出图工作流、第三方平台集成），欢迎提前申请加入开发者预览。请发送邮件至dev@banana-saas.example（占位）说明：

• 公司 / 个人简介
• 预期月生成量级
• 主要使用场景
• 是否需要私有化部署 / 模型微调

我们会在 5 个工作日内回复，优先邀请高质量内测用户。