MaaS_GP_image

Request Protocol

https

Header

Parameter Name	Type	Description
anthorization	string	Authentication

Capability Map

Ability	Image Generat ion	Image Edit
text-to-image generation	✓	-
Image Editing	-	✓
Multi-image input	-	✓ (up to 16 images)
Mask Editing	-	✓
Streaming Output	✓	✓
Multiple output formats	✓	✓

1. Interface and Request Parameters

Image Generation Interface (Image Generation)

POST {endpointPath}/images/generations

Generate images based on text prompts.

Request Parameters

Attribute Name	Type	Is it required?	Description
prompt	string	is	Text prompt describing the desired image.
background	string	No	Background behavior. Optional values:transparent(transparent/not supported by Image 2.0),opaque(opaque),auto(automatic).
moderation	string	No	Content moderation level. Optional values:low,auto.
n	integer	No	Number of generated images. Default: 1.
output_compression	number	No	jpeg or webp output compression level (0-100). Does not support PNG
output_format	string	No	Output image format. Available values:png,jpeg,webp.
quality	string	No	Output image quality. Available values:low,medium,high,auto.
size	string	No	Output image size. Optional values:auto,1024x1024,1536x1024,1024x1536.
stream	boolean	No	Whether to return in streaming mode. Default is false. Set to true to enable streaming output.
partial_images	number	No	Only available in streaming mode. Number of partial images during streaming response (0-3).
user	string	No	Unique Device Identifier, used for monitoring and detecting abuse.

Request Example

curl -X POST https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
  "prompt": "A beautiful sunset over mountains with vibrant colors",
  "model": "gpt-image-1",
  "quality": "high",
  "size": "1024x1024",
  "n": 1
}'

Example of Transparent Background (not supported by image2.0)

curl -X POST https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
  "prompt": "A cute cat sitting, isolated on transparent background",
  "model": "gpt-image-1",
  "background": "transparent",
  "output_format": "png"
}'

Streaming Output Example

curl -X POST https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
  "prompt": "A futuristic cityscape at night",
  "model": "gpt-image-1",
  "stream": true,
  "partial_images": 2
}'

Image Edit Interface (Image Edit)

POST {endpointPath}/images/edits

Edit or expand existing images based on the prompt.

Request Parameters

Attribute Name	Type	Is it required?	Description
image	string or array	is	Upload a file. The file format must be jpg or png, and the file size must not exceed 50MB
prompt	string	is	Text prompt describing the desired image editing effect.
input_fidelity	string	No	Fidelity to the original input image. Optional values: high, low.
mask	string	No	Mask image reference, used to specify the editing area. PNG, no more than 4MB.
model	string	No	Model used.
n	number	No	Number of edited images generated.
partial_images	number	No	Only available in streaming mode. Number of partial images (0-3) during streaming response. When set to 0, a single event returns the full image.
quality	string	No	Output quality. Optional values:low,medium,high,auto.
size	string	No	Output size. Optional values:auto,1024x1024,1536x1024,1024x1536.
stream	boolean	No	Whether to return in streaming mode. Default is false. Set to true to enable streaming output.
user	string	No	Unique Device Identifier for end users.

request Example

{
curl 
--location --request POST 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/images/edits' \
--header 'Authorization: Bearer $API_KEY' \
--form 'image[]=@"F:\\projects\\AiModels\\images\\1111111111111.png"' \
--form 'prompt="less people to two"'
}

Example of a multi-image editing request

request Example

{curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/images/edits' \
--header 'Authorization: Bearer $API_KEY' \
--header 'Content-Type: multipart/form-data' \
--form 'image[]=@"/C:/Users/98de9f970bb9462a90fc69799f5269b9fbb624c8.jpg"' \
--form 'image[]=@"/C:/Users/Desktop/fox.png"' \
--form 'prompt="Combine these two images together"'
}

2. Response Format

Non-streaming response

Response Example

{
  "created": 1709312456,
  "background": "opaque",
  "output_format": "png",
  "quality": "high",
  "size": "1024x1024",
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 1250,
    "input_tokens_details": {
      "image_tokens": 1100,
      "text_tokens": 150
    },
    "output_tokens": 4096,
    "output_tokens_details": {
      "image_tokens": 4000,
      "text_tokens": 96
    },
    "total_tokens": 5346
  }
}

Response Field Description

