DEV Community: Germey

How to Use NanoBanana MCP in Cursor for Practical Image Editing Workflows

Germey — Fri, 02 Oct 2026 01:05:13 +0000

Long URLs are easy to copy once and surprisingly annoying to manage when a release, newsletter, or launch note contains five of them; this guide shows how to let Codex CLI shorten them without leaving the terminal.

What you are building

The setup is deliberately small: Codex CLI acts as the client, a hosted ShortURL MCP server exposes one tool, and your instruction in the terminal becomes a tool call.

The MCP server documented by Ace Data Cloud is:

https://shorturl.mcp.acedata.cloud/mcp

It exposes a single tool named shorturl_create. That tool handles both individual links and batches, so you do not need separate integrations for a one-off URL and a list of release-note links.

This is a useful first MCP project because the behavior is easy to verify. You provide one or more long URLs, Codex calls the tool, and you inspect the shortened results. There is no complicated agent state, database, or local service to maintain.

Configure the MCP server in Codex CLI

Codex reads MCP server definitions from ~/.codex/config.toml. Open that file in your editor and add the following block:

[mcp_servers.shorturl]
url = "https://shorturl.mcp.acedata.cloud/mcp"
type = "http"

http_headers = { "Authorization" = "Bearer yourToken" }

Replace yourToken with your Ace Data Cloud API token. Keep the Bearer prefix and the space after it: the full value is sent through the Authorization header when Codex connects to the remote MCP server.

A few details are worth noticing:

shorturl is the local name of the MCP server inside Codex. It is descriptive, but it is not the remote tool name.
url points to the hosted MCP endpoint.
type = "http" tells Codex that this is a remote HTTP MCP server.
http_headers carries authentication without putting the token into every prompt.

Save the file, then restart your Codex session. The documentation states that the tool is loaded on the next startup, so changing the TOML while a session is already running may not make it immediately available.

Treat the token like any other credential. Do not paste the completed configuration into an issue, commit it to a dotfiles repository, or include it in a screenshot.

Start with one link

For the first test, use a direct instruction that makes the desired tool obvious:

Shorten this link: https://platform.acedata.cloud

Codex should recognize that the request matches the ShortURL capability and call shorturl_create. Starting with one URL helps separate connection problems from batch-input problems.

If nothing happens, check the basics in this order:

Confirm that the TOML block is in ~/.codex/config.toml.
Confirm the URL is exactly https://shorturl.mcp.acedata.cloud/mcp.
Check that the authorization value begins with Bearer.
Restart Codex after saving the file.
Make the prompt explicit by using the verb “shorten.”

That last point matters in agent workflows. “Prepare this link for sharing” leaves room for interpretation, while “Shorten this link” maps directly to the available tool.

Turn it into a batch workflow

The more practical use case is shortening several links at once. For example, after preparing release notes, you can give Codex a compact task like this:

Shorten these links for a release email:
- https://example.com/releases/2.4.0
- https://example.com/docs/migration-guide
- https://example.com/changelog

Return a Markdown list that keeps each original label next to its short URL.

The documented ShortURL MCP supports batch creation, while Codex can take care of the surrounding formatting. This division of labor is useful: the MCP tool performs the external action, and the model turns the returned values into the shape your workflow needs.

You can use the same pattern for launch checklists, support replies, event resources, or a set of links collected during research. Ask for the final format you actually need—Markdown, a plain-text email section, or a checklist—but keep the URL-shortening action explicit.

Keep the workflow predictable

Tool-enabled terminal workflows are most reliable when the instruction has three parts:

Action: shorten the links.
Input: provide the exact URLs.
Output contract: specify how the results should be organized.

For example:

Shorten the five URLs below. Preserve their order, do not rewrite the titles,
and return a two-column Markdown table with Title and Short URL.

This does not add hidden capabilities to shorturl_create; it simply gives Codex a clear way to present the tool's output. If a URL is malformed, fix the source input instead of asking the agent to guess what you intended.

I like this integration as a first MCP exercise because it solves a real, boring problem with very little machinery: one config block, one remote tool, and a result you can verify immediately. The exact setup and current examples are available in the Codex with ShortURL MCP documentation.

How to Generate and Edit Images from Claude Code with Flux MCP

Germey — Thu, 01 Oct 2026 01:09:00 +0000

A lot of developer work needs small but polished visuals: a cover for a technical post, an illustration for a docs page, or a corrected poster where only one detail changed. The annoying part is that image work often pulls you out of the terminal, even when the rest of the task is already happening in Claude Code.

Flux MCP is a practical way to keep that visual step inside the same coding workflow. You configure one MCP server, verify it once, and then ask Claude Code to generate or edit images with natural language.

What you can do

The Flux MCP setup documented by Ace Data Cloud gives Claude Code two image tools:

Tool	What it does
`flux_generate_image`	Text-to-image generation
`flux_edit_image`	Image editing

The same document describes three Flux model directions you can use from Claude Code:

Dev: fast draft-level exploration when you are not sure about the style yet;
Pro: more detailed image generation after you pick a direction;
Kontext: editing an existing image without regenerating the whole thing.

That maps well to real builder work. You can quickly try a few blog-cover directions, choose one, regenerate it with more detail, and later fix a small piece of text or layout in an existing image.

How it works

Flux MCP is added to Claude Code as an HTTP transport server:

https://flux.mcp.acedata.cloud/mcp

Authentication is passed through a header:

Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY

A local project setup looks like this:

claude mcp add flux --transport http https://flux.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY" \
  -s local

Notice the uppercase -H. In Claude Code, lowercase -h means help, so a tiny flag typo can make the command behave very differently from what you intended.

The documented scopes are:

local: bound to the current project directory;
user: visible across projects on your machine;
project: written into .mcp.json for the current project.

For most experiments, I would start with local. It gives you a low-risk way to test the workflow in one repository before deciding whether it belongs in your global Claude Code setup.

Step 1: Add Flux MCP to Claude Code

From the project where you want to use image generation, run:

claude mcp add flux --transport http https://flux.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY" \
  -s local

If you expect to use Flux across many projects, switch only the scope:

claude mcp add flux --transport http https://flux.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY" \
  -s user

For a team project, you can use project scope:

claude mcp add flux --transport http https://flux.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY" \
  -s project

Be careful with that last option. Project scope writes configuration into .mcp.json in the project root. The config may be useful for a private team repo, but the real token should not be committed to public repositories, issues, screenshots, or chat logs. Use placeholders or have each person add their own token locally.

When Claude Code reads a project-level config for the first time, it may show Pending approval. That is a normal trust prompt, not necessarily a Flux problem.

Step 2: Verify the MCP connection

Before asking for images, check the server status:

claude mcp list

You want flux to show ✓ Connected.

If it fails, check the three most boring things first:

the token after Authorization: Bearer,
the exact server URL, including /mcp,
the scope you used when adding the server.

This is faster than debugging prompts or assuming a model issue. If the MCP handshake is not connected, Claude Code cannot call the tools reliably.

Step 3: Draft image directions with Flux Dev

When the visual direction is unclear, start with fast drafts. The source document gives this example:

Use flux-dev to quickly generate 3 different styles of developer blog cover images, trying flat, realistic, and abstract styles

That is a good pattern because it asks for comparison, not perfection. In a real docs workflow, I would add context from the file I am editing:

