> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MAI-Image-2.7 Image Generation

>  - Asynchronous processing mode, returns task ID for subsequent queries
- Supports text-to-image, single-image editing, and multi-image composition, with up to 5 reference images
- Available as the high-quality `mai-image-2.7` and the fast `mai-image-2.7-flash`, with identical capabilities and parameters
- Control output size with `size` (aspect ratio) + `resolution` (`1K` / `2K`), or specify exact pixels
- Up to 2048×2048 per image (about 4.19 megapixels), 1 image per request 

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "mai-image-2.7",
    "prompt": "A university campus poster at dusk, photorealistic style, cinematic lighting",
    "size": "16:9",
    "resolution": "2K"
  }'
```

```python Python theme={null}
import requests

url = "https://api.apimart.ai/v1/images/generations"

payload = {
    "model": "mai-image-2.7",
    "prompt": "A university campus poster at dusk, photorealistic style, cinematic lighting",
    "size": "16:9",
    "resolution": "2K"
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript JavaScript theme={null}
const url = "https://api.apimart.ai/v1/images/generations";

const payload = {
  model: "mai-image-2.7",
  prompt: "A university campus poster at dusk, photorealistic style, cinematic lighting",
  size: "16:9",
  resolution: "2K"
};

const headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

```go Go theme={null}
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    url := "https://api.apimart.ai/v1/images/generations"

    payload := map[string]interface{}{
        "model":      "mai-image-2.7",
        "prompt":     "A university campus poster at dusk, photorealistic style, cinematic lighting",
        "size":       "16:9",
        "resolution": "2K",
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer <token>")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "Invalid parameters: empty prompt / invalid size / unsupported resolution / pixels out of range, etc.",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Authentication failed, please check your API key",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "Insufficient account balance, please top up and try again",
    "type": "payment_required"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "Too many requests, please try again later",
    "type": "rate_limit_error"
  }
}
```

```json 500 theme={null}
{
  "error": {
    "code": 500,
    "message": "Server error",
    "type": "server_error"
  }
}
```

## Authorizations

**Authorization** `string` *required*

All endpoints require Bearer Token authentication

Get your API Key:

Visit the [API Key management page](https://apimart.ai/keys) to get your API Key

Include it in the request header:

```
Authorization: Bearer YOUR_API_KEY
```

## Body

**model** `string` *required* (default: mai-image-2.7)

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.

**nsfw\_check** `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)

**prompt** `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

**n** `integer` (default: 1)

Number of images to generate

Value: `1`

> [!WARNING]
>
> 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

**size** `string` (default: 1:1)

Image aspect ratio or pixel dimensions, applies to text-to-image only

Two 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)

> [!WARNING]
>
> `auto` is not supported and returns 400

**resolution** `string` (default: 1K)

Output resolution tier, applies only when `size` is an aspect ratio

Options: `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 |

> [!WARNING]
>
> `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.

**width** `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

**height** `integer`

Exact pixel height, must be provided together with `width`; same constraints as `width`

**image\_urls** `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

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

**background** `string`

Background type

Options: `auto` / `opaque`, same effect as omitting the parameter

> [!WARNING]
>
> Transparent background `transparent` is not yet available; passing `transparent` or any other value returns 400

> [!NOTE]
>
> `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.

```json theme={null}
{
  "model": "mai-image-2.7",
  "prompt": "A university campus poster at dusk, photorealistic style, cinematic lighting"
}
```

**Text-to-image (aspect ratio + 2K)**

```json theme={null}
{
  "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)**

```json theme={null}
{
  "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**

```json theme={null}
{
  "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)**

```json theme={null}
{
  "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

**code** `integer`

Response status code

**data** `array`

Response data array

**Properties**

**status** `string`

Task status

* `submitted` - Submitted

**task\_id** `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](https://docs.apimart.ai/en/api-reference/tasks/status.md) for details. We recommend polling every 3–5 seconds with an overall timeout of 3 minutes.

### Success Response Example

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx.png"
          ],
          "expires_at": 1791539365
        }
      ]
    }
  }
}
```

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

### Task Status

| Status | Meaning |
| - | - |
| `pending` | Queued, continue polling |
| `processing` | Generating, continue polling |
| `completed` | Success, `result.images` available |
| `failed` | Failed, check `error.message` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.