sync: daily Backend capability updates

en/guides/nano-banana/nanobanana_images.mdx

@@ -3,44 +3,45 @@ title: "Nano Banana Images API Integration Guide"
 description: "Nano Banana Image Generation integration guide - Ace Data Cloud"
 ---
 
-This document introduces the integration and use of the Nano Banana Images API. This API supports two capabilities: **image generation (generate)** and **image editing (edit)**.
+This document introduces the integration and usage of the Nano Banana Images API. This API supports two capabilities: **image generation (generate)** and **image editing (edit)**.
 
 ## Application Process
 
 To use the Nano Banana Images API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token and keep it for later use.
 
 ![](https://cdn.acedata.cloud/dvc3cg.jpg)
 
-If you have not yet logged in or registered, you will be automatically redirected to the login page and invited to register and log in. After completion, you will automatically return to the current page.
+If you have not logged in or registered yet, you will be automatically redirected to the login page to register and log in, and will automatically return to the current page after completion.
 
-**One API Token can call all platform services; there is no need to apply separately for each service.** Your first application includes free credits for a free trial; when credits are insufficient, you can recharge your general balance in the [Console](https://platform.acedata.cloud/console/coin).
+**One API Token can call all platform services; there is no need to apply separately for each service.** Your first application will receive free credits for a free trial; when credits are insufficient, you can recharge your general balance in the [Console](https://platform.acedata.cloud/console/coin).
 
 > 📘 Full documentation: [Nano Banana Images API →](https://platform.acedata.cloud/documents/nano-banana-images)
 
 ## API Overview
 
 - **Base URL**: `https://api.acedata.cloud`
 - **Endpoint**: `POST /nano-banana/images`
-- **Authentication method**: Include `authorization: Bearer {token}` in the HTTP Header
-- **Request headers**:
+- **Authentication**: Include `authorization: Bearer {token}` in the HTTP Header
+- **Request Headers**:
   - `accept: application/json`
   - `content-type: application/json`
-- **Action (`action`)**:
-  - `generate`: Generate an image based on a text prompt
-  - `edit`: Edit based on the given image
-- **Model (`model`)** (optional):
+- **Actions (`action`)**:
+  - `generate`: Generate images based on text prompts
+  - `edit`: Edit based on given images
+- **Models (`model`)** (optional):
   - `nano-banana` (default): Based on Gemini 2.5 Flash Image, fast and low cost
   - `nano-banana-2-lite`: Based on Gemini 3.1 Flash Lite Image, supports 1K only, fast generation speed
   - `nano-banana-2`: Based on Gemini 3.1 Flash Image Preview, Pro-level quality + Flash speed
+  - `nano-banana-2.1`: A new-generation efficient image model supporting 1K, 2K, and 4K image generation and editing
   - `nano-banana-pro`: Based on Gemini 3 Pro Image Preview, highest quality
-  - `nano-banana:official`, `nano-banana-2-lite:official`, `nano-banana-2:official`, `nano-banana-pro:official`: Official channel versions of the corresponding models, with better image quality and stability, billed differently
-- **Asynchronous callback**: Optional; receive task completion notifications and results through `callback_url`
-- **Image quantity**: Optional; specify 1–4 images through `count`, with a default of 1; each image is completed by an independent generation call; ordinary technical failures or provider safety rejections only affect the corresponding call, while other successful images are returned as usual and billed according to the actual number of successful images
+  - `nano-banana:official`, `nano-banana-2-lite:official`, `nano-banana-2:official`, `nano-banana-pro:official`: Official-channel versions of the corresponding models, with better image quality and stability, and different billing
+- **Asynchronous Callback**: Optional; receive task completion notifications and results through `callback_url`
+- **Image Count**: Optional; specify 1–4 images through `count`, with a default of 1; each image is completed by an independent generation call; ordinary technical failures or provider safety rejections only affect the corresponding call, while other successfully generated images are returned as usual and billed according to the actual number of successful images
 
 ## Quick Start: Generate Images (`action=generate`)
 
 **Minimum required parameters**: `action`, `prompt`  
-When you only want to directly generate an image based on a prompt, set `action` to `generate` and provide a clear `prompt`.
+When you only want to generate an image directly based on a prompt, set `action` to `generate` and provide a clear `prompt`.
 
 ### Request Example (cURL)
 
@@ -107,18 +108,18 @@ print(resp.json())
 - `success`: Whether this request was successful.
 - `task_id`: Task ID.
 - `trace_id`: Trace ID for troubleshooting.
-- `count`: The number of images requested for generation or editing, supporting 1–4, with a default of 1. `data` contains only successfully generated images and is billed according to the actual number returned. Each generation call is required to use the provider's native safety policy; rejection of one call does not affect other successful calls, and 403 is returned when all calls are rejected.
+- `count`: The number of images requested for generation or editing, supporting 1–4, with a default of 1. `data` contains only successfully generated images and is billed according to the actual number of returned images. Each generation call is required to use the provider's native safety policy; a rejected call does not affect other successful calls, and a 403 is returned when all calls are rejected.
 - `data[]`: Result list.
-  - `prompt`: Prompt used for generation (echoed back).
+  - `prompt`: The prompt used for generation (echoed).
   - `image_url`: Direct URL of the generated image.
 
 > Note: `/nano-banana/images` only requires `action` and `prompt` to generate images
 
 ## Edit Images (`action=edit`)
 
-When you want to edit based on an existing image, set `action` to `edit`, pass in the list of image links to be edited (one or more images) through `image_urls`, and provide a `prompt` describing the editing target.
+When you want to edit based on existing images, set `action` to `edit`, pass in a list of image links to be edited (one or multiple images) through `image_urls`, and provide a `prompt` describing the editing target.
 
-For example, here we provide a portrait photo and a clothing photo, and have the person wear the clothing. You can pass in both image links at the same time and specify `action` as `edit`. The URL can be an HTTP URL, a publicly accessible link using the `https` or `http` protocol, or a Base64-encoded image, such as `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....`
+For example, here we provide a photo of a person and a photo of clothing, and want the person to wear this clothing. You can pass in the image links at the same time and specify `action` as `edit`. The URL can be an HTTP URL, a publicly accessible link using the `https` or `http` protocol, or a Base64-encoded image, such as `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....`
 
 ### Request Example (cURL)
 ```bash
@@ -179,18 +180,18 @@ print(resp.json())
 
 ### Field Description
 
-- `image_urls[]`: List of image URLs to be edited (must be publicly accessible). Multiple images can be provided, and the service will combine these materials with the `prompt` to complete the editing.
-- Other fields are the same as those returned by "Generate Image".
+- `image_urls[]`: List of image URLs to be edited (must be publicly accessible). Multiple images can be provided; the service will combine these materials with the `prompt` to complete the editing.
+- Other fields are the same as the response for "Generate Image".
 
 ---
 
 ## Asynchronous Callback (Optional, Recommended)
 
-Generation or editing may take some time. To avoid long connections consuming resources, it is recommended to use a **Webhook callback** through `callback_url`:
+Generating or editing may take some time. To avoid long connections consuming resources, it is recommended to use a **Webhook callback** through `callback_url`:
 
 1. Add `callback_url` to the request body, for example, your server-side Webhook address (must be publicly accessible and support POST JSON).
-2. The API will **immediately return** a response containing `task_id` (or basic results).
-3. When the task is completed, the platform will send the complete JSON to `callback_url` via `POST`. You can associate the request with the result through `task_id`.
+2. The API will **immediately return** a response containing `task_id` (or containing basic results).
+3. When the task is complete, the platform will send the full JSON to `callback_url` via `POST`. You can associate the request with the result through `task_id`.
 
 **Callback Payload Example** (the field structure is consistent with the synchronous successful response):
 
@@ -216,8 +217,8 @@ When a call fails, a standard error format and trace ID will be returned. Common
 
 - **400 `token_mismatched`**: The request is invalid or there is a parameter error.
 - **400 `api_not_implemented`**: The API is not implemented (please contact support).
-- **401 `invalid_token`**: Authentication failed or the Token is missing.
-- **403 `forbidden`**: The provider's native security policy rejected the request or generated result. This call will not return an image and will not be billed; multi-image requests may still return and bill for other successful calls.
+- **401 `invalid_token`**: Authentication failed or Token is missing.
+- **403 `forbidden`**: The provider's native security policy rejected the request or generated result. This call will not return an image and will not be charged; multi-image requests may still return and charge for other successful calls.
 - **429 `too_many_requests`**: Request rate limit exceeded.
 - **500 `api_error`**: Server-side exception.
 
@@ -239,8 +240,8 @@ When a call fails, a standard error format and trace ID will be returned. Common
 ## Parameter Reference and Notes
 
 - **Required**: `action`, `prompt`
-- **Editing Only**: `image_urls` (array, at least 1 item)
-- **Optional**: `model` (default: `nano-banana`; optional values: `nano-banana-2-lite`, `nano-banana-2`, `nano-banana-pro`, or the corresponding `:official` official channel versions), `aspect_ratio` (aspect ratio, such as `1:1`, `16:9`), `resolution` (resolution, such as `1K`, `2K`, `4K`; `nano-banana-2-lite` supports only `1K`), `callback_url` (used for asynchronous callbacks)
-- **Headers**: You must provide `authorization: Bearer {token}`; setting `accept` to `application/json` is recommended
+- **Edit-only**: `image_urls` (array, at least 1 item)
+- **Optional**: `model` (default: `nano-banana`; optional: `nano-banana-2-lite`, `nano-banana-2`, `nano-banana-2.1`, `nano-banana-pro`; except for `nano-banana-2.1`, corresponding `:official` official-channel versions are also available), `aspect_ratio` (aspect ratio, such as `1:1`, `16:9`), `resolution` (resolution, such as `1K`, `2K`, `4K`; `nano-banana-2-lite` supports only `1K`), `callback_url` (used for asynchronous callbacks)
+- **Headers**: `authorization: Bearer {token}` must be provided; `accept` is recommended to be set to `application/json`
 - **Image Accessibility**: `image_urls` must be publicly accessible direct links (HTTP/HTTPS); HTTPS is recommended
 - **Idempotency and Tracking**: Retain `task_id` and `trace_id` for troubleshooting and result association