Use flux-dev to generate 3 cover directions for this tutorial page. Keep the style technical, dark, and minimal. Try flat, realistic, and abstract variants.

Once you see the directions, pick the strongest one instead of trying to force the first image to be perfect.

Step 4: Refine with Flux Pro

After a draft works, regenerate the chosen direction with more detail. The documented example is:

Use flux-pro to regenerate the second image, increasing details and resolution

This two-step approach is useful because it separates taste decisions from final rendering. You do not spend effort polishing an image direction that might be wrong for the post, README, or landing page.

Step 5: Fix existing images with Kontext editing

Flux MCP is not only for new images. The documented flux_edit_image workflow supports local edits to an existing image. The example is:

Edit this poster image, changing the date in the bottom right corner from 2024 to 2025

For developer content, this can be more useful than full regeneration. You might need to update a date, remove stale text, or adjust a small visual detail without changing the whole composition.

A practical workflow for technical content

Here is the workflow I would use for a real tutorial or release note:

Ask Claude Code to read the Markdown or page that needs an image.
Use flux_generate_image with Dev-style exploration for 2–3 directions.
Pick one direction and ask for a Pro-style refinement.
If something small is wrong later, use flux_edit_image instead of starting over.
Save the final image URL or asset reference back into the Markdown.

The value is not that every visual becomes automatic. The value is that the image task stays close to the code, copy, and context that created the need for the image in the first place.

Final notes

Start with local, verify with claude mcp list, and keep tokens private. Use Dev for exploration, Pro for the final version, and Kontext when an existing image only needs a targeted edit.

The full setup notes are in the official Ace Data Cloud Flux MCP document.

A Practical Guide to Building with the Kimi K3 Chat Completions API

Germey — Wed, 30 Sep 2026 01:05:01 +0000

Reasoning models are useful only when your application can call them predictably, stream partial output, and preserve enough conversation state for follow-up turns.

This guide walks through a small, practical Kimi K3 chat-completion workflow using Ace Data Cloud's Kimi endpoint. We will cover the request shape, the response fields you should actually read, how to enable streaming, and how to pass multi-turn messages without inventing a custom protocol.

What you can do

The Kimi Chat Completion API lets you call the kimi-k3 model through an HTTP API. The documented use cases include ordinary chat completion, streaming responses, multi-turn dialogue, and K3 reasoning intensity control through reasoning_effort.

The important request fields are:

Field	Purpose
`model`	Selects the Kimi model. The guide recommends `kimi-k3`.
`messages`	An array of dialogue messages. Each item has `role` and `content`.
`role`	Supports `user`, `assistant`, `system`, and `tool`.
`reasoning_effort`	Top-level field for K3 reasoning. The supported value is `max`.
`stream`	Set to `true` when you want line-by-line streaming output.

The endpoint used throughout the guide is:

POST https://api.acedata.cloud/kimi/chat/completions

Authentication is sent with a bearer token:

Authorization: Bearer $ACEDATACLOUD_API_KEY

How it works

At the simplest level, you send a JSON body containing the model and a messages array. Kimi returns a Chat Completions-style response with an id, model, choices, and usage.

Here is a minimal request that asks Kimi K3 to review code and provide a fix:

curl https://api.acedata.cloud/kimi/chat/completions \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Review this code and provide a fix"}
    ],
    "reasoning_effort": "max"
  }'

A normal response contains a choices array. The assistant reply is in choices[0].message.content. The usage object reports token counts, including prompt_tokens, completion_tokens, and total_tokens.

A shortened response looks like this:

{
  "id": "msg_2D4Btbg1WgvkNE3tCYkR4xGA",
  "object": "chat.completion",
  "model": "kimi-k3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 86,
    "completion_tokens": 206,
    "total_tokens": 292
  }
}

For a first integration, store the returned id for observability, read choices[0].message, and log usage so you can understand how prompts grow over time.

Use `reasoning_effort` carefully

For kimi-k3, reasoning is always enabled. The documented top-level request field is reasoning_effort, and the supported value is currently max. If you omit the field, the behavior is also max.

That means you should not build application logic that depends on unsupported strings such as standard or high. They may be partially accepted by upstream compatibility layers, but the guide explicitly says not to rely on them changing reasoning behavior.

In Python with an OpenAI-style client, the field can be passed directly:

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Design a reliable task queue"}],
    reasoning_effort="max",
)

For multi-turn dialogues and tool calls, return the complete assistant message from the previous round back into messages, including fields such as reasoning_content and tool_calls when they are present. This keeps the next request faithful to what the model actually produced.

Add streaming for better UX

For a web app or terminal assistant, waiting for the entire response can feel slow. The API supports streaming with stream: true in the JSON body.

import requests

url = "https://api.acedata.cloud/kimi/chat/completions"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
payload = {
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "Hello"}],
    "reasoning_effort": "max",
    "stream": True
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

The streaming response arrives as multiple data: blocks. During the stream, new content appears inside choices[].delta. K3 may stream reasoning_content as well as final content. The stream is complete when the data value is [DONE].

In a UI, treat these chunks as events: append delta.content to the visible answer, optionally handle delta.reasoning_content separately, and stop reading when you receive [DONE].

Keep multi-turn chat simple

You do not need a special session object for a basic multi-turn chat. Send previous turns in the messages array:

{
  "model": "kimi-k3",
  "messages": [
    {"role": "assistant", "content": "Hello! How can I help you today?"},
    {"role": "user", "content": "What model are you?"}
  ],
  "reasoning_effort": "max"
}

The response shape remains the same: inspect choices, read the assistant message, and track usage. As your conversation gets longer, this is also where token usage becomes important. Logging usage.total_tokens early will save you debugging time later.

Handle errors before users see them

The guide documents several error categories worth mapping into clear application messages:

400 token_mismatched: bad request, possibly missing or invalid parameters.
400 api_not_implemented: bad request, possibly missing or invalid parameters.
401 invalid_token: invalid or missing authorization token.
429 too_many_requests: rate limit exceeded.
500 api_error: server-side failure.

A typical error response includes success: false, an error object with code and message, and a trace_id. Log the trace_id; it is the field you will want when investigating a failed request.

A good first build

If I were adding Kimi K3 to an app, I would start with one non-streaming endpoint, log id and usage, then add streaming only after the basic response parser is stable. After that, I would add multi-turn history and make sure the full previous assistant message is preserved.

That order keeps the integration boring: request shape first, response parsing second, streaming third, conversation memory last.

For the original field reference and examples, see the Ace Data Cloud Kimi Chat Completion API guide: https://platform.acedata.cloud/documents/kimi-chat-completion-integration

A Practical Guide to Configuring Claude Desktop with a Third-Party Inference Gateway

Germey — Mon, 28 Sep 2026 01:08:30 +0000

If you use Claude Desktop as a daily coding or research companion, a third-party inference gateway gives you a cleaner way to route model calls while keeping the desktop workflow familiar.

This guide focuses on one specific setup: configuring Claude Desktop’s Third-Party Inference Gateway with Ace Data Cloud. This is not the Claude Code setup, and it is not the MCP Connector configuration inside Claude Desktop. The goal here is narrower: set the gateway fields correctly, restart the app, and verify that Claude Desktop can call models, stream messages, and continue tool calls through the gateway.

