diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 7e511ec..6cad3b6 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,23 +1,26 @@ { "name": "nano-banana", - "displayName": "Nano Banana", - "version": "1.0.0", + "displayName": "Nano Banana by Ace Data Cloud", + "version": "1.0.1", "minClientVersions": { "cursor": "3.13.0" }, - "description": "Generate Nano Banana images and retrieve the finished image.", + "description": "Generate or edit Nano Banana images with Ace Data Cloud and retrieve completed images by the original task ID.", "author": { "name": "Ace Data Cloud Dev", "email": "dev@acedata.cloud" }, - "homepage": "https://platform.acedata.cloud/models", + "homepage": "https://platform.acedata.cloud/models?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_manifest_pricing", "repository": "https://github.com/AceDataCloud/NanoBananaCursor", "license": "MIT", "logo": "assets/logo.jpg", "keywords": [ - "nano-banana", "nano banana", - "image", + "nanobanana", + "nano-banana", + "image generation", + "image editing", + "ace data cloud", "acedatacloud", "mcp" ], @@ -25,7 +28,7 @@ "tags": [ "nano-banana", "image", - "mcp" + "acedatacloud" ], "variables": { "type": "object", diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a15657..b2c843f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## 1.0.1 + +- Clarify the independent service name and Ace Data Cloud publisher relationship in discovery metadata. +- Add bilingual install/token/setup guidance and sourced credential/official UI reference images; preserve the hosted MCP and same-task workflow. + ## 1.0.0 - Initial Nano Banana Cursor plugin using the existing Ace Data Cloud hosted MCP. diff --git a/README.md b/README.md index 54fb170..e470e3d 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,40 @@ -# Nano Banana for Cursor +# Nano Banana by Ace Data Cloud for Cursor + +This independent **Nano Banana by Ace Data Cloud** integration brings image generation, image editing and task retrieval into Cursor Agent. It is maintained by Ace Data Cloud, not an official plugin from the model brand or Cursor. The hosted MCP connection avoids running a local server; your service API token is entered once in Configure. Generate Nano Banana images and retrieve the finished image. This standalone plugin reuses the [Ace Data Cloud nanobanana MCP](https://github.com/AceDataCloud/MCPs/tree/main/nanobanana) and includes a focused Agent skill. Available tools and limits come from the live MCP schema. -[简体中文教程](readme/README_zh_Hans.md) · [Copyable first-run prompt](examples/first-run.md) · [Current pricing](https://platform.acedata.cloud/models) +[简体中文教程](readme/README_zh_Hans.md) · [Copyable first-run prompt](examples/first-run.md) · [Current pricing](https://platform.acedata.cloud/models?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_pricing_en) + +## 1. Find the independent Nano Banana plugin + +Open the [Cursor Marketplace](https://cursor.com/marketplace) or **Customize** in Cursor. Search **Nano Banana** (nano banana, nanobanana, nano-banana), then look for **Nano Banana by Ace Data Cloud** and publisher/author **Ace Data Cloud Dev**. Select **Install** and choose the project or user scope. Cursor 3.24 used **Customize → Browse Marketplace → Add**; use the controls in your installed version. Installing this plugin does not require an Ace collection plugin. + +**Publication status:** [the official submission](https://github.com/cursor/plugins/pull/562) is pending review; an available source repository or a passing check does not prove a live Marketplace listing. If the exact listing is absent, do not install a similarly named unrelated plugin. An optional source/local review under `~/.cursor/plugins/local/nano-banana/` is a manual route, not official distribution. This is a tool integration, not an Ace preset in Cursor's chat-model provider list. + +For an unpublished candidate, use the [pinned local-review procedure](docs/local-review.md) rather than guessing a Marketplace URL. It copies the tracked candidate files, checks for an existing installation, and records the exact commit. Local loading needs a reload and allowed local imports; an external-repository symlink is skipped, and a same-name Marketplace install takes precedence. This procedure does not claim official installation. + +## 2. Register or sign in and get a service API token + +1. [Open Ace Data Cloud](https://platform.acedata.cloud/?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_register_signin_en) and register or sign in. Then open [Applications](https://platform.acedata.cloud/console/applications?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_api_key_en). If no General application exists, select **Initialize General Application**. +2. Open **General application** or an application enabled for **Nano Banana**. Confirm service access, balance and [current pricing](https://platform.acedata.cloud/models?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_pricing_en) before any generation. +3. Copy an existing API Key with the copy button marked **1** below, or open **Manage Keys** marked **2**, then **Create** for a dedicated Cursor token. + +![Copy an existing service API token or open Manage Keys](assets/tutorial/get-api-key-en.png) -## 1. Search and install +4. Name the optional key, for example **Cursor Nano Banana**. Set expiry and usage/API limits as needed; create it and copy the token. The screenshot's **Dify tutorial** name is a historical example only; use your Cursor-specific name. If Allowed APIs is enabled, allow the actions needed here: `/nano-banana/images`, `/nano-banana/tasks`. -In Cursor 3.24, open **Customize → Browse Marketplace**, search for **Nano Banana**, confirm **Ace Data Cloud Dev** and the service logo, then click **Add**. Older releases may put Plugins under Settings. You can also use `/add-plugin nano-banana` in chat. If the official listing is not live, review this source under `~/.cursor/plugins/local/nano-banana/`; local installation does not prove Marketplace publication. +![Optional dedicated API token creation](assets/tutorial/create-api-key-en.png) -## 2. Get a service API key +These are real Ace Applications screenshots reused from the [Suno Dify tutorial](https://github.com/AceDataCloud/SunoDify/blob/8d3d03570e73324220f111f7fe343da0792a8071/README.md), checked on **2026-10-18**; original capture date is not recorded. Key, application ID and balance are obscured. They show Ace credential management, not a Dify step required for Cursor. -1. Sign in at [Ace Data Cloud Applications](https://platform.acedata.cloud/console/applications). -2. Open **General application** or a service-specific application. Copy an existing API key, or use **Manage Keys → Create** for a separate Cursor key. -3. Confirm Nano Banana access, [current price](https://platform.acedata.cloud/models), and balance. If **Allowed APIs** restrictions are enabled, include /nano-banana/images, /nano-banana/tasks. +Copy only the service token string: no `Bearer ` prefix, quotation marks or redacted screenshot characters. This is not a platform management token. Never put a token in prompts, source, screenshots or exported examples. -Use a service API key, not a platform management token. Do not put it in chat or source files. +## 3. Paste the token in Cursor Configure -## 3. Configure the plugin +Open **Customize → Plugins → Nano Banana by Ace Data Cloud → Configure** (older versions may show **Nano Banana**). Paste the token in **Ace Data Cloud API token**, choose **Save**, wait for completion, then reopen Configure to confirm a masked value. Cursor substitutes `ACEDATACLOUD_API_TOKEN`; the plugin adds `Bearer ` and connects to its hosted HTTP MCP. No Python or Node server needs to be started. Reconnect if tools have not loaded. -Open **Customize → Plugins → Nano Banana → Configure**, paste the key string into **Ace Data Cloud API token**, and click **Save**. Cursor uses it as `ACEDATACLOUD_API_TOKEN`; the plugin adds `Bearer `. Reconnect the MCP server if tools are missing. The hosted endpoint needs no local Python installation. +The Configure path and variable behavior follow the [official Cursor plugin reference](https://cursor.com/docs/reference/plugins#variables), checked **2026-10-18**. A current Ace-specific Configure screenshot is still pending; the official screenshots below illustrate the subsequent tool approval/result UI, not this token field. ```json { @@ -42,6 +58,20 @@ Submit with `nanobanana_generate_image` once. Save the returned `task_id` and us Open the returned image and inspect it. In **Ace Data Cloud → Usage/Billing**, match this call to its deducted Credits record. The plugin is free; API calls follow current service pricing. +## 5. Confirm one tool call and inspect the result + +For a free first connection check, open Agent and ask **“List this plugin's tools without generating anything.”** Then inspect the live schema for `nanobanana_generate_image` to see available model values. Confirm model access and current price before explicitly approving a new generation. Keep generation retries off; if a request times out, inspect the existing task and usage before deciding whether to pay again. + +The following are **unaltered official Cursor screenshots**, downloaded/checked **2026-10-17**. The original example queries PostgreSQL, not Ace; the official page does not state its client version or capture date. They illustrate where to inspect the tool name/arguments and click **Run tool**, then inspect a returned result. They do not prove this plugin has been installed or run. + +![Official Cursor tool approval screenshot; PostgreSQL reference, not an Ace run](assets/tutorial/tool-confirm.png) + +![Official Cursor tool result screenshot; PostgreSQL reference, not an Ace run](assets/tutorial/tool-call.png) + +After an approved generation, query `nanobanana_get_task` with **`task_id` set to the original task ID**. For example: “Only call `nanobanana_get_task` with `task_id=`; do not generate again.” Check completion and open your actual returned media URL. An accepted/pending task, a green tool indicator or an example link is not a finished, playable result. Check the corresponding single generation record in Ace Usage/Billing; Cursor/model auxiliary charges are separate. + +Screenshot sources, checksums and reuse boundaries: [image provenance](assets/tutorial/SOURCES.json). + ## Troubleshooting | Symptom | Action | @@ -54,3 +84,5 @@ Open the returned image and inspect it. In **Ace Data Cloud → Usage/Billing**, | Result URL will not open | Confirm a terminal success and use the URL returned by that call. | [Source](https://github.com/AceDataCloud/NanoBananaCursor) · [Report a problem](https://github.com/AceDataCloud/NanoBananaCursor/issues) · dev@acedata.cloud. The logo reuses an existing Ace Data Cloud integration asset. This tool plugin does not register a Cursor chat-model provider. + +[Register / sign in](https://platform.acedata.cloud/?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_register_signin_en) · [Applications / API token](https://platform.acedata.cloud/console/applications?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_api_key_en) · [Current Nano Banana pricing](https://platform.acedata.cloud/models?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_pricing_en) diff --git a/assets/tutorial/SOURCES.json b/assets/tutorial/SOURCES.json new file mode 100644 index 0000000..2684c20 --- /dev/null +++ b/assets/tutorial/SOURCES.json @@ -0,0 +1,51 @@ +{ + "service": "Nano Banana", + "sources": [ + { + "file": "get-api-key-en.png", + "type": "real_ace_console_screenshot", + "source_url": "https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/get-api-key-en.png", + "official_page_url": "https://github.com/AceDataCloud/SunoDify/blob/8d3d03570e73324220f111f7fe343da0792a8071/README.md", + "checked_at": "2026-10-18", + "original_capture_date": "not recorded", + "edit_date": null, + "limits": "Original token/ID/balance obscured; Dify tutorial key name is an example, use Cursor-specific name.", + "sha256": "b63787f2bd15af82fef9ab61c99e11c454355ac86e91f7f94559386b795069b7" + }, + { + "file": "create-api-key-en.png", + "type": "real_ace_console_screenshot", + "source_url": "https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/create-api-key-en.png", + "official_page_url": "https://github.com/AceDataCloud/SunoDify/blob/8d3d03570e73324220f111f7fe343da0792a8071/README.md", + "checked_at": "2026-10-18", + "original_capture_date": "not recorded", + "edit_date": null, + "limits": "Original token/ID/balance obscured; Dify tutorial key name is an example, use Cursor-specific name.", + "sha256": "5411ffe75d8a8efa6806a78fc68fce6a20735225d8e9818c94bbc238da4f4590" + }, + { + "file": "tool-confirm.png", + "type": "official_screenshot", + "source_url": "https://cursor.com/docs-static/images/context/mcp/tool-confirm.png", + "official_page_url": "https://cursor.com/docs/mcp", + "checked_at": "2026-10-18", + "original_capture_date": "not recorded", + "edit_date": null, + "limits": "PostgreSQL official reference, not Ace execution.", + "sha256": "0404c2a6e15a83817cf7dd08b177097c835316345e4af629e411ecc369ec7f09" + }, + { + "file": "tool-call.png", + "type": "official_screenshot", + "source_url": "https://cursor.com/docs-static/images/context/mcp/tool-call.png", + "official_page_url": "https://cursor.com/docs/mcp", + "checked_at": "2026-10-18", + "original_capture_date": "not recorded", + "edit_date": null, + "limits": "PostgreSQL official reference, not Ace execution.", + "sha256": "af88bda0de0929b73a955883b0b79ee394ee2f94d96e18329b0fa6db636529e7" + } + ], + "credential_values_present": false, + "current_configure_screenshot": "pending native UI capture, not substituted with a fake screenshot" +} diff --git a/assets/tutorial/create-api-key-en.png b/assets/tutorial/create-api-key-en.png new file mode 100644 index 0000000..dce66e2 Binary files /dev/null and b/assets/tutorial/create-api-key-en.png differ diff --git a/assets/tutorial/get-api-key-en.png b/assets/tutorial/get-api-key-en.png new file mode 100644 index 0000000..0cbf417 Binary files /dev/null and b/assets/tutorial/get-api-key-en.png differ diff --git a/assets/tutorial/tool-call.png b/assets/tutorial/tool-call.png new file mode 100644 index 0000000..1a9a1b9 Binary files /dev/null and b/assets/tutorial/tool-call.png differ diff --git a/assets/tutorial/tool-confirm.png b/assets/tutorial/tool-confirm.png new file mode 100644 index 0000000..c5426ee Binary files /dev/null and b/assets/tutorial/tool-confirm.png differ diff --git a/docs/local-review.md b/docs/local-review.md new file mode 100644 index 0000000..04eae4a --- /dev/null +++ b/docs/local-review.md @@ -0,0 +1,55 @@ +# Nano Banana: pinned local candidate review / 固定候选本地审查 + +2026-10-19. This procedure prepares and loads an **unpublished source candidate**. It is not a Marketplace install, publisher approval, or proof of a completed service call. The public route remains [the existing official submission](https://github.com/cursor/plugins/pull/562). + +## Preconditions and exact source + +- Read the current **OPEN** source PR (https://github.com/AceDataCloud/NanoBananaCursor/pull/2) and record its current commit SHA. Use that exact commit in your dedicated source checkout; do not assume `main` contains candidate README/manifest changes. Record `git rev-parse HEAD`, client version and source origin in the review receipt. +- In Cursor **Customize**, first check whether a Marketplace plugin with the same name `nano-banana` is already installed. Cursor gives it precedence over the local copy. Do not remove or change the user's installed plugin silently; use an already authorized isolated profile/project or report the collision. +- On Teams/Enterprise, **Allow Local Plugin Imports** is an administrator policy under Dashboard → Settings → Security & Identity → Marketplace and Plugins (off by default on Enterprise). If disabled, stop and report it; do not bypass policy or expand access. +- Do not point `~/.cursor/plugins/local/nano-banana` at this external Git checkout with a symlink: Cursor skips such symlinks. Use the physical tracked-file copy below. Never put a token in the candidate files. + +## Copy the tracked candidate without overwriting existing state + +Run inside the isolated source checkout at the verified commit. The shell stops on an existing destination, including a broken symlink. The command deliberately copies only Git-tracked files; local `.env`, user settings, caches and untracked credentials are excluded. + +```sh +set -eu +candidate_commit=$(git rev-parse HEAD) +candidate_stage=$(mktemp -d "${TMPDIR:-/tmp}/nano-banana-cursor-review.XXXXXX") +git archive --format=tar "$candidate_commit" | tar -xf - -C "$candidate_stage" +test -f "$candidate_stage/.cursor-plugin/plugin.json" +test -f "$candidate_stage/mcp.json" +printf 'Candidate commit: %s\nStaged files: %s\n' "$candidate_commit" "$candidate_stage" +local_plugin_dir="$HOME/.cursor/plugins/local/nano-banana" +if [ -e "$local_plugin_dir" ] || [ -L "$local_plugin_dir" ]; then + printf 'Stop: destination already exists: %s\n' "$local_plugin_dir" >&2 + exit 1 +fi +mkdir -p "$HOME/.cursor/plugins/local" +cp -R "$candidate_stage" "$local_plugin_dir" +``` + +If staging completed but copying stopped, retain the temporary path and receipt; do not force-delete or overwrite an existing installation. Reviewers may inspect the staged directory without launching Cursor. This plugin is Git-distributed and has no build step or local Python/Node worker to run. + +## Load, Configure, and verify a free boundary + +1. Restart Cursor or run **Developer: Reload Window**. Open **Customize** and confirm `Nano Banana by Ace Data Cloud`, manifest version **1.0.1**, one HTTP MCP and the expected Skill. Verify the installed files match your pinned commit, not the old `main` or a same-name Marketplace item. +2. Open the plugin **Configure**. With no key, only record the credential field/required-value behavior; do not claim authenticated access. Do not submit a billable tool just to test a missing token. +3. If an existing authorized service token is already available, paste only its value into **Ace Data Cloud API token**, click **Save**, wait, reopen, and confirm masking. Never place the token in chat, a JSON file, an exported profile or a screenshot. If policy disallows storage/import, stop. +4. For authorized free validation, enable only the existing-task retrieval or free metadata tool from the read-only prompt in the coordinator receipt. Use a task belonging to the existing credential, query the original successful ID, and do not generate, search, transform, or retry a paid action. Current service access, API restrictions and balance still apply. +5. Capture the actual source/client version, installation origin, masked Configure field, tool name/arguments, cancellation/error behavior and returned terminal fields. A tool-cancel before approval proves only cancellation, not a service result. Token rejection/403/429/timeout must remain distinguishable; after an ambiguous generation timeout, query the original ID/history rather than resubmit. + +The copied files contain **configuration variable names only**, not secret values. `mcp.json` keeps the Authorization header template; Configure supplies the value. The UI rendering and persistence of that value require actual Cursor verification; a valid manifest or reference screenshot does not establish them. + +## 中文操作摘要 + +1. 从原源码PR读取当前commit，在隔离源码目录固定该SHA；不要用尚未合并增强的main充当候选。 +2. 先查同名市场插件和本地目录，企业本地导入策略关闭时停止；不卸载用户插件、不擅改管理员策略。外部仓库软链接会被跳过。 +3. 上方命令把Git已跟踪文件放入临时目录，再在目标不存在时物理复制到`~/.cursor/plugins/local/nano-banana`。不复制`.env`、缓存或未跟踪凭据；有目标或软链接就停止，不能覆盖。 +4. Reload Window/重启后，在Customize核插件名称/1.0.1、HTTP MCP、Skill以及文件commit。真实Configure只填已有合法服务Token并核遮蔽保存；无Key只能核空值行为。 +5. 仅在既有授权范围查询原成功任务或免费元数据；生成、搜索、图像/人像变换和自动重试都保持关闭。记录真实确认、取消、错误及返回值。准备包/静态通过不能替代Cursor原生安装/调用，当前Configure实拍仍待补。 + +## Official basis / 官方依据 + +[Cursor Plugins — Test plugins locally](https://cursor.com/docs/plugins#test-plugins-locally), read **2026-10-19**: physical plugin folder, manifest, reload, allowed local imports, installed-plugin precedence and in-folder-only symlink rule. [Variables](https://cursor.com/docs/reference/plugins#variables): manifest declares variable names, not secret values; users supply them in Configure. Follow the labels in the actual recorded client version. diff --git a/readme/README_zh_Hans.md b/readme/README_zh_Hans.md index 4cd6dbc..118fdd5 100644 --- a/readme/README_zh_Hans.md +++ b/readme/README_zh_Hans.md @@ -1,24 +1,40 @@ -# Cursor Nano Banana 插件 +# Nano Banana by Ace Data Cloud：Cursor 接入教程 + +这是由 **Ace Data Cloud** 维护的独立 **Nano Banana** 工具插件，提供图片生成、图片编辑与任务查询；不冒充服务品牌或 Cursor 官方插件。通过托管 MCP 连接，在 Configure 中保存自己的服务 API Token 后，可在 Cursor Agent 里使用，无需启动本地服务。 Generate Nano Banana images and retrieve the finished image. 插件复用 [Ace Data Cloud nanobanana MCP](https://github.com/AceDataCloud/MCPs/tree/main/nanobanana)，并提供专用 Agent skill。实际工具参数和限制以在线 MCP schema 为准。 -[English guide](../README.md) · [可复制的首跑提示词](../examples/first-run.md) · [当前价格](https://platform.acedata.cloud/models) +[English guide](../README.md) · [可复制的首跑提示词](../examples/first-run.md) · [当前价格](https://platform.acedata.cloud/models?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_pricing_zh_hans) + +## 1. 搜索并安装独立 Nano Banana 插件 + +打开 [Cursor 官方插件市场](https://cursor.com/marketplace)或 Cursor 的 **Customize**，搜索 **Nano Banana**（亦可搜 nano banana, nanobanana, nano-banana），核对显示名 **Nano Banana by Ace Data Cloud**、作者 **Ace Data Cloud Dev**，选择 **Install** 以及项目/用户范围。Cursor 3.24 曾使用 **Customize → Browse Marketplace → Add**，以所装版本为准。安装本插件不依赖 Ace 合集。 + +**发布状态：**[官方收录申请](https://github.com/cursor/plugins/pull/562)仍待审核；源码公开或检查成功不等于市场已上架。准确条目不存在时，不要安装同名无关插件。可选的`~/.cursor/plugins/local/nano-banana/`源码本地审查属于手动路径，不能计作官方分发。本插件提供工具，不会在 Cursor 聊天模型服务商列表新增 Ace 预设。 + +准确官方条目尚未发布时，按[固定候选本地审查步骤](../docs/local-review.md)复制已跟踪文件并记录commit，不猜市场地址。加载前核已有安装、允许本地导入，再Reload；指向外部源码目录的软链接会被跳过，同名市场安装优先。本地加载不计官方安装成功。 + +## 2. 注册/登录并取得服务 API Token + +1. 打开 [Ace Data Cloud](https://platform.acedata.cloud/?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_register_signin_zh_hans)注册或登录，再进入 [Applications 应用管理](https://platform.acedata.cloud/console/applications?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_api_key_zh_hans)；若尚无通用应用，先点 **Initialize General Application**。 +2. 打开 **General application**，或已开通 **Nano Banana** 的专用应用；生成前确认权限、余额及[当前价格](https://platform.acedata.cloud/models?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_pricing_zh_hans)。 +3. 使用下图标记 **1** 的复制按钮取已有 API Key；需要独立 Cursor 凭据时，点标记 **2** 的 **Manage Keys → Create**。 + +![复制已有服务Token或进入Manage Keys](../assets/tutorial/get-api-key-en.png) -## 1. 搜索安装 +4. 可选新Key命名为 **Cursor Nano Banana**，按需设置有效期、用量/API限制，创建后复制。截图里的 **Dify tutorial** 是历史示例名称，实际请填自己的Cursor名称。启用 Allowed APIs 时允许所需接口：`/nano-banana/images`, `/nano-banana/tasks`。 -在 Cursor 3.24 打开 **Customize → Browse Marketplace**，搜索 **Nano Banana**，确认作者 **Ace Data Cloud Dev** 和服务图标后点击 **Add**。较早版本可能在 Settings 中提供 Plugins 入口。也可在聊天中输入 `/add-plugin nano-banana`。若官方条目尚未出现，可在 `~/.cursor/plugins/local/nano-banana/` 本地审查；本地安装不代表 Marketplace 已上架。 +![可选的独立API Token创建窗口](../assets/tutorial/create-api-key-en.png) -## 2. 获取服务 API Key +以上是复用[原Suno Dify教程](https://github.com/AceDataCloud/SunoDify/blob/8d3d03570e73324220f111f7fe343da0792a8071/README.md)的真实Ace应用管理截图，**2026-10-18核验**，原拍摄日期未记录；Key、应用ID和余额均已遮蔽。它展示Ace凭据管理，不要求为Cursor使用Dify。 -1. 登录 [Ace Data Cloud 应用管理](https://platform.acedata.cloud/console/applications)。 -2. 打开 **General application** 或服务专用应用，复制已有 Key；也可通过 **Manage Keys → Create** 新建 Cursor 专用 Key。 -3. 确认 Nano Banana 权限、[当前价格](https://platform.acedata.cloud/models)和余额。若启用了 **Allowed APIs**，允许 /nano-banana/images, /nano-banana/tasks。 +只复制Token原文，不加`Bearer `、引号或图中遮蔽字符；不要使用平台管理token。不要把Key写进提示词、源码、截图或导出样例。 -使用服务 API Key，不要用平台管理 token，也不要放在聊天或仓库文件中。 +## 3. 粘贴到 Cursor Configure -## 3. 配置插件 +打开 **Customize → Plugins → Nano Banana by Ace Data Cloud → Configure**（旧版本可能只显示 **Nano Banana**），将Token填到 **Ace Data Cloud API token**，点 **Save**，等保存完成后重开确认遮蔽值。Cursor替换`ACEDATACLOUD_API_TOKEN`，插件自行添加`Bearer `并连接托管HTTP MCP，无需启动本地Python/Node服务。工具未加载时重新连接。 -打开 **Customize → Plugins → Nano Banana → Configure**，将 Key 原文填入 **Ace Data Cloud API token** 并点击 **Save**。Cursor 将其用于 `ACEDATACLOUD_API_TOKEN`；插件会自行添加 `Bearer `，连接 `https://nanobanana.mcp.acedata.cloud/mcp`；无需安装本地 Python 服务。工具未出现时重新连接 MCP。 +路径和变量行为依据 **2026-10-18**读取的[Cursor官方插件说明](https://cursor.com/docs/reference/plugins#variables)。本插件当前版本的Configure真实截图仍待补；下方官方图只演示后续工具确认和结果区域，不是此Token输入框。 ## 4. 首次调用 @@ -28,6 +44,20 @@ Generate Nano Banana images and retrieve the finished image. 插件复用 [Ace D 打开返回的image结果并检查。在 **Ace Data Cloud → Usage/Billing** 核对本次调用对应的 Credits 扣费；插件免费，API 按当前服务价格计费。 +## 5. 确认一次工具调用并检查结果 + +首次免费连接检查可在Agent说：“仅列出本插件工具，不要生成任何内容。”随后检查`nanobanana_generate_image`的在线schema模型参数。新生成前核权限、现价并明确同意一次提交；关闭生成自动重试，超时先查原任务和用量，不自动另付一笔。 + +以下为**未经改动的Cursor官方真实截图**，于**2026-10-17**下载核验；原示例查询PostgreSQL，并非Ace，官方未注明截图版本/拍摄日期。它说明检查工具名/参数、点 **Run tool** 及查看返回值的位置，不证明本插件已安装或实测。 + +![Cursor官方工具确认图：PostgreSQL参考，非Ace运行](../assets/tutorial/tool-confirm.png) + +![Cursor官方工具结果图：PostgreSQL参考，非Ace运行](../assets/tutorial/tool-call.png) + +一次已批准生成后，仅用`nanobanana_get_task`的 **`task_id`参数传原任务ID**。例如：“只调用`nanobanana_get_task`，`task_id=<我的任务ID>`，不要再次生成。”确认成功终态，再打开自己实际返回的媒体URL。任务受理/pending、绿色工具标记或示例链接均不等于最终可播放结果。到Ace Usage/Billing核同一次生成的账单；Cursor和辅助模型费用另计。 + +[截图来源、校验值及复用边界](../assets/tutorial/SOURCES.json)。 + ## 排障 | 现象 | 处理 | @@ -40,3 +70,5 @@ Generate Nano Banana images and retrieve the finished image. 插件复用 [Ace D | 结果无法打开 | 确认终态成功，打开该次调用返回的地址。 | [源码](https://github.com/AceDataCloud/NanoBananaCursor) · [问题反馈](https://github.com/AceDataCloud/NanoBananaCursor/issues) · dev@acedata.cloud。图标复用 Ace Data Cloud 现有集成资源。本插件提供工具，不注册 Cursor 聊天模型 Provider。 + +[注册/登录](https://platform.acedata.cloud/?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_register_signin_zh_hans) · [Applications / API Token](https://platform.acedata.cloud/console/applications?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_api_key_zh_hans) · [当前Nano Banana价格](https://platform.acedata.cloud/models?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=nano_banana_cursor_shared_readme_pricing_zh_hans)