Overview
Image generation and editing via OpenAI GPT-4o image capabilities. Excels at precise instruction-following, photorealistic rendering, and multi-step image editing tasks.
Primary Endpoint
/api/v1/userGptImage/startGenerate images from text or edit existing images using GPT Image (4o Image) model. **Features:** - Text-to-Image generation - Image-to-Image editing (supports up to 16 reference images) - High-fidelity visuals with accurate text rendering **Output:** - Images are stored in R2 storage and expire after 3 days - GPT Image 1.5/2 default to JPEG. GPT Image 2.5 defaults to preserving the upstream PNG; auto and transparent backgrounds are never converted to JPEG. ### 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: `name`, `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 - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userGptImage/list` — Get GPT Image task list. - `GET /api/v1/userGptImage/detail/{id}` — Get task details. - `DELETE /api/v1/userGptImage/{id}` — Delete GPT Image task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Name of the image generation task |
| prompt | string | Yes | Text prompt for image generation (GPT Image 2.5: max 20000 chars; older models: 3000 chars in the web form) |
| 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. |
| input_images | array<string> | No | Array of input image URLs for image-to-image editing (up to 16 images) |
| model | enum: gpt-image-1.5 | gpt-image-2 | gpt-image-2.5-flare | gpt-image-2.5-sunburst | No | Model variant. GPT Image 1.5 uses quality; GPT Image 2 and 2.5 use resolution. Both GPT Image 2.5 variants default to 20/25/45 credits per image for 1K/2K/4K; current prices come from the feature pricing catalog.; default: "gpt-image-1.5" |
| aspect_ratio | enum: auto | 1:1 | 9:16 | 21:9 | 16:9 | 4:3 | 3:2 | 3:4 | 2:3 | 27:16 | 16:27 | 9:8 | 8:9 | No | GPT Image 1.5 supports 1:1/3:2/2:3. GPT Image 2 supports the nine common ratios. GPT Image 2.5 additionally supports 27:16/16:27/9:8/8:9, which are limited to 1K.; default: "1:1" |
| quality | enum: medium | high | No | Image quality level. Only used by gpt-image-1.5; default: "medium" |
| resolution | enum: 1K | 2K | 4K | No | GPT Image 2: auto is limited to 1K; 1:1+4K is normalized to 2K. GPT Image 2.5: 27:16/16:27/9:8/8:9 are normalized to 1K; other ratios, including auto and 1:1, support 1K/2K/4K. Billing uses the normalized resolution.; default: "1K" |
| save_as_png | boolean | No | Preserve the upstream image without re-encoding. GPT Image 2 defaults to false. GPT Image 2.5 defaults to true and requires preservation for auto or transparent backgrounds; opaque background allows false for JPEG. GPT Image 1.5 always uses JPEG. |
| background | enum: auto | opaque | transparent | No | GPT Image 2.5 only. Auto may produce transparency. Auto and transparent preserve the upstream PNG regardless of save_as_png.; default: "auto" |
| force_generate | boolean | No | Force generation even if NSFW content is detected |
| 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",
"properties": {
"name": {
"type": "string",
"description": "Name of the image generation task"
},
"prompt": {
"type": "string",
"description": "Text prompt for image generation (GPT Image 2.5: max 20000 chars; older models: 3000 chars in the web form)"
},
"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."
},
"input_images": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of input image URLs for image-to-image editing (up to 16 images)"
},
"model": {
"type": "string",
"enum": [
"gpt-image-1.5",
"gpt-image-2",
"gpt-image-2.5-flare",
"gpt-image-2.5-sunburst"
],
"default": "gpt-image-1.5",
"description": "Model variant. GPT Image 1.5 uses quality; GPT Image 2 and 2.5 use resolution. Both GPT Image 2.5 variants default to 20/25/45 credits per image for 1K/2K/4K; current prices come from the feature pricing catalog."
},
"aspect_ratio": {
"type": "string",
"enum": [
"auto",
"1:1",
"9:16",
"21:9",
"16:9",
"4:3",
"3:2",
"3:4",
"2:3",
"27:16",
"16:27",
"9:8",
"8:9"
],
"default": "1:1",
"description": "GPT Image 1.5 supports 1:1/3:2/2:3. GPT Image 2 supports the nine common ratios. GPT Image 2.5 additionally supports 27:16/16:27/9:8/8:9, which are limited to 1K."
},
"quality": {
"type": "string",
"enum": [
"medium",
"high"
],
"default": "medium",
"description": "Image quality level. Only used by gpt-image-1.5"
},
"resolution": {
"type": "string",
"enum": [
"1K",
"2K",
"4K"
],
"default": "1K",
"description": "GPT Image 2: auto is limited to 1K; 1:1+4K is normalized to 2K. GPT Image 2.5: 27:16/16:27/9:8/8:9 are normalized to 1K; other ratios, including auto and 1:1, support 1K/2K/4K. Billing uses the normalized resolution."
},
"save_as_png": {
"type": "boolean",
"description": "Preserve the upstream image without re-encoding. GPT Image 2 defaults to false. GPT Image 2.5 defaults to true and requires preservation for auto or transparent backgrounds; opaque background allows false for JPEG. GPT Image 1.5 always uses JPEG."
},
"background": {
"type": "string",
"enum": [
"auto",
"opaque",
"transparent"
],
"default": "auto",
"description": "GPT Image 2.5 only. Auto may produce transparency. Auto and transparent preserve the upstream PNG regardless of save_as_png."
},
"force_generate": {
"type": "boolean",
"description": "Force generation even if NSFW content is detected"
},
"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."
}
},
"required": [
"name",
"prompt"
]
},
{
"$ref": "#/components/schemas/WebhookInput"
}
]
}Response Fields
- code: enum: 0
- data: object
- data._id: string
- Task ID for detail and batch polling.
- data.name: string
- data.prompt: string
- data.is_downloaded: boolean
- data.is_previewed: boolean
- data.current_status: string
- Persisted task state; use the concrete task family schema for its allowed values and terminal states.
- data.createdAt: string
- data.updatedAt: string
- data.expirationDate: string
- data.remainingDays: number
- data.isExpired: boolean
- data.coins: number
- data.hasRefundCoin: boolean
- Whether charged credits were refunded.
- data.failed_code: string
- data.failed_message: string
- data.failed_reason: string
- Public failure category when available.
- data.creation_mode: string
- data.image_url: string
- data.image_urls: array<string>
- data.result_image_url: string
- data.result_image_urls: array<string>
- data.input_images: array<string>
- data.nsfw_detected: enum: true
- data.message: string
- 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.
Request Example
curl -X POST "https://www.a2e.com.cn/api/v1/userGptImage/start" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "My Task",
"prompt": "high quality, clear, cinematic"
}'Related Endpoints
Responses
Task started successfully or NSFW content detected
Unauthorized - Invalid or missing bearer token