Skip to main content
POST

Authorizations

string
required
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:

Body

string
default:"mai-image-2.7"
required
Image generation model nameBoth 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:
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
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.
Text-to-image (aspect ratio + 2K)
Text-to-image (exact pixels)
Single-image editing
Multi-image composition (mixed URL + base64)

Response

integer
Response status code
array
Response data array

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.

Success Response Example

To get the image: data.result.images[0].url[0]. Image links expire after expires_at, so download and save them promptly.

Task Status