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

# Génération d'images MAI-Image-2.7

>  - Mode de traitement asynchrone, renvoie un ID de tâche pour les requêtes ultérieures
- Texte en image, retouche d'une image et composition de plusieurs images, jusqu'à 5 images de référence
- Version haute qualité `mai-image-2.7` et version rapide `mai-image-2.7-flash`, avec les mêmes capacités et paramètres
- Taille de sortie contrôlée par `size` (ratio d'aspect) + `resolution` (`1K` / `2K`), ou directement en pixels
- Jusqu'à 2048×2048 (environ 4,19 mégapixels) par image, 1 image par requête 

```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": "Affiche photoréaliste d’un campus universitaire au coucher du soleil, éclairage cinématographique",
    "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": "Affiche photoréaliste d’un campus universitaire au coucher du soleil, éclairage cinématographique",
    "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: "Affiche photoréaliste d’un campus universitaire au coucher du soleil, éclairage cinématographique",
  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":     "Affiche photoréaliste d’un campus universitaire au coucher du soleil, éclairage cinématographique",
        "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 limits exceeded, 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"
  }
}
```

## Autorisations

**Authorization** `string` *required*

Tous les points de terminaison nécessitent une authentification Bearer Token

Obtenir votre clé API :

Rendez-vous sur la [page de gestion des clés API](https://apimart.ai/keys) pour obtenir votre clé API

Incluez-la dans l'en-tête de la requête :

```
Authorization: Bearer YOUR_API_KEY
```

## Body

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

Nom du modèle de génération d'images

| Modèle | Description |
| - | - |
| `mai-image-2.7` | Version haute qualité, pour les usages privilégiant le rendu |
| `mai-image-2.7-flash` | Version rapide, qualité légèrement inférieure, plus rapide et moins chère |

Les deux modèles ont exactement les mêmes capacités et paramètres.

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

Indique s'il faut modérer le contenu avant d'envoyer la tâche d'image.

* `true` : vérifier les prompts et les images d'entrée avec `omni-moderation-latest`
* `false` ou omis : ne pas envoyer de requête de modération, sans coût ni latence de modération supplémentaires (par défaut)

**prompt** `string` *required*

Description textuelle de l'image à générer ou instructions de retouche

* Prend en charge le chinois et l'anglais, des descriptions détaillées sont recommandées
* 20 000 caractères maximum ; au-delà, une erreur 400 est renvoyée
* Ne peut pas être vide ni composé uniquement d'espaces

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

Nombre d'images à générer

Valeur : `1`

> [!WARNING]
>
> Une seule image par requête : soumettez des tâches séparées pour plusieurs images. Une valeur `0`, négative ou supérieure à 1 renvoie 400

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

Ratio d'aspect ou dimensions en pixels de l'image, uniquement pour le texte en image

Deux formats sont acceptés :

* **Ratio d'aspect** : tout rapport d'entiers entre `1:4` et `4:1`, par exemple `1:1`, `16:9`, `9:16`, `21:9` ; combiné à `resolution`, il détermine les pixels réels
* **Dimensions en pixels** : `largeurxhauteur` (ou `largeur*hauteur`, `largeur×hauteur`), par exemple `2048x1152` ; `resolution` est alors ignoré

Contraintes des dimensions en pixels :

* Largeur et hauteur **≥ 768** chacune
* Largeur × hauteur **≤ 4 194 304** (2048×2048)
* Largeur et hauteur sont chacune arrondies au multiple de 32 inférieur, par exemple `1000x1000` produit en réalité `992x992`

Exemples : ✅ `2048x2048`, `2048x1152`, `2560x1536` ; ❌ `512x512` (côté inférieur à 768), `2080x2048` (nombre total de pixels dépassé)

> [!WARNING]
>
> `auto` n'est pas pris en charge et renvoie 400

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

Niveau de résolution de sortie, uniquement lorsque `size` est un ratio d'aspect

Options : `1K` / `2K` (minuscules acceptées)

Correspondance `size × resolution` → pixels réels :

| 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]
>
> La `4K` n'est pas prise en charge ; tout autre niveau renvoie 400. Le petit côté devant atteindre au moins 768, les ratios plus allongés que 2:1 dépassent en réalité environ 1 million de pixels au niveau `1K`.

**width** `integer`

Largeur exacte en pixels, à fournir obligatoirement avec `height`

* Priorité la plus élevée : lorsqu'elle est fournie, elle remplace `size` et `resolution`
* Mêmes contraintes que les dimensions en pixels de `size` : largeur et hauteur ≥ 768, total ≤ 4 194 304 pixels
* Uniquement pour le texte en image

**height** `integer`

Hauteur exacte en pixels, à fournir obligatoirement avec `width`, mêmes contraintes que `width`

**image\_urls** `array`

Tableau d'images de référence ; lorsqu'il est fourni, passe en mode image en image

* 1 image pour la retouche d'une image, plusieurs pour la composition de plusieurs images

**Détails**

* Jusqu'à 5 images de référence
* Prend en charge `URL d'image` (lien direct accessible publiquement ; une URL inaccessible fait échouer la tâche)
* Prend en charge `base64 data URI` (par exemple `data:image/png;base64,...`)
* Formats JPEG et PNG acceptés ; WEBP et GIF sont convertis automatiquement en PNG
* La taille de sortie est déterminée par le modèle d'après les images de référence ; `size` / `resolution` / `width` / `height` sont sans effet en image en image

**background** `string`

Type d'arrière-plan

Options : `auto` / `opaque`, même effet que sans ce paramètre

> [!WARNING]
>
> L'arrière-plan transparent `transparent` n'est pas encore disponible ; `transparent` ou toute autre valeur renvoie 400

> [!NOTE]
>
> `auto_aspect_ratio: true` et `web_grounding: true` ne sont pas pris en charge et renvoient 400. `quality`, `style`, `output_format`, `response_format` et `mask_url` ne sont pas pris en charge et sont ignorés. La sortie est toujours au format PNG.

## Exemples d'utilisation

**Texte en image (requête minimale)**

Par défaut `1:1` + `1K`, sortie en 1024×1024.

```json theme={null}
{
  "model": "mai-image-2.7",
  "prompt": "Affiche photoréaliste d’un campus universitaire au coucher du soleil, éclairage cinématographique"
}
```

**Texte en image (avec ratio + 2K)**

```json theme={null}
{
  "model": "mai-image-2.7",
  "prompt": "Affiche photoréaliste d’un campus universitaire au coucher du soleil, éclairage cinématographique",
  "size": "3:2",
  "resolution": "2K"
}
```

**Texte en image (pixels exacts)**

```json theme={null}
{
  "model": "mai-image-2.7-flash",
  "prompt": "Flacon de parfum en verre sur un plan de travail en marbre blanc, photo de produit épurée",
  "width": 2048,
  "height": 2048
}
```

**Retouche d'une image**

```json theme={null}
{
  "model": "mai-image-2.7",
  "prompt": "Rendez le vélo bleu et ajoutez un petit chien à côté",
  "image_urls": [
    "https://example.com/bicycle.png"
  ]
}
```

**Composition de plusieurs images (URL + base64 mélangés)**

```json theme={null}
{
  "model": "mai-image-2.7-flash",
  "prompt": "Combinez les deux images de référence en une photo de produit épurée et futuriste",
  "image_urls": [
    "https://example.com/first.png",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}
```

## Response

**code** `integer`

Code de statut de la réponse

**data** `array`

Tableau de données de réponse

**Propriétés**

**status** `string`

Statut de la tâche

* `submitted` — Soumise

**task\_id** `string`

Identifiant unique de la tâche, utilisé pour les requêtes ultérieures de résultats

## Interrogation des résultats de tâche

Après une soumission réussie, un `task_id` est renvoyé. Interrogez l'état de la tâche via `GET /v1/tasks/{task_id}`, voir [API d'interrogation des tâches](https://docs.apimart.ai/fr/api-reference/tasks/status.md) pour plus de détails. Nous vous recommandons d'interroger toutes les 3 à 5 secondes, avec un délai d'expiration global de 3 minutes.

### Exemple de réponse en cas de succès

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

Accès à l'image : `data.result.images[0].url[0]`. Le lien de l'image expire après `expires_at` ; téléchargez-la et enregistrez-la dès que possible.

### Statuts de tâche

| Statut | Signification |
| - | - |
| `pending` | En file d'attente, continuer l'interrogation |
| `processing` | Génération en cours, continuer l'interrogation |
| `completed` | Succès, `result.images` disponible |
| `failed` | Échec, voir `error.message` |


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