MaaS_GP_image

Request Protocol

http

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.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.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.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.

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

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_indexindicates which partial image it is currently (starting from 0). The number of partial images is controlled by the request parameterpartial_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

{
  "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

Appendix 1: Supported Output Sizes

Size	Aspect Ratio
auto	Automatic
1024x1024	1:1
1536x1024	3:2
1024x1536	2:3

Appendix 2: Comparison of Model Characteristics

Feature	gpt-image-1.5	gpt-image-1	gpt-image-1-mini
Billing Method	Token	Token	Token
Default Response Format	b64_json	b64_json	b64_json
Supports streaming	✓	✓	✓
Transparent Background	✓	✓	✓
Multi-image Input (Edit)	✓ (up to 16 images)	✓ (up to 16 images)	✓ (up to 16 images)
usage object	✓	✓	✓