Skip to main content

概述

这是一个面向 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_TOKENFINISH_REASONINLINE_DATA_EMPTYTEXT_RESPONSE 等多种失败原因,便于工作流分支处理

违规内容自动归类

遇到水印移除、换脸、色情、超出知识库年限等任务时,返回明确的拒绝类型而非让用户自行猜测

OSS 直传

生成的 base64 图片直接上传阿里云 OSS,工作流拿到的是可直接外发或入库的 URL

分辨率超时自适应

1K / 2K / 4K 各自配置独立超时(360s / 600s / 1200s),4K 高清场景也不会被中断

支持的 API易 模型

插件调用的是 API易 的 https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent 端点(Gemini 原生协议),与官方 Google AI Studio 完全一致,便于复用现成 prompt。

插件架构

Coze 插件配置示意 插件核心调用链:

输入输出参数

入参(Input

出参(Output

部署步骤

1

第一步:准备 API易 与 OSS 凭证

  • API易控制台 申请密钥(以 sk- 开头)
  • 在阿里云开通 OSS Bucket,并创建一个 RAM 子账号,授予该 Bucket 的 oss:PutObject 权限
  • 记录 AccessKey IDAccessKey SecretBucket 名称Endpoint(如 oss-cn-beijing.aliyuncs.com
2

第二步:在 Coze 创建自定义插件

  1. 进入 Coze 工作台 → 资源库 → 创建自定义插件
  2. 运行模式选择「云侧插件 - 在 Coze IDE 中创建」
  3. 工具运行环境选择 Python
  4. 添加依赖包:requestsoss2
3

第三步:复制插件代码

将下方”插件完整源码”章节的 Python 代码完整粘贴到 Coze IDE 中,并把代码顶部的阿里云 OSS 配置改成你自己的:
4

第四步:配置元数据与入参出参

按下图配置 Input / Output 字段类型与必填项,与代码中的 args.input 字段保持一致:Coze 插件元数据配置
5

第五步:测试与发布

  • 在 Coze IDE 内填入测试参数(建议先用 1K + 简单 prompt 验证 OSS 链路)
  • 测试通过后点击「发布」即可在工作流中拖拽使用

错误码识别策略

插件不只判断 success=True/False,还会按以下顺序识别失败原因,便于在 Coze 工作流里做差异化处理:

插件完整源码

下面是 coze-nanobanana-pro.py 的完整代码,可以直接复制到 Coze IDE。只需修改顶部 4 行 OSS 配置即可投入使用。
coze-nanobanana-pro.py

在 Coze 工作流中使用

插件发布后,在 Coze 工作流编辑器里拖入插件节点,按以下方式连线:
推荐配合 飞书多维表格 AI 生图方案 使用,整套方案让运营/设计同学在飞书表格里填提示词就能批量出图,无需打开任何代码。

常见问题

Coze 工作流后续节点(特别是飞书字段捷径)大多需要 可访问的 URL 才能转换为图片附件。直接返回 base64 会让数据在工作流里反复传输,不仅性能差,飞书侧还无法直接渲染。OSS 链接还方便长期归档与对外分享。
Coze 自定义插件目前不支持系统环境变量。推荐做法:把 OSS 凭证写在代码顶部常量,并通过 Coze 的「插件加密配置」功能保护。如果你的工作流面向多租户,建议把 OSS 路径前缀也按租户分目录写入。
便于按用户分发不同密钥。在 Coze 工作流中可以前置一个「人员 apikey 分离」字典节点,按调用人姓名匹配对应的 API易 密钥,方便用量核算与权限控制。
Nano Banana Pro 的 4K 出图本身需要较长时间(通常 5-15 分钟)。插件已为 4K 配置了 1200 秒超时,如果还是超时,建议:
  1. 降级到 2K 调试 prompt
  2. 检查 API易 控制台是否有限流
  3. 减少同时调用并发数
这通常意味着模型拒绝了任务(违规、超出知识库等),插件会自动判别类型:水印移除、换脸、色情、年份超出 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 密钥、查看用量与余额