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.
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.
- 📦 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
fileurls is empty — no need for two parallel branches in your workflowMulti-reference editing
inline_data, preserving original detailGranular error classification
ZERO_CANDIDATES_TOKEN, FINISH_REASON, INLINE_DATA_EMPTY, TEXT_RESPONSE and more, so workflow branches can react preciselyAuto violation labeling
Direct OSS upload
Resolution-aware timeout
Supported APIYI Models
| Model | Identifier | Use | API Doc |
|---|---|---|---|
| Nano Banana Pro | gemini-3-pro-image-preview | Text-to-image, image-to-image | View doc |
Plugin Architecture

Inputs and Outputs
Input
| Field | Type | Required | Description |
|---|---|---|---|
cleantext | string | yes | User prompt or edit instruction |
fileurls | string[] | no | Reference image URLs; empty triggers text-to-image |
aspect_ratio | string | yes | Aspect ratio, e.g. 1:1, 16:9, 9:16 |
resolution | string | yes | Resolution, must be uppercase: 1K / 2K / 4K |
apikey | string | yes | APIYI key (recommended: distribute per-user via the upstream node) |
Output
| Field | Type | Description |
|---|---|---|
analysis | string | Status label: 图片生成成功 / 图片生成失败 |
url | string | null | OSS public URL on success |
error | string | null | Friendly error message on failure |
Deployment
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:PutObjectpermission on that bucket - Note down
AccessKey ID,AccessKey Secret,Bucket name, andEndpoint(e.g.oss-cn-beijing.aliyuncs.com)
Step 2: Create a custom plugin in Coze
- Go to Coze Workspace → Library → Create custom plugin
- Pick “Cloud-side plugin — create in Coze IDE”
- Runtime: Python
- Add dependencies:
requests,oss2
Step 3: Paste the plugin code
Step 4: Configure metadata, inputs, and outputs
args.input fields in code:
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:| Priority | Error type | Trigger | Recommended action |
|---|---|---|---|
| 1 | ZERO_CANDIDATES_TOKEN | usageMetadata.candidatesTokenCount == 0 | Prompt or image flagged in moderation; rewrite |
| 2 | NO_CANDIDATES | candidates is empty | System error; retry |
| 3 | FINISH_REASON | finishReason not STOP | Mapped: PROHIBITED_CONTENT / SAFETY / etc. |
| 4 | NO_PARTS | content.parts is empty | Retry |
| 5 | INLINE_DATA_EMPTY | inlineData present but data empty | Retry or rephrase |
| 6 | TEXT_RESPONSE | Only text returned | Auto-categorized as watermark / face-swap / NSFW / year-cutoff |
Plugin Full Source
Below is the completecoze-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.
Using It in a Coze Workflow
Once published, drag the plugin node into your Coze workflow and wire it like this:FAQ
Why upload to OSS instead of returning base64?
Why upload to OSS instead of returning base64?
Can I use environment variables for OSS config?
Can I use environment variables for OSS config?
Why is apikey passed in instead of hardcoded?
Why is apikey passed in instead of hardcoded?
4K generation keeps timing out?
4K generation keeps timing out?
- Drop to 2K to debug your prompt
- Check APIYI Console for rate limits
- Reduce concurrent calls
What to do with TEXT_RESPONSE errors?
What to do with TEXT_RESPONSE errors?
error field to the user — don’t retry, the result will be the same.Where's the full source code? Can I copy it directly?
Where's the full source code? Can I copy it directly?
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:- The Feishu field shortcut → see “Feishu Field Shortcut Full Source” in Feishu Bitable AI Image Generation Workflow
- The Aliyun FC code → see “Aliyun Function Compute Full Source” in the same doc