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

# Generación de imágenes con MAI-Image-2.7

>  - Modo de procesamiento asíncrono, devuelve un ID de tarea para consultas posteriores
- Admite texto a imagen, edición de imágenes con una sola referencia y composición de varias imágenes, con hasta 5 imágenes de referencia
- Versión de alta calidad `mai-image-2.7` y versión rápida `mai-image-2.7-flash`, con las mismas capacidades y parámetros
- El tamaño de salida se controla con `size` (relación de aspecto) + `resolution` (`1K` / `2K`), o indicando directamente los píxeles
- Máximo de 2048×2048 por imagen (unos 4,19 millones de píxeles), 1 imagen por generación 

```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": "Póster de un campus universitario al atardecer, estilo de fotografía realista, iluminación cinematográfica",
    "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": "Póster de un campus universitario al atardecer, estilo de fotografía realista, iluminación cinematográfica",
    "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: "Póster de un campus universitario al atardecer, estilo de fotografía realista, iluminación cinematográfica",
  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":     "Póster de un campus universitario al atardecer, estilo de fotografía realista, iluminación cinematográfica",
        "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 / resolution not supported / pixel 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"
  }
}
```

## Autorizaciones

**Authorization** `string` *required*

Todos los endpoints requieren autenticación con Bearer Token

Obtenga su API Key:

Visite la [página de gestión de API Keys](https://apimart.ai/keys) para obtener su API Key

Inclúyala en el encabezado de la solicitud:

```
Authorization: Bearer YOUR_API_KEY
```

## Body

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

Nombre del modelo de generación de imágenes

| Modelo | Descripción |
| - | - |
| `mai-image-2.7` | Versión de alta calidad, ideal cuando la calidad de imagen es prioritaria |
| `mai-image-2.7-flash` | Versión rápida, con calidad ligeramente inferior, mayor velocidad y menor coste |

Ambos modelos tienen exactamente las mismas capacidades y parámetros.

**nsfw\_check** `boolean` (default: false)

Indica si se debe moderar el contenido antes de enviar la tarea de imagen.

* `true`: revisar los prompts y las imágenes de entrada con `omni-moderation-latest`
* `false` u omitido: no enviar una solicitud de moderación, sin coste ni latencia de moderación adicionales (predeterminado)

**prompt** `string` *required*

Descripción textual o instrucción de edición para generar la imagen

* Admite chino e inglés, se recomiendan descripciones detalladas
* Hasta 20.000 caracteres; si se supera, devuelve 400
* No puede estar vacío ni contener solo espacios en blanco

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

Número de imágenes a generar

Valor: `1`

> [!WARNING]
>
> Solo se genera 1 imagen por solicitud; para varias imágenes, envíe tareas separadas. Los valores `0`, negativos o mayores que 1 devuelven 400

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

Relación de aspecto o dimensiones en píxeles de la imagen; solo aplica a texto a imagen

Admite dos formatos:

* **Relación de aspecto**: cualquier proporción de enteros entre `1:4` y `4:1`, como `1:1`, `16:9`, `9:16`, `21:9`; junto con `resolution` determina los píxeles reales
* **Dimensiones en píxeles**: `anchoxalto` (también admite `ancho*alto` y `ancho×alto`), como `2048x1152`; en este caso se ignora `resolution`

Límites de las dimensiones en píxeles:

* Ancho y alto **≥ 768**
* Ancho × alto **≤ 4.194.304** (2048×2048)
* El ancho y el alto se redondean hacia abajo, cada uno, a un múltiplo de 32; por ejemplo, `1000x1000` produce `992x992`

Ejemplos: ✅ `2048x2048`, `2048x1152`, `2560x1536`; ❌ `512x512` (lado menor que 768), `2080x2048` (supera el total de píxeles)

> [!WARNING]
>
> No se admite `auto`; si se envía, devuelve 400

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

Nivel de resolución de salida; solo aplica cuando `size` es una relación de aspecto

Opciones: `1K` / `2K` (también en minúsculas)

Correspondencia `size × resolution` → píxeles reales:

| 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]
>
> No se admite `4K`; otros niveles devuelven 400. Como el lado corto debe ser al menos 768, las relaciones más alargadas que 2:1 superan aproximadamente 1 millón de píxeles en el nivel `1K`.

