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

# MAI Image 2.7

> The MAI Image 2.7 API from Microsoft generates one image from a prompt, edits a reference image, or combines up to 5 reference images. It supports 1K and 2K output, custom sizes up to about 4 megapixels, transparent backgrounds, and PNG, JPEG, or WebP output.

> [!TIP]
>
> 1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
> 2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](https://docs.poyo.ai/api-manual/task-management/status.md) endpoint.

Use `mai-image-2.7` to create posters, product shots, logos, and other images from a prompt, or to edit and combine reference images. For a faster, lower-cost option with the same parameters, use [MAI Image 2.7 Flash](https://docs.poyo.ai/api-manual/image-series/mai-image-2-7-flash.md).

## Models

* **mai-image-2.7** — Microsoft MAI Image 2.7 for text-to-image, image editing, and multi-image composition

## Features

* Text-to-image generation from prompts of up to 32,000 characters.
* Editing a single reference image, or combining up to 5 reference images into one image.
* Seven aspect ratios at `1K` or `2K`, plus custom `WIDTHxHEIGHT` sizes up to 4,194,304 pixels.
* Transparent backgrounds for PNG and WebP output.
* PNG, JPEG, or WebP output.

## Input modes

* **Text-to-image** — Omit `image_urls`. The output size comes from `size` and `resolution`.
* **Editing / composition** — Pass 1 to 5 URLs in `image_urls`. One image is edited; two or more images are combined into one. Without `size`, the output follows the aspect ratio of the first reference image at about 1 megapixel. With `size`, the output uses that size.

## Required parameters

* `prompt` (string): Description of the image or the requested edit, 1–32,000 characters. Must contain non-whitespace text. Put any exact on-image text in quotes.

## Optional parameters

* `image_urls` (array of strings): 1 to 5 publicly accessible HTTP(S) reference image URLs in JPEG, PNG, or WebP format. Selects editing / composition mode.
* `size` (string): `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `16:9`, `9:16`, or a custom `WIDTHxHEIGHT`. Text-to-image defaults to `1:1`. See [Size](#size).
* `resolution` (string): `1K` or `2K`. Default is `1K`. Applies to aspect-ratio sizes.
* `background` (string): `opaque` or `transparent`. Default is `opaque`. `transparent` requires `output_format` `png` or `webp`.
* `output_format` (string): `png`, `jpeg`, or `webp`. Default is `png`.

## Size

* Aspect ratios: `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `16:9`, `9:16`. `1K` outputs about 1 megapixel (for example, `1:1` is 1024×1024). `2K` outputs about 4 megapixels (for example, `16:9` is 2720×1536).
* Custom `WIDTHxHEIGHT` sizes need both sides divisible by 16, each side at least 768, and total pixels at most 4,194,304 (for example `2048x2048` or `3072x1344`). A custom size is used exactly as given; `resolution` applies to aspect-ratio sizes.
* In editing / composition mode without `size`, the output follows the aspect ratio of the first reference image at about 1 megapixel.

## Output

* Each request returns one image in the format set by `output_format` (`png` by default).
* With `background` set to `transparent`, the image has an alpha channel. Use it with `output_format` `png` or `webp`.

## Examples

### Text To Image

```json theme={"dark"}
{
  "model": "mai-image-2.7",
  "input": {
    "prompt": "A university campus poster at dusk with the title \"Open Day 2026\", photorealistic, cinematic light",
    "size": "16:9",
    "resolution": "2K"
  }
}
```

### Image Edit

```json theme={"dark"}
{
  "model": "mai-image-2.7",
  "input": {
    "prompt": "Change the bicycle to blue and add a small dog next to it",
    "image_urls": [
      "https://example.com/bicycle.png"
    ]
  }
}
```

### Custom Size

```json theme={"dark"}
{
  "model": "mai-image-2.7",
  "input": {
    "prompt": "A wide panoramic banner of a mountain range at sunrise",
    "size": "3072x1344"
  }
}
```

### Transparent Background

```json theme={"dark"}
{
  "model": "mai-image-2.7",
  "input": {
    "prompt": "A flat vector logo of a red fox head, clean edges, no background",
    "background": "transparent",
    "output_format": "webp"
  }
}
```

## Notes

* Each request returns one image.
* `image_urls` must be an array, even for one image.
* Reference images are used at up to about 1 megapixel.


## OpenAPI

````yaml api-manual/image-series/mai-image-2-7.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: PoYo AI - MAI Image 2.7 API
  description: >-
    The MAI Image 2.7 API from Microsoft generates one image from a prompt,
    edits a reference image, or combines up to 5 reference images. It supports
    1K and 2K output, custom sizes up to about 4 megapixels, transparent
    backgrounds, and PNG, JPEG, or WebP output.
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
    description: Production server
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - MAI Image 2.7
      summary: Submit MAI Image 2.7 Task
      description: >-
        MAI Image 2.7 single-image generation, reference-image editing, and
        multi-image composition with transparent background and output format
        options.
      operationId: submitMAIImage27Task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              text-to-image:
                summary: Text To Image
                value:
                  model: mai-image-2.7
                  input:
                    prompt: >-
                      A university campus poster at dusk with the title "Open
                      Day 2026", photorealistic, cinematic light
                    size: '16:9'
                    resolution: 2K
              image-edit:
                summary: Image Edit
                value:
                  model: mai-image-2.7
                  input:
                    prompt: Change the bicycle to blue and add a small dog next to it
                    image_urls:
                      - https://example.com/bicycle.png
              custom-size:
                summary: Custom Size
                value:
                  model: mai-image-2.7
                  input:
                    prompt: A wide panoramic banner of a mountain range at sunrise
                    size: 3072x1344
              transparent-background:
                summary: Transparent Background
                value:
                  model: mai-image-2.7
                  input:
                    prompt: >-
                      A flat vector logo of a red fox head, clean edges, no
                      background
                    background: transparent
                    output_format: webp
      responses:
        '200':
          description: Task submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      additionalProperties: false
      properties:
        model:
          type: string
          enum:
            - mai-image-2.7
          description: MAI Image 2.7 model identifier.
        callback_url:
          type: string
          format: uri
          description: Optional webhook URL for task completion or failure.
        input:
          type: object
          additionalProperties: false
          required:
            - prompt
          description: >-
            Generate one image. With image_urls, edit or combine the reference
            images.
          properties:
            prompt:
              type: string
              minLength: 1
              maxLength: 32000
              description: >-
                Prompt describing the image or the requested edit. Must contain
                non-whitespace text. Put exact on-image text in quotes.
            image_urls:
              type: array
              minItems: 1
              maxItems: 5
              items:
                type: string
                format: uri
              description: >-
                Optional 1–5 reference image URLs (JPEG, PNG, or WebP). Must be
                an array, even for one image. One image is edited; several
                images are combined. Without size, the output follows the aspect
                ratio of the first reference image at about 1 megapixel.
                Reference images are used at up to about 1 megapixel. Each URL
                must be a publicly accessible HTTP or HTTPS URL.
            size:
              type: string
              default: '1:1'
              description: >-
                Aspect ratio or custom WIDTHxHEIGHT. Supported values: 1:1, 4:3,
                3:4, 3:2, 2:3, 16:9, 9:16, or WIDTHxHEIGHT. Text-to-image
                defaults to 1:1. Custom sizes need both sides divisible by 16,
                each side at least 768, and total pixels at most 4194304 (for
                example 2048x2048 or 3072x1344) and are used exactly as given.
                With image_urls and no size, the output follows the aspect ratio
                of the first reference image at about 1 megapixel.
              example: '16:9'
            resolution:
              type: string
              enum:
                - 1K
                - 2K
              default: 1K
              description: >-
                Output resolution tier for aspect-ratio sizes. 1K is about 1
                megapixel (1:1 is 1024x1024); 2K is about 4 megapixels (16:9 is
                2720x1536).
            background:
              type: string
              enum:
                - opaque
                - transparent
              default: opaque
              description: >-
                Background type. transparent outputs an image with an alpha
                channel and requires output_format png or webp.
            output_format:
              type: string
              enum:
                - png
                - jpeg
                - webp
              default: png
              description: Output image format.
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
          description: >-
            Business status code. `200` means success; any other value means the
            request failed. Always check this field: some validation errors
            return HTTP 200 with `code: 400` in the body.


            - `200`: Success

            - `400`: Invalid request parameters

            - `401`: Missing or invalid API key

            - `402`: Insufficient credits

            - `403`: Permission denied

            - `404`: Resource not found

            - `408`: Request timeout

            - `429`: Rate limit exceeded

            - `500`: Internal server error

            - `502`: Upstream service error

            - `503`: Service unavailable


            See [Error Codes](/api-manual/error-codes) for details.
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              example: task-unified-1794383400-abcd1234
              description: Unique task identifier for status tracking
            status:
              type: string
              enum:
                - not_started
                - running
                - finished
                - failed
              example: not_started
              description: >-
                Task status. Always `not_started` right after submission. Use
                [Query Task Status](/api-manual/task-management/status) or
                `callback_url` to get later states.


                - `not_started`: Queued, waiting to be processed

                - `running`: Being generated

                - `finished`: Completed; results are in `files` or `output`

                - `failed`: Failed; details are in `error_message`
            created_time:
              type: string
              format: date-time
              example: '2026-11-11T10:30:00'
              description: ISO 8601 timestamp when the task was created
    ErrorResponse:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: integer
          example: 400
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            Business status code. `200` means success; any other value means the
            request failed. Always check this field: some validation errors
            return HTTP 200 with `code: 400` in the body.


            - `200`: Success

            - `400`: Invalid request parameters

            - `401`: Missing or invalid API key

            - `402`: Insufficient credits

            - `403`: Permission denied

            - `404`: Resource not found

            - `408`: Request timeout

            - `429`: Rate limit exceeded

            - `500`: Internal server error

            - `502`: Upstream service error

            - `503`: Service unavailable


            See [Error Codes](/api-manual/error-codes) for details.
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              example: Invalid request parameters
            type:
              type: string
              example: invalid_request_error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        All API endpoints require Bearer Token authentication.


        Create an API key: sign in to PoYo, open **Dashboard → API Key** at
        [poyo.ai/dashboard/api-key](https://poyo.ai/dashboard/api-key), and
        click to create a key.


        Add it to the request header:


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

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