Overview
Image generation powered by Google Gemini's image model. Accepts text-only prompts or text combined with up to four reference images for high-fidelity, semantically-aware output.
Primary Endpoint
/api/v1/userNanoBanana/startGenerate images using Nano Banana models with advanced conversational capabilities and NSFW content pre-filtering. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userNanoBanana/allRecords` — Get Nano Banana task list. - `GET /api/v1/userNanoBanana/detail/{id}` — Get task details. - `DELETE /api/v1/userNanoBanana/delete/{id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | No | Optional task name. |
| prompt | string | Yes | Text prompt for image generation |
| creation_mode | enum: text-to-image | image-edit | No | Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider. |
| model | enum: nano-banana | nano-banana-pro | nano-banana-2 | nano-banana-2-lite | No | Model to use for generation. Options: nano-banana (no resolution control, auto edit mode with images), nano-banana-pro (with resolution control), nano-banana-2 (with resolution control), nano-banana-2-lite (1K only); default: "nano-banana-pro" |
| input_images | array<string> | No | Array of input image URLs (for editing and composition modes) |
| aspect_ratio | enum: auto | 16:9 | 1:1 | 9:16 | 4:3 | 3:4 | 2:3 | 3:2 | 4:5 | 5:4 | 21:9 | No | Aspect ratio of the generated image. Options: auto, 16:9, 1:1, 9:16, 4:3, 3:4, 2:3, 3:2, 4:5, 5:4, 21:9; default: "auto" |
| image_size | enum: 1K | 2K | 4K | No | Size of the generated image. Options: 1K, 2K, 4K. Note: supported by nano-banana-pro and nano-banana-2 models; nano-banana-2-lite is always forced to 1K.; default: "1K" |
| google_search | boolean | No | Use Google Web Search grounding to generate images based on real-time information. Only supported by nano-banana-2 model.; default: false |
| force_generate | boolean | No | Force generation even if NSFW content is detected. Defaults to true for API users, false for web users; default: true |
| minor_suspected_skip | boolean | No | Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block.; default: false |
| webhook_url | string | No | HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.; maxLength: 2048 |
| webhook_token | string | No | Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.; maxLength: 256 |
Request schema and conditional rules
{
"allOf": [
{
"type": "object",
"required": [
"prompt"
],
"properties": {
"name": {
"type": "string",
"description": "Optional task name.",
"example": "Beautiful Landscape"
},
"prompt": {
"type": "string",
"description": "Text prompt for image generation",
"example": "A serene mountain landscape at sunset with a crystal clear lake"
},
"creation_mode": {
"type": "string",
"enum": [
"text-to-image",
"image-edit"
],
"description": "Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider."
},
"model": {
"type": "string",
"description": "Model to use for generation. Options: nano-banana (no resolution control, auto edit mode with images), nano-banana-pro (with resolution control), nano-banana-2 (with resolution control), nano-banana-2-lite (1K only)",
"enum": [
"nano-banana",
"nano-banana-pro",
"nano-banana-2",
"nano-banana-2-lite"
],
"default": "nano-banana-pro",
"example": "nano-banana-pro"
},
"input_images": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of input image URLs (for editing and composition modes)",
"example": [
"https://example.com/image1.jpg"
]
},
"aspect_ratio": {
"type": "string",
"description": "Aspect ratio of the generated image. Options: auto, 16:9, 1:1, 9:16, 4:3, 3:4, 2:3, 3:2, 4:5, 5:4, 21:9",
"enum": [
"auto",
"16:9",
"1:1",
"9:16",
"4:3",
"3:4",
"2:3",
"3:2",
"4:5",
"5:4",
"21:9"
],
"default": "auto",
"example": "auto"
},
"image_size": {
"type": "string",
"description": "Size of the generated image. Options: 1K, 2K, 4K. Note: supported by nano-banana-pro and nano-banana-2 models; nano-banana-2-lite is always forced to 1K.",
"enum": [
"1K",
"2K",
"4K"
],
"default": "1K",
"example": "1K"
},
"google_search": {
"type": "boolean",
"description": "Use Google Web Search grounding to generate images based on real-time information. Only supported by nano-banana-2 model.",
"default": false
},
"force_generate": {
"type": "boolean",
"description": "Force generation even if NSFW content is detected. Defaults to true for API users, false for web users",
"default": true
},
"minor_suspected_skip": {
"type": "boolean",
"default": false,
"description": "Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."
}
}
},
{
"$ref": "#/components/schemas/WebhookInput"
}
]
}Response Fields
- code: enum: 0
- data: object
- data._id: string
- data.name: string
- data.prompt: string
- data.model: string
- data.current_status: string
- data.reference_id: string
- data.coins: number
- trace_id: string
- Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.
- data.nsfw_detected: enum: true
- data.message: string
Request Example
curl -X POST "https://www.a2e.com.cn/api/v1/userNanoBanana/start" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A serene mountain landscape at sunset with a crystal clear lake"
}'Related Endpoints
Responses
Nano Banana task started successfully or NSFW content detected
Bad Request - Invalid parameters
Unauthorized - Invalid or missing bearer token