**width** `integer`

Ancho exacto en píxeles; debe enviarse junto con `height`

* Máxima prioridad: si se envían, sustituyen a `size` y `resolution`
* Mismos límites que las dimensiones en píxeles de `size`: ancho y alto ≥ 768, total de píxeles ≤ 4.194.304
* Solo aplica a texto a imagen

**height** `integer`

Alto exacto en píxeles; debe enviarse junto con `width`, con los mismos límites que `width`

**image\_urls** `array`

Array de imágenes de referencia; si se proporciona, activa el modo imagen a imagen

* 1 imagen para edición individual, varias imágenes para composición

**Detalles**

* Hasta 5 imágenes de referencia
* Admite `URL de imagen` (enlace directo accesible públicamente; si no es accesible, la tarea fallará)
* Admite `data URI base64` (p. ej., `data:image/png;base64,...`)
* Admite JPEG y PNG; WEBP y GIF se convierten automáticamente a PNG
* El modelo determina las dimensiones de salida según las imágenes de referencia; `size` / `resolution` / `width` / `height` no tienen efecto en imagen a imagen

**background** `string`

Tipo de fondo

Opciones: `auto` / `opaque`, con el mismo efecto que omitir el parámetro

> [!WARNING]
>
> El fondo transparente (`transparent`) aún no está disponible; enviar `transparent` u otro valor devuelve 400

> [!NOTE]
>
> No se admiten `auto_aspect_ratio: true` ni `web_grounding: true`; si se envían, devuelven 400. `quality`, `style`, `output_format`, `response_format` y `mask_url` no se admiten y se ignoran. La salida siempre es PNG.

## Ejemplos de uso

**Texto a imagen (solicitud mínima)**

Por defecto `1:1` + `1K`, salida de 1024×1024.

```json theme={null}
{
  "model": "mai-image-2.7",
  "prompt": "Póster de un campus universitario al atardecer, estilo de fotografía realista, iluminación cinematográfica"
}
```

**Texto a imagen (con proporción + 2K)**

```json theme={null}
{
  "model": "mai-image-2.7",
  "prompt": "Póster de un campus universitario al atardecer, estilo de fotografía realista, iluminación cinematográfica",
  "size": "3:2",
  "resolution": "2K"
}
```

**Texto a imagen (píxeles exactos)**

```json theme={null}
{
  "model": "mai-image-2.7-flash",
  "prompt": "Frasco de perfume de cristal sobre una encimera de mármol blanco, fotografía de producto limpia",
  "width": 2048,
  "height": 2048
}
```

**Edición individual**

```json theme={null}
{
  "model": "mai-image-2.7",
  "prompt": "Haz que la bicicleta sea azul y añade un perro pequeño a su lado",
  "image_urls": [
    "https://example.com/bicycle.png"
  ]
}
```

**Composición de varias imágenes (URL + base64 combinados)**

```json theme={null}
{
  "model": "mai-image-2.7-flash",
  "prompt": "Combina ambas imágenes de referencia en una foto de producto limpia y futurista",
  "image_urls": [
    "https://example.com/first.png",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}
```

## Response

**code** `integer`

Código de estado de la respuesta

**data** `array`

Array de datos de la respuesta

**Propiedades**

**status** `string`

Estado de la tarea

* `submitted` - Enviada

**task\_id** `string`

Identificador único de la tarea, usado para consultar posteriormente sus resultados

## Consulta de resultados de la tarea

Tras un envío correcto, se devuelve un `task_id`. Consulte el estado de la tarea mediante `GET /v1/tasks/{task_id}`; consulte la [API de consulta de tareas](https://docs.apimart.ai/es/api-reference/tasks/status.md) para más detalles. Se recomienda consultar cada 3–5 segundos, con un tiempo de espera total de 3 minutos.

### Ejemplo de respuesta exitosa

```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
        }
      ]
    }
  }
}
```

Acceso a la imagen: `data.result.images[0].url[0]`. El enlace de la imagen caduca después de `expires_at`; descárguela y guárdela cuanto antes.

### Estado de la tarea

| Estado | Significado |
| - | - |
| `pending` | En cola, siga consultando |
| `processing` | Generándose, siga consultando |
| `completed` | Éxito, `result.images` disponible |
| `failed` | Falló, compruebe `error.message` |


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