Documentation Index
Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
Use this file to discover all available pages before exploring further.
概述
这是一个面向 Coze 平台 的自定义 Python 插件,把 API易 的 Nano Banana Pro 模型(gemini-3-pro-image-preview)封装成 Coze 工作流可直接调用的节点。插件内置完整的请求构造、错误码识别、违规内容判定与阿里云 OSS 上传链路,返回的是可直接展示的公网 URL,省去你在 Coze 工作流里再做一次结果转发的工作。
项目信息
- 📦 形态:代码包形式分享(未公开在 GitHub)
- 👤 作者:Shuaila1996
- 🎯 适用平台:Coze 国内版 / 海外版自定义插件
- 🔌 调用模型:
gemini-3-pro-image-preview(API易) - 📝 完整代码已在下方”插件完整源码”章节提供,可直接复制使用
核心功能
文生图 / 图生图统一入口
根据
fileurls 是否为空,自动切换文生图与改图模式,无需在 Coze 工作流里写两套节点多张参考图改图
传入图片 URL 列表后自动下载并以
inline_data 方式注入请求,保留原图细节精细化错误识别
区分
ZERO_CANDIDATES_TOKEN、FINISH_REASON、INLINE_DATA_EMPTY、TEXT_RESPONSE 等多种失败原因,便于工作流分支处理违规内容自动归类
遇到水印移除、换脸、色情、超出知识库年限等任务时,返回明确的拒绝类型而非让用户自行猜测
OSS 直传
生成的 base64 图片直接上传阿里云 OSS,工作流拿到的是可直接外发或入库的 URL
分辨率超时自适应
1K / 2K / 4K 各自配置独立超时(360s / 600s / 1200s),4K 高清场景也不会被中断
支持的 API易 模型
| 模型名称 | 模型标识 | 用途 | API 文档 |
|---|---|---|---|
| Nano Banana Pro | gemini-3-pro-image-preview | 文生图、图生图 | 查看文档 |
插件架构

输入输出参数
入参(Input)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
cleantext | string | 是 | 用户文字提示词或编辑指令 |
fileurls | string[] | 否 | 参考图 URL 列表,留空走文生图 |
aspect_ratio | string | 是 | 宽高比,如 1:1、16:9、9:16 |
resolution | string | 是 | 分辨率,必须大写:1K / 2K / 4K |
apikey | string | 是 | API易 密钥(建议在 Coze 工作流上游分发,按用户分配) |
出参(Output)
| 字段 | 类型 | 说明 |
|---|---|---|
analysis | string | 状态文案:图片生成成功 / 图片生成失败 |
url | string | null | 成功时返回 OSS 公网链接 |
error | string | null | 失败时返回友好错误描述 |
部署步骤
第一步:准备 API易 与 OSS 凭证
- 在 API易控制台 申请密钥(以
sk-开头) - 在阿里云开通 OSS Bucket,并创建一个 RAM 子账号,授予该 Bucket 的
oss:PutObject权限 - 记录
AccessKey ID、AccessKey Secret、Bucket 名称、Endpoint(如oss-cn-beijing.aliyuncs.com)
第二步:在 Coze 创建自定义插件
- 进入 Coze 工作台 → 资源库 → 创建自定义插件
- 运行模式选择「云侧插件 - 在 Coze IDE 中创建」
- 工具运行环境选择 Python
- 添加依赖包:
requests、oss2
错误码识别策略
插件不只判断success=True/False,还会按以下顺序识别失败原因,便于在 Coze 工作流里做差异化处理:
| 优先级 | 错误类型 | 触发条件 | 推荐处理 |
|---|---|---|---|
| 1 | ZERO_CANDIDATES_TOKEN | usageMetadata.candidatesTokenCount == 0 | 提示词或图片触发审核,建议改写 |
| 2 | NO_CANDIDATES | candidates 为空 | 系统出错,重试 |
| 3 | FINISH_REASON | finishReason 非 STOP | 按 PROHIBITED_CONTENT / SAFETY 等映射 |
| 4 | NO_PARTS | content.parts 为空 | 重试 |
| 5 | INLINE_DATA_EMPTY | 检测到 inlineData 但 data 为空 | 重试或换 prompt |
| 6 | TEXT_RESPONSE | 只返回了文本说明 | 自动归类为水印/换脸/色情/年限超出 |
插件完整源码
下面是coze-nanobanana-pro.py 的完整代码,可以直接复制到 Coze IDE。只需修改顶部 4 行 OSS 配置即可投入使用。
coze-nanobanana-pro.py
在 Coze 工作流中使用
插件发布后,在 Coze 工作流编辑器里拖入插件节点,按以下方式连线:常见问题
为什么不直接返回 base64,而要多走一步 OSS?
为什么不直接返回 base64,而要多走一步 OSS?
Coze 工作流后续节点(特别是飞书字段捷径)大多需要 可访问的 URL 才能转换为图片附件。直接返回 base64 会让数据在工作流里反复传输,不仅性能差,飞书侧还无法直接渲染。OSS 链接还方便长期归档与对外分享。
OSS 配置可以用环境变量吗?
OSS 配置可以用环境变量吗?
Coze 自定义插件目前不支持系统环境变量。推荐做法:把 OSS 凭证写在代码顶部常量,并通过 Coze 的「插件加密配置」功能保护。如果你的工作流面向多租户,建议把 OSS 路径前缀也按租户分目录写入。
apikey 为什么要从入参传入而不是写死?
apikey 为什么要从入参传入而不是写死?
便于按用户分发不同密钥。在 Coze 工作流中可以前置一个「人员 apikey 分离」字典节点,按调用人姓名匹配对应的 API易 密钥,方便用量核算与权限控制。
4K 分辨率经常超时?
4K 分辨率经常超时?
Nano Banana Pro 的 4K 出图本身需要较长时间(通常 5-15 分钟)。插件已为 4K 配置了 1200 秒超时,如果还是超时,建议:
- 降级到 2K 调试 prompt
- 检查 API易 控制台是否有限流
- 减少同时调用并发数
错误返回 `TEXT_RESPONSE` 怎么处理?
错误返回 `TEXT_RESPONSE` 怎么处理?
这通常意味着模型拒绝了任务(违规、超出知识库等),插件会自动判别类型:水印移除、换脸、色情、年份超出 2025 等。按
error 字段文案展示给用户即可,不要重试——重试结果一致。完整源码在哪里?可以直接复制吗?
完整源码在哪里?可以直接复制吗?
可以。本文档”插件完整源码”章节提供了
coze-nanobanana-pro.py 的完整代码(作者 Shuaila1996 贡献),只需修改顶部 4 行 OSS 配置就能直接粘贴到 Coze IDE 投入使用,无需额外索取。如果你还需要:- 飞书字段捷径代码 → 见 飞书多维表格 AI 生图方案 中的”飞书字段捷径完整源码”章节
- 阿里云函数计算代码 → 同上文档中的”阿里云函数计算完整源码”章节
相关资源
飞书多维表格 AI 生图方案
本插件的最佳搭档:把整条 Coze 工作流接入飞书多维表格,运营同学填表即可批量出图
Nano Banana Pro 文档
查看 Nano Banana Pro 完整 API 文档、定价与生图样例
生图失败排查
Nano Banana 生图常见问题排查指南,匹配本插件的错误码体系
API易控制台
管理 API 密钥、查看用量与余额
