如何使用 Nano Banana Images API 建立簡單的 HTTP 圖像編輯流程

When an image workflow starts in a design tool, the hard part is often not the edit itself. It is making the edit repeatable: accepting a prompt, preserving the input references, authenticating the request, and keeping enough task information to troubleshoot a failed run.

This guide shows a small, practical workflow for editing one or more publicly accessible images over HTTP. The example uses the Nano Banana Images API, but the useful pattern is broader: send an explicit action, keep the input URLs and prompt together, and retain the task identifiers returned by the service.

What you can do

The API exposes one endpoint for image generation and editing:

• Base URL: https://api.acedata.cloud
• Endpoint: POST /nano-banana/images
• Authentication: authorization: Bearer {token}
• Content type: application/json

For editing, set action to edit, provide at least one item in image_urls, and describe the desired change in prompt. The URLs must be publicly accessible direct links. You can pass more than one image when the edit needs multiple reference materials.

The request can also include model, count, aspect_ratio, resolution, and an optional callback_url. The documented model options include nano-banana, nano-banana-2-lite, nano-banana-2, nano-banana-2.1, and nano-banana-pro.

How the request works

A useful mental model is that the request has three parts:

1. Action — tells the endpoint whether this is a generate or edit operation.
2. Materials — image_urls[] contains the source images for an edit.
3. Instruction — prompt describes what should change.

The response includes success, a task_id, a trace_id, and a data array. Each successful item in data contains the prompt and an image_url. Keep both identifiers in your application logs. They give you a way to associate a result with the original request when a workflow has several edits in flight.

Make your first edit with cURL

Start with a single reference image and a deliberately narrow instruction. A small edit is easier to evaluate than a prompt that asks for several unrelated changes at once.

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "model": "nano-banana-pro",
    "prompt": "Replace the background with a clean, softly lit studio backdrop while keeping the subject and its proportions unchanged.",
    "image_urls": [
      "https://example.com/input.png"
    ],
    "count": 1
  }'

Replace {token} and the example image URL with values you control. The API documentation accepts HTTP or HTTPS image URLs, although HTTPS is the safer default for production systems.

A successful response has this general shape:

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "Replace the background with a clean, softly lit studio backdrop while keeping the subject and its proportions unchanged.",
      "image_url": "https://cdn.acedata.cloud/assets/example.png"
    }
  ]
}

Treat the returned image_url as the artifact your next workflow step consumes. Do not assume that a request with multiple images produces one result: the API describes each requested image as an independent generation call, and data contains only successful results.

Use multiple references without losing context

Multiple references are useful when the edit combines materials—for example, a subject image and a separate visual reference. Put them in the intended order in image_urls and make their roles explicit in the prompt:

{
  "action": "edit",
  "prompt": "Keep the person from the first image, and use the second image only as the clothing reference.",
  "image_urls": [
    "https://example.com/person.png",
    "https://example.com/clothing.png"
  ],
  "count": 1
}

The important engineering detail is not the wording of the example. It is that the materials and instruction travel together as one request. That makes a job reproducible and gives you a clean record to store alongside the result.

Make longer jobs observable

For a synchronous prototype, waiting for the HTTP response can be enough. For a production workflow, the documentation recommends an optional callback_url. The endpoint can return a task_id immediately, then send the completed JSON to your publicly accessible webhook with a POST request.

A minimal webhook handler should:

• validate that the payload contains the expected task_id;
• store trace_id, success, and the returned data items;
• record failures separately from provider safety rejections;
• make processing idempotent, because retries should not create duplicate downstream work.

The documented error codes also give you a useful starting point for retry policy: 401 invalid_token is an authentication problem, 429 too_many_requests is a rate-limit signal, and 500 api_error indicates a server-side exception. A 403 forbidden response means the provider's safety policy rejected the call or result, so it should not be handled as a normal transient error.

A practical checklist

Before wiring this into an application, check the basics:

• Keep the API token in server-side configuration, not in browser code.
• Verify every image_urls value is a direct, publicly accessible link.
• Start with count: 1 while validating prompts and output handling.
• Persist task_id and trace_id with your request record.
• Add callback_url when a long-running request should not hold an open connection.
• Handle invalid_token, too_many_requests, api_error, and forbidden differently.

The result is a small but dependable image-editing building block: a prompt-driven operation with explicit inputs, observable execution, and a URL that can move into the next step of a pipeline. For the complete parameter reference and response details, see the Nano Banana Images API documentation.