What you are configuring

Claude Desktop exposes a developer-mode menu for third-party inference. In that screen, you choose Gateway and provide a base URL, an API key, and an auth scheme.

The values from the Ace Data Cloud guide are:

Claude Desktop field	Value
`Gateway base URL`	`https://api.acedata.cloud`
`Gateway API key`	your Ace Data Cloud API key
`Gateway auth scheme`	`bearer`
`Credential kind`	`Static API key`

Under the hood, the gateway supports /v1/models, Bearer-authenticated streaming /v1/messages, tool calling, and tool_result continuation used by Claude Desktop.

That matters because a simple chat completion is not enough for a desktop assistant. If your workflow uses tools, Claude Desktop needs to send tool calls, receive results, and continue the conversation without breaking the turn.

Step 1: Get an API key

Start by opening the Ace Data Cloud application list, entering an available application, and copying the API key.

Treat the key like any other production credential:

do not paste it into public logs;
do not commit it to a repository;
do not include it in screenshots;
rotate it if you accidentally expose it.

Claude Desktop will store it as a static API key in the gateway configuration.

Step 2: Open Claude Desktop developer mode

On the Claude Desktop login page, open the menu path:

Help → Troubleshooting → Enable Developer Mode

After developer mode is enabled, open:

Developer → Configure Third-Party Inference…

This is the configuration surface you want for this tutorial. If you are looking at Claude Code settings or an MCP connector JSON file, you are in the wrong place for this particular guide.

Step 3: Fill in the gateway settings

In the Third-Party Inference configuration screen, select Gateway and enter:

Gateway base URL: https://api.acedata.cloud
Gateway auth scheme: bearer
Credential kind: Static API key
Gateway API key: YOUR_API_KEY

Then click Apply Changes, followed by Save & Restart.

Do not skip the restart. A common failure mode with desktop integrations is changing a setting, testing immediately, and debugging a stale configuration. Restarting makes the verification step much less ambiguous.

Step 4: Verify with a minimal prompt

After Claude Desktop restarts, select an available model and create a new conversation.

Use a minimal prompt first:

Reply only OK

This checks the basic path before you introduce a larger prompt, files, or tool use. Once that works, perform a small tool task. The gateway documented for this setup supports streaming /v1/messages, tool calling, and tool_result continuation, so a tool task is an important second check.

You can also inspect invocation records in Usage History on the platform side. If something fails, those records are more useful than guessing from the desktop UI alone.

What to check when it fails

Here is the debugging order I would use before changing random settings.

401 errors

A 401 usually means the key is wrong or missing. Recheck that:

the copied API key is complete;
the auth scheme is exactly bearer;
the credential kind is Static API key;
the key was not pasted with extra whitespace.

Do not share the API key when asking for help.

Model not found

If a model cannot be found, recheck the gateway configuration and fully restart Claude Desktop. Since the gateway supports /v1/models, the model list is part of the integration path; a stale desktop state or wrong gateway URL can make this look like a model issue when it is actually a configuration issue.

Tool calls stop after the first call

For agent-like workflows, the continuation step matters. This gateway supports tool calling and tool_result continuation used by Claude Desktop. If a normal prompt works but tool use does not, test a very small tool task and then look at the invocation records for the trace ID.

Prompt caching confusion

The guide notes that prompt caching fields are retained. Cache write and read values both being 0 does not mean that a cache hit occurred. Avoid treating those numbers as proof of caching behavior unless the surrounding usage records support that interpretation.

A practical verification checklist

Before you consider the setup done, run through this short checklist:

Gateway base URL is https://api.acedata.cloud.
Auth scheme is bearer.
Credential kind is Static API key.
Claude Desktop was restarted after applying changes.
A new conversation can answer Reply only OK.
A small tool task completes.
Usage History shows invocation records.
Any support report includes a trace ID, not an API key.

Closing thoughts

The biggest trick with desktop AI configuration is knowing which layer you are editing. For this workflow, stay in Claude Desktop’s Third-Party Inference Gateway screen, keep the gateway values minimal, restart before testing, and verify both plain messages and tool continuation. The full Ace Data Cloud setup notes are here: https://platform.acedata.cloud/documents/claude-desktop-gateway-integration

How to Add Short Link Workflows to Claude Code with MCP

Germey — Sun, 27 Sep 2026 01:06:35 +0000

Long links are a tiny annoyance until they show up everywhere: PR descriptions, commit messages, README files, release notes, Slack threads, and internal docs. The practical goal of this guide is simple: let Claude Code shorten links from the terminal while you are already working on the surrounding text.

ShortURL MCP is a small but useful example of what Model Context Protocol tools are good at. It does not try to replace your editor or your coding agent. It gives Claude Code one focused capability: turn long links into cleaner https://surl.id/xxxxx links, including batch workflows for multiple URLs.

What you can do

After connecting the ShortURL MCP server, Claude Code can call link-shortening tools from a normal terminal session. The source document describes several everyday scenarios:

shortening an issue or document link before putting it into a commit message;
replacing multiple long external links in a README;
preparing friendlier links before sending them to non-technical teammates;
asking Claude Code to handle the link cleanup while it is already editing nearby Markdown.

The MCP server exposes these tools:

Tool	Purpose
`shorturl_create`	Generate one short link
`shorturl_batch_create`	Generate multiple short links at once
`shorturl_get_api_info`	Get API information
`shorturl_get_usage_guide`	Get the usage guide

The important thing is not the short link itself. It is the workflow placement. If Claude Code is already drafting a PR description or editing a README, link shortening becomes one more tool call instead of a browser detour.

How it works

ShortURL is exposed as a remote MCP server. Claude Code connects to it over HTTP, and your Ace Data Cloud API token is provided through the Authorization header.

The setup fields from the documentation are:

MCP server URL: https://shorturl.mcp.acedata.cloud/mcp
Transport: http
Authorization header: Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY
Claude Code command: claude mcp add
Verification command: claude mcp list
Expected server name after setup: shorturl

The documentation shows three configuration scopes: local, user, and project. Use local for a single project, user if you want the server available across projects, and project if a private team repository should carry the MCP configuration.

Configure it locally first

For a first run, I prefer the local scope. It keeps the setup attached to the current project directory and avoids changing your global Claude Code configuration.

claude mcp add shorturl --transport http https://shorturl.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY" \
  -s local

Two details are easy to miss:

-H must be uppercase. Lowercase -h means --help.
Keep the full header format: Authorization: Bearer ....

After adding the server, verify that Claude Code can see it:

claude mcp list

If shorturl shows ✓ Connected, the MCP handshake worked. If it does not, check the token, the server URL, and the scope before changing anything else.

Use it in a PR or commit workflow

Imagine you are writing a commit message that references a long issue URL. Instead of manually opening a URL shortener, ask Claude Code directly:

Shorten this issue link; I want to put it in the commit message.

Claude Code can then call shorturl_create and return a compact link in the https://surl.id/xxxxx format described by the docs. The result is easier to scan in terminal output, commit bodies, chat messages, and changelog drafts.

This is a good fit for links that are useful but noisy: GitHub issue filters, permanent line references, documentation pages with tracking parameters, or internal tools that generate very long URLs.

Batch-clean links in Markdown

