All endpoints require Bearer Token authenticationGet your API Key:Visit the API Key management page to get your API KeyInclude it in the request header:
Authorization: Bearer YOUR_API_KEY
Body
string
default:"mai-image-2.7"
required
Image generation model name
Model
Description
mai-image-2.7
High-quality version, best for use cases where image quality matters most
mai-image-2.7-flash
Fast version with slightly lower image quality, faster speed, and lower cost
Both models have exactly the same capabilities and parameters.
boolean
default:"false"
Whether to run content moderation before submitting the image task.
true: use omni-moderation-latest to review prompts and input images
false or omitted: do not send a moderation request, adding no moderation cost or latency (default)
string
required
Text description or editing instructions for the image
Supports Chinese and English; detailed descriptions are recommended
Up to 20,000 characters; longer prompts return 400
Cannot be empty or whitespace only
integer
default:"1"
Number of images to generateValue: 1
Only 1 image can be generated per request; submit separate tasks for multiple images. Passing 0, a negative number, or a value greater than 1 returns 400
string
default:"1:1"
Image aspect ratio or pixel dimensions, applies to text-to-image onlyTwo formats are supported:
Aspect ratio: any integer ratio from 1:4 to 4:1, such as 1:1, 16:9, 9:16, or 21:9; combined with resolution to determine the actual pixels
Pixel dimensions: widthxheight (also accepts width*height and width×height), such as 2048x1152; resolution is ignored in this case
Pixel dimension constraints:
Width and height must both be ≥ 768
Width × height must be ≤ 4,194,304 (2048×2048)
Width and height are each rounded down to a multiple of 32; for example, 1000x1000 outputs 992x992
Examples: ✅ 2048x2048, 2048x1152, 2560x1536; ❌ 512x512 (side shorter than 768), 2080x2048 (exceeds the total pixel limit)
auto is not supported and returns 400
string
default:"1K"
Output resolution tier, applies only when size is an aspect ratioOptions: 1K / 2K (lowercase also accepted)size × resolution → actual pixel mapping:
size
1K
2K
1:1
1024×1024
2048×2048
4:3
1152×864
2336×1760
3:4
864×1152
1760×2336
3:2
1248×832
2496×1664
2:3
832×1248
1664×2496
16:9
1344×768
2720×1536
9:16
768×1344
1536×2720
2:1
1536×768
2880×1440
1:2
768×1536
1440×2880
21:9
1792×768
3104×1312
9:21
768×1792
1312×3104
4:1
3072×768
4096×1024
1:4
768×3072
1024×4096
4K is not supported; any other tier returns 400. Because the shorter side must be at least 768, aspect ratios more extreme than 2:1 (or 1:2) produce more than about 1 million pixels at the 1K tier.
integer
Exact pixel width, must be provided together with height
Highest priority; when provided, overrides size and resolution
Same constraints as size pixel dimensions: width and height both ≥ 768, total pixels ≤ 4,194,304
Applies to text-to-image only
integer
Exact pixel height, must be provided together with width; same constraints as width
array
Array of reference images; when provided, the request runs in image-to-image mode
Provide 1 image for single-image editing, or multiple images for multi-image composition
Show Details
Up to 5 reference images
Supports image URL (a publicly accessible direct link; an inaccessible URL causes the task to fail)
Supports base64 data URI (such as data:image/png;base64,...)
Supports JPEG and PNG; WEBP and GIF are automatically converted to PNG
Output dimensions are determined by the model from the reference images; size / resolution / width / height have no effect on image-to-image
string
Background typeOptions: auto / opaque, same effect as omitting the parameter
Transparent background transparent is not yet available; passing transparent or any other value returns 400
auto_aspect_ratio: true and web_grounding: true are not supported and return 400. quality, style, output_format, response_format, and mask_url are not supported and are ignored. Output is always PNG.
Usage Examples
Text-to-image (minimal request)Defaults to 1:1 + 1K, outputting 1024×1024.
{ "model": "mai-image-2.7", "prompt": "A university campus poster at dusk, photorealistic style, cinematic lighting"}
Text-to-image (aspect ratio + 2K)
{ "model": "mai-image-2.7", "prompt": "A university campus poster at dusk, photorealistic style, cinematic lighting", "size": "3:2", "resolution": "2K"}
Text-to-image (exact pixels)
{ "model": "mai-image-2.7-flash", "prompt": "A glass perfume bottle on a white marble countertop, clean product photography", "width": 2048, "height": 2048}
Single-image editing
{ "model": "mai-image-2.7", "prompt": "Make the bicycle blue and add a small dog next to it", "image_urls": [ "https://example.com/bicycle.png" ]}
Multi-image composition (mixed URL + base64)
{ "model": "mai-image-2.7-flash", "prompt": "Combine both reference images into a clean futuristic product photo", "image_urls": [ "https://example.com/first.png", "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." ]}
Response
integer
Response status code
array
Response data array
Show Properties
string
Task status
submitted - Submitted
string
Unique task identifier, used for subsequent result queries
Querying Task Results
After successful submission, a task_id is returned. Poll the task status via GET /v1/tasks/{task_id}, see Task Query API for details. We recommend polling every 3–5 seconds with an overall timeout of 3 minutes.