Skip to main content

Overview

This is a custom Python plugin for the Coze platform that wraps APIYI’s Nano Banana Pro model (gemini-3-pro-image-preview) into a node any Coze workflow can call directly. The plugin includes a complete request builder, fine-grained error classification, content-violation detection, and Aliyun OSS upload — what comes back is a public URL ready to display, so you don’t need an extra forwarding node downstream.
Project Info
  • 📦 Form: Shared as a code package (not published on GitHub)
  • 👤 Author: Shuaila1996
  • 🎯 Platforms: Coze CN / Global custom plugins
  • 🔌 Model: gemini-3-pro-image-preview (via APIYI)
  • 📝 The full source code is embedded below in the “Plugin Full Source” section — copy and paste, no separate download needed

Core Features

Unified text-to-image / image-to-image

Auto-switches between txt2img and img2img modes based on whether fileurls is empty — no need for two parallel branches in your workflow

Multi-reference editing

Pass an array of image URLs and they’re downloaded and injected as inline_data, preserving original detail

Granular error classification

Distinguishes ZERO_CANDIDATES_TOKEN, FINISH_REASON, INLINE_DATA_EMPTY, TEXT_RESPONSE and more, so workflow branches can react precisely

Auto violation labeling

For watermark removal / face-swap / NSFW / out-of-knowledge-cutoff prompts, returns a clear refusal type instead of forcing users to guess

Direct OSS upload

The base64 result is uploaded straight to Aliyun OSS — your workflow gets back a URL ready to share or store

Resolution-aware timeout

Independent timeouts for 1K / 2K / 4K (360s / 600s / 1200s), so 4K HD jobs don’t get cut off

Supported APIYI Models

The plugin calls APIYI’s https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent endpoint (Gemini-native protocol), identical to Google AI Studio — so existing prompts port cleanly.

Plugin Architecture

Coze plugin configuration Core flow:

Inputs and Outputs

Input

Output

Deployment

1

Step 1: Prepare APIYI and OSS credentials

  • Generate an APIYI key (starts with sk-) at APIYI Console
  • Create an Aliyun OSS Bucket and a RAM sub-account with oss:PutObject permission on that bucket
  • Note down AccessKey ID, AccessKey Secret, Bucket name, and Endpoint (e.g. oss-cn-beijing.aliyuncs.com)
2

Step 2: Create a custom plugin in Coze

  1. Go to Coze Workspace → Library → Create custom plugin
  2. Pick “Cloud-side plugin — create in Coze IDE”
  3. Runtime: Python
  4. Add dependencies: requests, oss2
3

Step 3: Paste the plugin code

Copy the complete Python code from the “Plugin Full Source” section below into Coze IDE, then update the 4 OSS config lines at the top of the file with your own values:
4

Step 4: Configure metadata, inputs, and outputs

Configure Input / Output fields and required flags as below, matching the args.input fields in code:Coze plugin metadata configuration
5

Step 5: Test and publish

  • In the Coze IDE, fill in test parameters (recommended: 1K + simple prompt to validate the OSS path first)
  • When green, hit “Publish” and the node is now draggable in any workflow

Error Classification Strategy

The plugin doesn’t just return a boolean — it identifies failure causes in this priority order, so workflow branches can react differently:

Plugin Full Source

Below is the complete coze-nanobanana-pro.py. You can copy it into Coze IDE as-is — just update the 4 OSS config lines at the top and you’re ready to publish.
coze-nanobanana-pro.py

Using It in a Coze Workflow

Once published, drag the plugin node into your Coze workflow and wire it like this:
Pair it with the Feishu Bitable AI Image Generation Workflow for a no-code production line — operators just fill rows in Feishu Bitable to batch-generate images.

FAQ

Downstream Coze workflow nodes (especially Feishu field shortcuts) generally need an accessible URL to convert results into image attachments. Returning base64 means the data hops through the workflow inefficiently, and Feishu can’t render it directly. OSS links also make long-term archiving and external sharing trivial.
Coze custom plugins don’t expose system environment variables today. Recommended approach: keep the OSS credentials as constants at the top of the file and protect them with Coze’s plugin encryption feature. For multi-tenant workflows, also write per-tenant prefixes into the OSS path.
To distribute different keys per caller. Add a “Per-user API key” dictionary node upstream that maps a caller’s name to their APIYI key — clean for usage accounting and access control.
Nano Banana Pro 4K generation is genuinely slow (typically 5–15 minutes). The plugin already configures a 1200-second timeout for 4K. If still timing out:
  1. Drop to 2K to debug your prompt
  2. Check APIYI Console for rate limits
  3. Reduce concurrent calls
This usually means the model refused (violation, year-cutoff, etc.). The plugin auto-classifies the type: watermark removal / face-swap / NSFW / year > 2025. Show the error field to the user — don’t retry, the result will be the same.
Yes. The “Plugin Full Source” section above contains the complete coze-nanobanana-pro.py (contributed by Shuaila1996). Just update the 4 OSS config lines at the top and paste it into Coze IDE — no separate download needed.If you also need:

Feishu Bitable AI Image Generation

The perfect companion: hook this Coze workflow into Feishu Bitable so operators just fill rows to batch-generate

Nano Banana Pro Doc

Full Nano Banana Pro API doc, pricing, and generation samples

Image generation failure FAQ

Nano Banana failure-troubleshooting guide aligned with this plugin’s error codes

APIYI Console

Manage API keys, view usage and balance