The more interesting workflow is batch cleanup. The docs describe shorturl_batch_create for shortening multiple links at once. That maps naturally to README and release-note maintenance.

A useful prompt is:

Help me replace all long external links in the README with short links.

In a real project, I would make that instruction more constrained:

Find external links in README.md that are longer than 100 characters. Use shorturl_batch_create to shorten them, then update the Markdown while keeping the link text unchanged.

That keeps the content readable while reducing link noise. It also gives Claude Code a clear editing rule: change the URL target, not the surrounding prose.

Choose the right scope

Use local when you are testing or when only one repository needs short links.

Use user when shortening links is part of your personal writing workflow across projects. The documentation notes that user-level configuration is written into the local ~/.claude.json, so projects opened later can see it.

Use project for team workflows, but be careful with secrets. The documentation says project-level configuration is written into .mcp.json in the project root. That can be useful in a private repository, but the real token should not be committed to a public repo. The first time Claude Code reads project-level configuration, it may show Pending approval; you need to trust that configuration inside the session.

Final notes

ShortURL MCP is intentionally small, which is why it is a good first MCP workflow to try in Claude Code. It has a clear input, a clear output, and a practical place in daily engineering writing. Start with local, verify with claude mcp list, and then use shorturl_create or shorturl_batch_create only where shorter links make the surrounding text easier to read.

The original Ace Data Cloud setup reference is here: Claude Code with ShortURL MCP.

A Practical Guide to Generating Short Videos with the Seedance API

Germey — Sat, 26 Sep 2026 01:03:03 +0000

If you have ever tried to turn a prompt, product idea, or reference image into a short video clip, the tricky part is often not the creative brief. It is getting the API shape right: which model supports which reference type, how image_url is formatted, and where the finished video URL appears.

This guide walks through a practical Seedance video generation workflow on Ace Data Cloud. We will send text and reference inputs to one endpoint, choose output settings, and read the video_url from the result.

What you can do

The Seedance Videos API supports a few useful builder workflows:

text-to-video with a plain prompt
image-to-video with a first frame, or first and last frames
multimodal references with images, audio, or video
optional audio generation on supported models
asynchronous jobs through callback_url or async: true
Seedance 2.5 video editing and extension with reference_video

The endpoint is:

POST https://api.acedata.cloud/seedance/videos

The request headers are:

authorization: Bearer ${bearer_token}
accept: application/json
content-type: application/json

The core body field is content, an array of typed inputs. Each item can be text, image_url, audio_url, or video_url. Image entries may also use roles such as first_frame, last_frame, or reference_image.

A minimal text-to-video request

A basic request needs a model, a prompt in content, and output settings such as resolution, ratio, and duration. For a quick 720p test, the documented example uses doubao-seedance-2-0-fast-260128:

curl -X POST 'https://api.acedata.cloud/seedance/videos' \
  -H 'authorization: Bearer ${bearer_token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "content": [
      {
        "type": "text",
        "text": "A white ceramic coffee mug on a glossy marble countertop with soft morning window light. The camera slowly orbits 360 degrees around the mug, steam gently rising."
      }
    ],
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

A successful response includes success, task_id, trace_id, and a data object. The useful delivery field is usually data.video_url:

{
  "success": true,
  "task_id": "9777f36b-4f44-47ff-962d-45cd2f7aeaa8",
  "trace_id": "ce5da2ca-6695-4459-9d2c-2ef9f86db752",
  "data": {
    "status": "succeeded",
    "model": "doubao-seedance-2-0-fast-260128",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "video_url": "https://cdn.acedata.cloud/assets/examples/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152-102bf9f98e35.mp4"
  }
}

Keep task_id and trace_id in your logs. They are useful when debugging failed jobs or correlating callbacks.

Choose model features intentionally

The model value determines which options are valid. The Seedance 1.x series includes models such as doubao-seedance-1-0-pro-250528 and doubao-seedance-1-0-lite-i2v-250428. The 2.0 series includes doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, and doubao-seedance-2-0-mini-260615. Seedance 2.5 uses doubao-seedance-2-5-260628.

Some fields are model-specific. generate_audio is supported by Seedance 1.5 Pro and the 2.x series, but not by the 1.0 series:

{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {
      "type": "text",
      "text": "A girl holds a fox, the wind blows her hair, you can hear the sound of the wind"
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 5
}

For Seedance 2.5, omni_reference_task_type can be auto, reference, edit, or extend. Version 2.5 supports output_format as mp4 or mov, and supports duration from 4 to 30 seconds or -1 where automatic duration is allowed.

Add reference images without 400 errors

For image-to-video, image_url must be an object with a url field. Passing a raw string is not supported.

Correct:

{
  "type": "image_url",
  "image_url": {
    "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
  }
}

A simple Python request can combine that image with a prompt:

import requests

url = "https://api.acedata.cloud/seedance/videos"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
payload = {
    "content": [
        {
            "type": "image_url",
            "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"}
        },
        {
            "type": "text",
            "text": "A girl holds a fox in her arms. As the camera slowly pulls away, her hair is gently blown by the wind. --ratio adaptive --dur 5"
        }
    ],
    "model": "doubao-seedance-1-0-pro-250528"
}
print(requests.post(url, json=payload, headers=headers).text)

If you need strict first and last frames, use two image_url items and set role to first_frame and last_frame.

Multimodal references and validation

Seedance 2.0 supports reference_image, reference_audio, and reference_video. This helps when you want consistency in a subject, action, rhythm, or camera motion.

Useful validation rules to add before sending the request:

Do not mix first_frame / last_frame with reference_image, reference_audio, or reference_video.
Seedance 2.0 supports up to 9 reference images.
Reference audio should be wav or mp3, 2–15 seconds per item, up to 3 items, and no more than 15 seconds total.
Reference video should be mp4 or mov, 2–15 seconds per item, up to 3 items, and no more than 15 seconds total.

A clean production flow is: create an internal job, submit async: true or a callback_url, store task_id and trace_id, then persist data.video_url when the task succeeds. That keeps the model call separate from your UI and gives you enough metadata to retry or inspect failures.

For the full parameter table and additional examples, see the Seedance Videos API Integration Guide.

How to Configure Cline in VS Code with an OpenAI-Compatible Endpoint

Germey — Fri, 25 Sep 2026 01:05:29 +0000

Sometimes the fastest way to test a coding model is not to write a new integration, but to plug it into a tool you already use every day: VS Code.

This guide walks through a practical setup for using Cline with Ace Data Cloud through Cline's OpenAI Compatible provider. The goal is simple: configure the provider, verify the model can reply, and then confirm that file-oriented agent work is possible before you trust it on a real task.

What you can do

Cline is a VS Code extension for agent-style coding tasks. In this setup, Ace Data Cloud is used as the OpenAI-compatible endpoint behind Cline. The documented configuration is intentionally small:

Field	Value
API Provider	`OpenAI Compatible`
Base URL	`https://api.acedata.cloud/v1`
API Key	The API Key copied from the Ace Data Cloud application
Model ID	The model ID currently provided by the Coding Plan
Custom Headers	Leave blank
Set Azure API version	Leave blank
Use Azure Identity Authentication	Disabled

This is enough to route Cline's model calls to the selected Coding Plan model without adding custom headers or Azure-specific settings.

How it works

The setup has three moving parts:

