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 金鑰、檢視用量與餘額