Field	Type	Description
created	number	Unix timestamp (seconds) of image creation
background	string	Background parameters used. Optional values: transparent, opaque
output_format	string	Output format. Optional values:png,webp,jpeg
quality	string	Quality of the generated image. Optional values:low,medium,high
size	string	Size of the generated image
data	array	Generated Image List
data[].b64_json	string	Base64-encoded image data
usage	object	Token Usage Information
usage.input_tokens	number	Number of input Tokens (image + text)
usage.input_tokens_details	object	Input Token Details
usage.output_tokens	number	Output Token Count
usage.output_tokens_details	object	Output Token Details
usage.total_tokens	number	Total number of Tokens

Streaming Response

ResponseExample

```plain text event: {operation_type}.partial_image data: { "type": "{operation_type}.partial_image", "partial_image_index": 0, "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }

event: {operation_type}.partial_image data: { "type": "{operation_type}.partial_image", "partial_image_index": 1, "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }

event: {operation_type}.completed data: { "type": "{operation_type}.completed", "created": 1709312456, "usage": { "input_tokens": 1250, "output_tokens": 4096, "total_tokens": 5346 } } data: [DONE]

#### **Explanation of Streaming Response Events**

| Event Type                       | Description                                                                                                                                                                                                        |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `{operation_type}.partial_image` | Returns a partially rendered image.`partial_image_index`indicates which partial image it is currently (starting from 0). The number of partial images is controlled by the request parameter`partial_images`(0-3). |
| `{operation_type}.completed`     | All image generation is completed, returning the final usage information. This is the last event of the streaming response.                                                                                        |

The value of {operation\_type} can be different depending on the requested interface: 

image\_generation: /images/generations

image\_edit: /images/edits

#### **Streaming Parameter Description**

* `stream: true` - Enable streaming output mode

* `partial_images: 0-3` - Controls the number of partial images returned

  * `0`: Return the full image directly without returning partial images

  * `1-3`: Return 1-3 progressively rendered partial images, then return the full image

#### **Precautions **

* The complete image may be generated before all partial images are returned 

## 3. **Error Response**

### **Example of Error Response**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Incorrect API key provided",
    "type": "invalid_request_error"
  }
}

Common Error Codes

Error Code	Instructions
invalid_api_key	Invalid API Key
invalid_request_error	Request parameter error
rate_limit_exceeded	Exceeded rate limit
content_policy_violation	Content violates policy
server_error	Internal Server Error

IV. Appendices

	Image-2	Image-1.5	Image-1	Image-1-Mini
Advantages	Best suited for high-resolution and 4K generation, improved image editing, and extensive aspect ratio support	Best Choice: Realism, Instruction Following, MultiModal Machine Learning Context, and Improved Speed and Cost.	Best suited for realism, instruction execution, and MultiModal Machine Learning context	Best suited for rapid prototyping, batch generation, or cost-sensitive use cases
Input/Output Forms and Formats	Accepts text + image input; only outputs images in base64 (no URL option).
Image Size/Resolution	Arbitrary resolution: Both edges must be multiples of 16 pixels; Long edge up to 3,840 pixels (4K): Aspect ratio up to 3:1; Pixel count 655,360–8,294,400	1024×1024、1024×1536、1536×1024
Quality Options	Improved Quality Control:low,medium,high;lowoptimized for latency-sensitive use cases	low medium, high (default = high)	low medium, high (default = high)	low, (mediumhigh default = medium)
Number of images per request	1-10 images per request (n parameter)	1-10 images per request (n parameter)	1-10 images per request (n parameter)	1-10 images per request (n parameter)
Edit (Cutting/Variation)	✅ Improved editing performance when using internal painting and variants	✅ Supports masks, variants + prompts	✅ Supports image inpainting and variant generation via masks and prompts	✅ Supports repair and variation through masks and prompts
Face Retention	✅Advanced face fidelity ensures real and consistent results	✅Advanced face fidelity for achieving realistic and consistent effects	✅Advanced face fidelity for realistic and consistent results	❌ No dedicated face retention; more suitable for non-portrait/ordinary creative images
Performance and Cost	High-fidelity, realism-optimized model; higher latency and cost	High-fidelity, realism-optimized model; improves the efficiency and latency of GPT-Image-1	High-fidelity, realism-optimized model; higher latency and cost	Cost-effective and faster for large-scale or iterative generation