An API Key from an Ace Data Cloud application.
Cline's OpenAI Compatible provider in VS Code.
A model ID from the Coding Plan model directory.

The Base URL is the important fixed value:

https://api.acedata.cloud/v1

The API Key is copied from the application list in the Ace Data Cloud console. The Model ID should match a model currently available in the Coding Plan. Keep the other provider fields unchanged unless you have a model-specific reason to adjust them later.

Step 1: get the API Key

Open the Ace Data Cloud application list and enter an available application. Copy the API Key from that application.

Avoid putting this key in screenshots, public issues, shared repos, or example files. In documentation and team notes, use a placeholder such as:

YOUR_ACEDATACLOUD_API_KEY

For Cline itself, paste the real value into the provider configuration field. The docs do not require a custom header for this setup, so keep Custom Headers blank.

Step 2: configure Cline in VS Code

Install and open Cline in VS Code. In the Cline panel, open the provider settings and fill in the fields from the guide:

API Provider: OpenAI Compatible
Base URL: https://api.acedata.cloud/v1
API Key: <your copied API Key>
Model ID: <Coding Plan model ID>
Custom Headers: <blank>
Set Azure API version: <blank>
Use Azure Identity Authentication: Disabled

For a first pass, keep the remaining model capability settings at their defaults. The guide recommends adjusting those later only when you need image support or a larger context, and only according to the actual capabilities of the selected model.

That order matters. First prove basic chat and tool behavior. Then tune model-specific capability switches.

Step 3: verify basic model access

After saving the provider configuration, create a new Cline task and send:

Reply only OK

This is a small but useful smoke test. If the provider is configured correctly, the model should respond with just OK. If that fails, do not start debugging agent behavior yet. Fix connectivity first.

The guide gives two common failure patterns:

401 usually means the Key is incorrect.
404 usually means the Base URL or Model ID is incorrect.

So if you see a 401, re-copy the API Key from the application. If you see a 404, check that the Base URL is exactly https://api.acedata.cloud/v1 and that the Model ID matches the model you intended to use.

Step 4: verify file-oriented agent behavior

A chat response proves the endpoint is reachable, but Cline is most useful when it can work with your project files. After the Reply only OK smoke test passes, ask Cline to read a simple test file in the current workspace.

For example:

Read the README file in this workspace and summarize its main setup steps.

If the model can chat but cannot operate on files, the guide recommends checking whether the selected model supports tool calling. This is a different class of problem from API credentials. A valid endpoint and key do not automatically mean every model has the same agent capabilities.

You can also review call records in Usage History in the Ace Data Cloud console. That gives you a practical place to confirm requests are reaching the platform while you test different model IDs.

A practical debugging checklist

When configuring a coding agent, it is easy to change too many variables at once. I would debug this setup in the following order:

Confirm API Provider is OpenAI Compatible.
Confirm Base URL is exactly https://api.acedata.cloud/v1.
Re-paste the API Key if you see 401.
Re-check the Model ID if you see 404.
Send Reply only OK before trying file edits.
If chat works but file operations do not, check the selected model's tool calling capability.
Only then adjust optional model capability settings such as image support or larger context.

This keeps the setup boring, which is what you want from infrastructure inside an editor.

When this setup is useful

This workflow is especially handy if your team already uses VS Code and wants a quick way to compare Coding Plan models inside a real coding assistant. You can start with a minimal provider configuration, run a tiny smoke test, and then graduate to repository-aware tasks once the model and tool calling behavior are confirmed.

The full Ace Data Cloud setup reference for Cline is here: https://platform.acedata.cloud/documents/cline-vscode-integration

How to Add AI Music Generation to Gemini CLI with Suno MCP

Germey — Thu, 24 Sep 2026 01:08:59 +0000

If you already use Gemini CLI as a terminal assistant, the next useful step is not another chat window. It is giving that same terminal session a few real tools, so it can help you produce assets while you are still in the flow of building.

This guide shows how to add Suno MCP to Gemini CLI through Ace Data Cloud. The practical result is simple: from a Gemini CLI conversation, you can ask for a short song, background music, lyrics, a cover, or an extension of an existing track.

What you can do

The source document describes a remote MCP server for Suno. Once it is configured in Gemini CLI, the assistant can call Suno-related tools from natural language prompts instead of making you switch to a separate UI.

The documented MCP endpoint is:

https://suno.mcp.acedata.cloud/mcp

Authentication is passed with an HTTP header:

Authorization: Bearer yourToken

The tool list in the document includes:

Tool	What it is for
`generate`	Generate a song from a description
`custom`	Generate a song with custom lyrics and style
`extend`	Extend an existing song
`cover`	Cover a song in a new style
`lyrics`	Generate lyrics only
`upload_to_persona`	Register a Persona with vocal audio
`query`	Query historical generation results

That is enough for a practical builder workflow: write a tutorial, app demo, or game prototype, then create a matching audio draft without leaving the terminal.

How it works

Gemini CLI supports MCP servers. An MCP server is a tool provider that the model can call when it decides a task needs an external capability. In this case, the tool provider is the Suno MCP server hosted behind Ace Data Cloud.

The configuration has two parts:

the remote MCP URL
the authorization header that carries your Ace Data Cloud token

The one-command setup from the document is:

gemini mcp add suno \
  --transport http \
  https://suno.mcp.acedata.cloud/mcp \
  --header "Authorization: Bearer yourToken"

Use a real token locally, but keep examples and documentation in the yourToken form. Tokens should not be committed to a repository, pasted into public issues, or embedded in screenshots.

Alternative: edit the Gemini settings file

If you prefer declarative configuration, the document also shows a ~/.gemini/settings.json entry. This is useful when you want a repeatable setup that is easy to review.

{
  "mcpServers": {
    "suno": {
      "httpUrl": "https://suno.mcp.acedata.cloud/mcp",
      "headers": { "Authorization": "Bearer yourToken" }
    }
  }
}

After saving the file, restart your gemini session so the MCP server is loaded. I usually prefer starting with the CLI command for a quick test, then moving to the settings file once I know the endpoint and token are correct.

Try a few useful prompts

Once the server is mounted, the interaction can stay high level. You describe the musical goal, and Gemini CLI can choose the relevant Suno tool.

For a short social or product demo asset:

Help me write a 30-second upbeat Chinese pop song with the theme "Camping with friends on the weekend."

For background music under a screen recording:

Use Suno to create a lofi hip hop BGM for a programming tutorial video, without vocals.

For iterating on an existing track:

Extend this song (link xxx) from 30 seconds to 90 seconds, maintaining the original melody style.

These are intentionally specific. “Make some music” is hard to evaluate. “30-second upbeat Chinese pop song,” “lofi hip hop BGM,” and “extend from 30 seconds to 90 seconds” give the tool enough context to produce something you can review.

A practical workflow for builders

A small but useful workflow looks like this:

Write the script or demo flow in your project.
Ask Gemini CLI to summarize the mood and pacing of the content.
Turn that summary into a Suno prompt.
Generate one or two drafts.
If a draft is close, use extend or cover instead of starting over.
Use query when you need to check previous generation results.

The key is to treat audio generation like an iteration loop, not a one-shot command. The first output tells you what to clarify: vocals or no vocals, duration, genre, language, and whether the piece should sit under narration or stand on its own.

