Nano Banana for Dify: step-by-step guide

Generate one Nano Banana image from a prompt. This guide takes you from your first API key to the result in a Dify Workflow. Screenshots use Dify CE 1.17.1 in English; later versions may move the same controls.

Read in Simplified Chinese · API and pricing

1. Install the correct plugin

Open Nano Banana by acedatacloud in Dify Marketplace. Check the author is acedatacloud, choose Install, and select your Dify workspace. In Dify, open Integrations → Tools → Tool Plugin → Nano Banana.

If your Dify server cannot open Marketplace, ask its administrator to enable outbound access and plugin installation. The plugin needs HTTPS to .

2. Get an API key with the correct access

Sign in at Ace Data Cloud → Applications.
Open General application. Its API key can access multiple services your account is entitled to use. A service-specific key is limited to that service. For this tutorial, check Nano Banana access and current pricing/balance before generating.
To reuse the selected key, click the copy icon marked 1 below. To create a separate Dify key, click Manage Keys marked 2, then Create.

Give the new key a name, such as . Set expiration and usage/API restrictions only as needed, then click Create. Return to the key list or application card and copy the key. If Allowed APIs is enabled, include both the generation and task-query APIs used here: , .

Copy only the token string. Do not add , quotation marks, or the screenshot's redacted characters. A platform management token (for example, a token) is not the generation API key this plugin expects. Confirm service access and a sufficient balance before the first run.

3. Authorize Nano Banana in Dify

Open Integrations → Tools → Tool Plugin → Nano Banana.
Click API Key Authorization Configuration. If an authorization already exists, click 1 Authorization first, then the configuration button.
Enter an Authorization Name, such as , and paste the copied token into Ace Data Cloud Bearer Token.
Choose who may use the credential and click Save. Never put a key in a prompt or workflow export.

4. Build your first Workflow

Open Studio → Create → Create from Blank → Workflow, name it, and create this path by dragging from each node's right connector to the next node:

Start → Nano Banana Generate Image → Nano Banana Retrieve Task → Output.

Use the + button to add a Tool, select this plugin, and choose the exact action above. Rename the generation node Nano Banana and the query node Retrieve completed task to match the screenshots. Leave Start inputs empty for this fixed first example. Keep Retry on Failure off on the generation node.

Select Nano Banana Generate Image and set these fields. Leave unmentioned optional fields empty.

Dify field	First-run value
Model ()
Resolution ()
Aspect ratio ()
Image count ()

Prompt ():

For editing, select Nano Banana Edit Image, set Reference image URLs to a JSON array such as , and describe the change. Replace the placeholder URL with your own accessible image. Model variants have separate access and pricing.

5. Wait for the same task and map the result

Select Nano Banana Retrieve Task. In Task ID, click the variable picker (or type ) and choose Nano Banana → task_id. It must be the output variable from the generation node, not its name typed as plain text. Set Wait up to seconds to ; leave Trace ID empty for this example.

Select Output, click + to add output fields, and choose the variables below from Retrieve completed task:

Output name	Select from query node	Type
status	status	String
success	success	Boolean
task_id	task_id	String
media_urls	media_urls	Array[String]
result	result	Object

Click Test Run → Start Run. Generation may finish before the bounded wait expires; otherwise is normal. Do not rerun the whole workflow while it is pending, because that submits a new generation. Copy its task ID and create a separate Start → Nano Banana Retrieve Task → Output workflow with that ID and a wait of 0 or 240. Query the same ID until and ; then open the links in . A green Dify workflow alone is not proof that the service task finished.

6. Check the expected output

A completed result has this shape (the URL below illustrates the field; use your own returned URL):

Actual Dify workflow after installing version 0.0.2 from the official Marketplace on October 11, 2026. The service returned a completed 1024×1024 image. Your task ID and media URL will differ.

Version 0.0.3 adds to generation and editing. Select it in Model; 1K, 2K and 4K are available. The default remains . Check current model pricing before switching.

Download the ready-to-import workflow. Install this plugin first, import the workflow in Studio, then configure your own credential.

Troubleshooting

What you see	What to do
Authorization fails / 401 or 403	Copy the full API token, remove , check service access, balance, expiration and Allowed APIs.
Invalid parameter / 400	Copy the exact example model, action, resolution and JSON shape. Do not combine unrelated action fields.
or an empty media list	Query the same task ID again. Never regenerate just to poll.
HTTP 429	Wait, reduce concurrency and check service limits; do not enable automatic paid retries.
Timeout / 5xx / failed task	Inspect the original task or request history before resubmitting. Contact support with task/trace ID, never your key.
Media link will not load	Check the task is terminal and the returned link is accessible from the Dify server/browser.

Privacy, cost and support

The free plugin sends your chosen inputs and token to ; API calls follow current service pricing. Keys stay in Dify credential storage. See Privacy. Only submit content you have permission to process.

Source · Report a problem · [email protected] · Advanced capabilities. Development and test evidence live in the source repository, separate from this first-run guide.