When I would use each tool

Use generate when you have a style description but no lyrics. This is a good fit for BGM, short loops, or mood boards.

Use custom when the words matter. If your demo video has a theme, tagline, or narrative arc, write or generate lyrics first, then pass the lyrics plus a style direction.

Use lyrics when you are still drafting the concept. It lets you separate writing from audio production.

Use extend when the first result is directionally right but too short. This is common for tutorial intros, product walkthroughs, and background tracks.

Use cover when the composition is useful but the style is not. Instead of discarding the idea, try a new style pass.

Use upload_to_persona only when you have appropriate rights to the vocal audio you are registering. That is an implementation detail, but it is also an important product boundary.

Keep the integration boring

For production or team usage, keep the setup boring and explicit. Store the token outside version control, document the MCP URL, and write down which prompts produce good results for your content style. If multiple people use the same workflow, standardize a few prompt templates so outputs are easier to compare.

This is where MCP feels natural: Gemini CLI stays the workspace, while Suno becomes one callable capability inside that workspace. You do not need a giant automation system to benefit from it; even a single terminal command plus a few disciplined prompts is enough to make the workflow useful.

You can read the original setup notes here: Gemini CLI with Suno MCP.

How to Track Async Image Generation Jobs with the Seedream Tasks API

Germey — Wed, 23 Sep 2026 01:06:32 +0000

Generating an image is only half of the integration. In a real product, you also need to know whether the job finished, how long it took, which prompt produced the result, and where the final image URL lives.

This guide shows how to build that job-tracking layer with the Seedream Tasks API. The workflow is intentionally simple: start an image generation request elsewhere, save the returned task ID, then query task status until you have a stable result.

What you can do

The Seedream Tasks API is designed to retrieve execution details for tasks created by the Seedream Images Generation API.

The documented task endpoint is:

Base URL: https://api.acedata.cloud
Endpoint: POST /seedream/tasks
Auth header: authorization: Bearer {token}
Accept header: accept: application/json
Content type: content-type: application/json

The request body changes depending on whether you are looking up one task or multiple tasks:

Single task: id plus action: "retrieve"
Batch lookup: ids plus action: "retrieve_batch"

That makes the API a good fit for backend queues, admin dashboards, cron-based polling, or any UI where users can return later and see whether their generated image is ready.

Store the task ID first

When your image-generation call returns, persist the task ID immediately. The Seedream image response documented by Ace Data Cloud includes fields such as success, task_id, trace_id, and data. The task API uses that task ID as the lookup key.

A minimal table for your own app might look like this:

image_jobs
- id
- provider_task_id
- trace_id
- prompt
- status
- output_image_url
- created_at
- finished_at
- elapsed

The exact database does not matter. What matters is that provider_task_id stores the value you will later send as id to /seedream/tasks.

Retrieve one task

For a single job detail page, query one task by ID. The request body contains the task id and an action value of retrieve.

curl -X POST 'https://api.acedata.cloud/seedream/tasks' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "id": "a6e0d456-189b-4c78-9232-2fe72166ab39",
    "action": "retrieve"
  }'

A successful response can include the generated result directly:

{
  "success": true,
  "task_id": "84d1544a-9043-4dde-a98b-e889dacd75f6",
  "trace_id": "176acf03-7ca7-4fc6-85db-e3724d4f59eb",
  "data": [
    {
      "prompt": "a white siamese cat",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/6e5f9085-cc4a-4801-b77b-31550129ff19.jpg"
    }
  ]
}

For a user-facing UI, the important field is data[].image_url. Once that is present, you can mark your local job as complete and render the image. Keep trace_id too; it is useful when debugging a failed or unexpected task.

Retrieve many tasks at once

Single-task polling is fine for a detail page. For an admin dashboard or worker process, batch retrieval is more efficient. The body uses ids and action: "retrieve_batch".

{
  "ids": [
    "84d1544a-9043-4dde-a98b-e889dacd75f6",
    "84d1544a-9043-4dde-a98b-e889dacd75f6"
  ],
  "action": "retrieve_batch"
}

The documented batch response contains an items array and a count. Each item includes task metadata such as id, api_id, application_id, created_at, started_at, finished_at, elapsed, credential_id, request, trace_id, type, user_id, and response.

That structure is useful because you can update local records in one pass:

for item in response.items:
    job = find_job_by_provider_task_id(item.id)
    job.trace_id = item.trace_id
    job.started_at = item.started_at

    if item.finished_at exists:
        job.finished_at = item.finished_at
        job.elapsed = item.elapsed
        job.status = "finished"
        job.output_image_url = item.response.data[0].image_url

The documentation notes that finished_at and elapsed are not returned if the task is not complete. That is a clean signal for your polling loop: if finished_at is missing, leave the job in a running state and check again later.

A practical polling loop

A basic backend loop can be conservative:

Insert a local job before or immediately after creating the image task.
Save the returned task_id as provider_task_id.
Poll /seedream/tasks with action: "retrieve" for one item, or retrieve_batch for many pending jobs.
If finished_at exists, copy elapsed and response.data[0].image_url into your database.
If an error comes back, store the error.code, error.message, and trace_id.

The task API is especially helpful when you do not want to expose provider-specific details to your frontend. Your frontend can call your own /jobs/:id endpoint, while your backend handles the Ace Data Cloud task lookup.

Error handling

The documented error examples include:

400 token_mismatched
400 api_not_implemented
401 invalid_token
429 too_many_requests
500 api_error

A failed response follows this shape:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

In practice, handle these as job states rather than raw exceptions. A 401 means the integration needs configuration. A 429 should trigger backoff. A 500 should be stored with the trace ID so the job can be retried or inspected.

Where this fits in an app

This pattern works well for tools where users do not expect instant completion: image editors, CMS media libraries, ecommerce asset tools, internal creative review systems, or batch generation scripts.

The main idea is to separate creation from retrieval. The image generation endpoint starts the work; the task endpoint gives your application a reliable way to observe it.

For the complete field reference and examples, see the source document: Seedream Tasks API integration guide.

How to Add Seedream Image Tools to Gemini CLI with MCP

Germey — Mon, 21 Sep 2026 01:03:51 +0000

Voice cloning demos often skip the part that determines whether the result is usable: preparing a clean source recording and carrying the returned identity into the generation request correctly. This guide walks through that small but important pipeline, from a WAV or MP3 sample to a song generated with its private voice character.

What you are building

The workflow has two API calls against the base URL https://api.acedata.cloud:

POST /suno/voices accepts a public audio_url and creates a voice character.
POST /suno/audios accepts the resulting persona_id together with a music prompt and a supported model.

The handoff between those calls is the key design detail. The cloning response also contains a generated name, but your application should store and reference persona_id. Uploaded voice characters are private resources, and they cannot be reused across accounts.

Before implementing this, make consent part of the product flow. Only clone a voice you own or have explicit permission to use. That is not an API parameter, but it is a sensible boundary for any real application involving someone’s identity.

Step 1: prepare a source recording that can pass verification

The voice endpoint accepts a publicly accessible audio_url pointing to a WAV or MP3 file. The supported duration is 10–240 seconds, while the practical recommendation is a clean 30–60 second sample.

More audio is not automatically better. A short dry recording with one recognizable speaker or singer is preferable to a finished song. Avoid accompaniment, background noise, echo, reverb, multiple speakers, low volume, and unclear speech. Those conditions can cause cloning to fail or reduce the quality of later generations.

In production, I would validate the file format and duration before submitting the request. I would also tell the user why a studio-like dry sample matters rather than returning a generic error after a long upload.

Step 2: create the private voice character

Send the source file URL in audio_url. The name and description fields are optional.

curl -X POST 'https://api.acedata.cloud/suno/voices' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "audio_url": "{public_wav_or_mp3_url}",
    "name": "My Voice",
    "description": "Single clear voice example"
  }'

A successful response follows this shape:

{
  "success": true,
  "task_id": "0fa609a6-c8d9-4bb5-8574-e4c93bb55d02",
  "data": {
    "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16",
    "name": "VOICE_20260803037676",
    "is_public": false
  }
}

Persist data.persona_id; do not treat the generated name as the stable reference. The is_public value is false for a voice character created from uploaded audio.

Voice cloning is compute-intensive, so a compliant sample can occasionally return a failure such as voices_sound_different. The integration guidance recommends one or two automatic retries, including when retrying the same material. Keep that retry policy bounded: record the failure, retry briefly, and then ask for a cleaner sample instead of hiding a persistent input problem. Failed requests are not charged according to the integration document.

Step 3: generate music with the cloned voice

Pass the stored identifier to the audio generation endpoint. Set action to generate, include a text prompt, and choose a compatible model. Voice cloning works with chirp-v4-5 and later models such as chirp-v5 and chirp-v5-5; it does not support chirp-v4.

curl -X POST 'https://api.acedata.cloud/suno/audios' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "model": "chirp-v5-5",
    "prompt": "A warm synth-pop song about city nights",
    "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16"
  }'

The returned data is an array. Each generated item can include fields such as id, title, audio_url, image_url, model, state, prompt, and duration. For an application, I would wait for state to be succeeded before exposing audio_url, and keep the original prompt beside the result so users can understand what produced it.

The same persona_id can also be used with the cover action, but starting with generate keeps the first integration easy to reason about: one owned source voice, one stored identifier, and one explicit music prompt.

A small production checklist

Validate WAV or MP3 and the 10–240 second duration range before calling the API.
Prefer a 30–60 second dry, single-voice sample.
Send bearer authentication in the authorization header.
Store persona_id, not the automatically generated voice name.
Use chirp-v4-5 or a later supported model.
Limit cloning retries to one or two attempts and surface actionable feedback.
Keep the voice resource and generated output tied to the account that created them.

What I like about this workflow is that it stays understandable: the first request creates an identity token, and the second uses that token as one input to generation. If you are implementing it yourself, keep the consent and audio-quality checks as visible as the API calls; the full field-level reference is in the Ace Data Cloud voice cloning integration guide.

How to Add NanoBanana Image Editing to Claude Code with MCP

Germey — Sun, 20 Sep 2026 01:04:15 +0000

If your coding agent can write the feature but you still leave the terminal to make screenshots, page illustrations, or product mockups, MCP is a practical way to close that loop.

What you can do

NanoBanana is useful when the image task depends on understanding an existing image, not just generating something from scratch. In the Ace Data Cloud documentation, the examples are deliberately developer-friendly: put a phone from one image onto a desk in another image, remove a text watermark from an image, or generate an illustration for a 404 page.

The workflow is simple: configure a remote MCP server once, then ask Claude Code for image work in natural language while it is already inside your project. The two exposed tools are:

Tool	What it does
`nanobanana_generate_image`	Text-to-image generation
`nanobanana_edit_image`	Image editing with support for multiple image inputs

The most important configuration details are:

MCP server URL: https://nanobanana.mcp.acedata.cloud/mcp
Transport: http
Auth header: Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY
Claude Code command: claude mcp add nanobanana
Verification command: claude mcp list

A small but important detail: the docs call out that -H must be uppercase. Lowercase -h is interpreted as help, which is exactly the kind of tiny CLI mistake that makes MCP setup feel more mysterious than it really is.

How it works

Claude Code can read your repo, modify files, and run commands. MCP adds external tools to that same terminal-centered session. In this case, the external tool is NanoBanana, an image generation and editing MCP server backed by Google's Gemini image-understanding capabilities.

You do not run the server locally. You register the remote MCP endpoint with Claude Code and pass an Ace Data Cloud API token through an HTTP authorization header. After that, Claude Code can discover the nanobanana_* tools and call them when your prompt asks for image generation, image editing, or multi-image composition.

That makes the pattern feel natural for builder workflows. You can work on a landing page, ask for a matching 404 illustration, save the generated asset, and keep going without switching contexts.

Step 1: Get an API token

The documentation says to open the Ace Data Cloud console application list and copy an API token. Keep the real token out of public repos, screenshots, issues, and chat logs. In examples, use a placeholder like this:

YOUR_ACEDATACLOUD_API_KEY

One token can be used across Ace Data Cloud MCP servers, so you do not need a separate token just for NanoBanana.

Step 2: Add the MCP server to Claude Code

For a quick trial in the current project, use the local scope:

claude mcp add nanobanana --transport http https://nanobanana.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY" \
  -s local

Use local when you are testing the setup in one repo. Claude Code writes the record into your local ~/.claude.json together with the current project path.

If you expect to use NanoBanana from many projects, use the user-level scope:

claude mcp add nanobanana --transport http https://nanobanana.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY" \
  -s user

For team projects, there is also a project-level option:

claude mcp add nanobanana --transport http https://nanobanana.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY" \
  -s project

The project scope writes configuration into .mcp.json in the project root. That can be useful for private team repositories, but do not commit a real token. Use a placeholder or let each teammate add their own local secret.

Step 3: Verify the connection

After adding the server, run:

claude mcp list

A healthy setup should show nanobanana as ✓ Connected. If it does not, check three things before changing anything else: the token, the remote service URL, and the scope you used when adding the server.

Step 4: Use it in real project tasks

Once connected, you can ask Claude Code for image work the same way you ask it for code changes.

For multi-image composition:

Use NanoBanana to place the phone from the first image onto the desk in the second image. Match the angle and lighting so it looks natural.

For cleanup work:

Edit this image to remove the text watermark in the lower-right corner, filling the area with the surrounding background.

For a small web asset:

Generate an illustration of a small dinosaur squatting next to a crack in the ground, looking down. Use it as a 404 page illustration.

The point is not to replace design judgment. It is to keep asset iteration close to the code. When you are building a docs page, prototype, README, or empty state, the fastest useful image is often the one you can request without leaving the terminal.

A few practical notes

Start with local until you confirm that the server connects. Move to user only when you know you want it available across projects. Use project when the configuration itself is part of how your team works, and treat secrets carefully.

Also, avoid hardcoding assumptions about the number of tools or older client behavior. The docs recommend checking the current connection state with claude mcp list rather than relying on memory.

If you want the exact setup reference, the Ace Data Cloud guide is here: https://platform.acedata.cloud/documents/claude-code-mcp-nano-banana

A Practical Guide to Generating Music from VS Code with MCP

Germey — Thu, 17 Sep 2026 01:05:42 +0000

You finish recording a programming walkthrough, play it back, and realize the tutorial is just your voice plus keyboard noise. Instead of breaking flow to hunt for background music, you can ask your editor agent to create a track from inside VS Code.

This guide walks through the documented VS Code + Suno MCP setup: install the MCP extension, store the API key safely, verify it from GitHub Copilot Agent mode, and keep a manual .vscode/mcp.json fallback for teams that prefer explicit project configuration.

What you can do

The document describes a Suno MCP workflow for VS Code. The main use case is simple: let GitHub Copilot Chat in Agent mode call Suno tools while you are still working in the editor.

The extension ID is:

acedatacloud.mcp-suno

The MCP server URL used by the optional manual config is:

https://suno.mcp.acedata.cloud/mcp

The Authorization header follows this shape:

Authorization: Bearer ${input:acedata-api-key}

The documented tools include:

Tool	What it is for
`suno_generate_music`	Generate a complete song from a one-sentence description
`suno_generate_custom_music`	Use your own lyrics, style, and vocal type
`suno_extend_music`	Continue a song from a specific time point
`suno_cover_music`	Cover an existing song in a different style
`suno_mashup_music`	Mash two songs into one
`suno_stems_music`	Separate vocals and accompaniment
`suno_generate_lyrics`	Generate lyrics
`suno_create_persona`	Save voice styles

That is enough to support practical builder workflows: background music for a tutorial, a short intro for a demo video, or fast iteration on game and podcast audio ideas.

Install the VS Code extension

Start with the extension path if you want the least configuration surface.

Open the VS Code extension marketplace with Cmd+Shift+X.
Search for Suno MCP, or search directly for the extension ID acedatacloud.mcp-suno.
Click Install.
Reload the VS Code window if prompted.

The key point is that the MCP integration lives where you are already working. You do not need to run a separate local MCP server process for this documented path.

Store the API key safely

After installing the extension, open the command palette with Cmd+Shift+P and run:

Suno MCP: Set Ace Data Cloud API Key

Paste your Ace Data Cloud API key and press Enter. The document says the key is stored in VS Code SecretStorage / the system keychain, not written into your project files.

If you need to rotate or replace it later, run:

Suno MCP: Clear Ace Data Cloud API Key

Then set the key again. This is a good habit if you test with temporary credentials, move between machines, or accidentally paste the wrong key.

Verify it from Copilot Agent mode

Open GitHub Copilot Chat and switch to Agent mode. Then ask for a task that clearly mentions suno, for example:

Use suno to help me generate a light and cheerful background music track for a programming tutorial, with a steady rhythm that does not distract from narration.

The first call should route through the plugin and use the saved API key. For a short demo video, you might ask:

Generate a 20-second sci-fi opening music, primarily with electronic synthesizers, powerful but not noisy.

For a podcast or branded intro, use the custom-music path:

Help me generate a song with custom lyrics. Lyrics: The moment the compilation passed, the world suddenly fell silent. Style: Lo-fi hip hop, lazy atmosphere.

The practical pattern is to describe the job as you would describe it to an editor: duration, mood, role in the video, and what the track should avoid. “Background music for narration” is a very different prompt from “energetic product launch intro.”

Optional: keep a manual `.vscode/mcp.json`

If you prefer project-level configuration, the document also shows a manual MCP config. Create .vscode/mcp.json and use an input prompt for the key instead of hardcoding the secret:

{
  "servers": {
    "suno": {
      "type": "http",
      "url": "https://suno.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${input:acedata-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "acedata-api-key",
      "type": "promptString",
      "description": "Ace Data Cloud API Key",
      "password": true
    }
  ]
}

This version is useful when you want the MCP server definition to travel with a private repository while still asking each developer to provide their own key. The important part is the ${input:acedata-api-key} placeholder: it keeps the real value out of Git.

Useful workflows to try

Here are three concrete ways I would use this in a builder workflow.

1. Add quiet BGM to a coding tutorial

Ask for a light, steady, non-distracting track. Mention narration explicitly. If the first version feels too busy, ask for less percussion or a slower rhythm.

2. Create a short demo-day intro

For a product demo, ask for a 20-second opener and specify instrumentation. The document's example uses electronic synthesizers and a powerful-but-not-noisy direction, which is a good constraint for a tech demo.

3. Iterate on an existing track

If a section works but the energy drops later, use suno_extend_music conceptually through Copilot:

Continue this song starting from 01:40, speed up the rhythm, and add more beats and orchestral crescendos.

This is where editor-native generation feels useful: you can keep notes, scripts, and prompts in the same workspace as the video or tutorial project.

Wrap-up

The smallest useful path is: install acedatacloud.mcp-suno, set the API key from the command palette, switch Copilot Chat to Agent mode, and make one narrow request for a real piece of background music. If your team prefers explicit config, use .vscode/mcp.json with a password input instead of committing secrets.

The full setup details are in the VS Code with Suno MCP documentation.

DEV Community: Germey

How to Use NanoBanana MCP in Cursor for Practical Image Editing Workflows

What you are building

Configure the MCP server in Codex CLI

Start with one link

Turn it into a batch workflow

Keep the workflow predictable

How to Generate and Edit Images from Claude Code with Flux MCP

What you can do

How it works

Step 1: Add Flux MCP to Claude Code

Step 2: Verify the MCP connection

Step 3: Draft image directions with Flux Dev

Step 4: Refine with Flux Pro

Step 5: Fix existing images with Kontext editing

A practical workflow for technical content

Final notes

A Practical Guide to Building with the Kimi K3 Chat Completions API

What you can do

How it works

Use reasoning_effort carefully

Add streaming for better UX

Keep multi-turn chat simple

Handle errors before users see them

A good first build

A Practical Guide to Configuring Claude Desktop with a Third-Party Inference Gateway

What you are configuring

Step 1: Get an API key

Step 2: Open Claude Desktop developer mode

Step 3: Fill in the gateway settings

Step 4: Verify with a minimal prompt

What to check when it fails

401 errors

Model not found

Tool calls stop after the first call

Prompt caching confusion

A practical verification checklist

Closing thoughts

How to Add Short Link Workflows to Claude Code with MCP

What you can do

How it works

Configure it locally first

Use it in a PR or commit workflow

Batch-clean links in Markdown

Choose the right scope

Final notes

A Practical Guide to Generating Short Videos with the Seedance API

What you can do

A minimal text-to-video request

Choose model features intentionally

Add reference images without 400 errors

Multimodal references and validation

How to Configure Cline in VS Code with an OpenAI-Compatible Endpoint

What you can do

How it works

Step 1: get the API Key

Step 2: configure Cline in VS Code

Step 3: verify basic model access

Step 4: verify file-oriented agent behavior

A practical debugging checklist

When this setup is useful

How to Add AI Music Generation to Gemini CLI with Suno MCP

What you can do

How it works

Alternative: edit the Gemini settings file

Try a few useful prompts

A practical workflow for builders

When I would use each tool

Keep the integration boring

How to Track Async Image Generation Jobs with the Seedream Tasks API

What you can do

Store the task ID first

Retrieve one task

Retrieve many tasks at once

A practical polling loop

Error handling

Where this fits in an app

How to Add Seedream Image Tools to Gemini CLI with MCP

What you are building

Step 1: prepare a source recording that can pass verification

Use `reasoning_effort` carefully

Optional: keep a manual `.vscode/mcp.json`