# Images

> Référence de POST /v1/images/generations et POST /v1/images/edits : créer et retoucher des images au format d’OpenAI, tailles, formats, limites et coûts.

Deux points d’accès au format de l’API Images d’OpenAI : `POST /v1/images/generations` crée des images à partir d’une description, `POST /v1/images/edits` les crée à partir d’une ou plusieurs images. Les images reviennent dans la réponse, en base64 : Moon AI n’en garde aucune copie et ne fournit pas d’adresse hébergée.

## Créer une image

```http
POST https://api.realmoon.ai/v1/images/generations
```

- Authentification : clé `sk-moon-…` avec la portée `inference` (voir [Authentification](https://realmoon.ai/documentation/api/authentification/)).
- Corps : JSON, 1 Mo au plus.
- Réponse : un objet image (voir [Réponse](https://realmoon.ai/documentation/api/images/#reponse)).

### Paramètres

| Paramètre | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `model` | chaîne | oui | Un modèle de type `image` de `GET /v1/models?type=image`. |
| `prompt` | chaîne | oui | Description de l’image, 8 000 caractères au plus. |
| `n` | entier | non | Nombre d’images, de 1 à 4. 1 par défaut. Facturé par image produite. |
| `size` | chaîne | non | `auto` ou `LARGEURxHAUTEUR`, de 64 à 8 192 pixels de côté. Sert à choisir le format et la taille les plus proches que le modèle propose (voir [Taille et format](https://realmoon.ai/documentation/api/images/#taille)). |
| `aspect_ratio` | chaîne | non | Format parmi ceux du modèle (`aspect_ratios` dans `/v1/models`), par exemple `1:1`, `16:9`, `2:3`. Prioritaire sur le format déduit de `size`. |
| `image_size` | chaîne | non | `1K`, `2K` ou `4K`, pour les modèles qui proposent plusieurs tailles (`image_sizes`). Prioritaire sur la taille déduite de `size`. |
| `quality` | chaîne | non | `auto`, `low`, `medium`, `high`, `standard` ou `hd`. Accepté pour la compatibilité, sans effet : le modèle choisit lui-même. |
| `response_format` | chaîne | non | `b64_json` (par défaut) ou `url`. Avec `url`, l’image arrive sous forme d’adresse `data:`. |
| `stream` | booléen | non | Seule la valeur `false` est acceptée. |

Les paramètres `user`, `style`, `moderation`, `background`, `output_compression`, `output_format`, `partial_images` et `input_fidelity` sont acceptés et sans effet. Tout autre paramètre est refusé avec `400 unknown_parameter`. Une image envoyée dans `image` ou `images` est refusée ici : utilisez [`/v1/images/edits`](https://realmoon.ai/documentation/api/images/#edits).

### Exemple

```bash title="cURL"
curl https://api.realmoon.ai/v1/images/generations \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "google/gemini-3.1-flash-image",
        "prompt": "Une affiche rétro d’une fusée au-dessus de Paris",
        "size": "1024x1536"
      }' \
  | jq -r '.data[0].b64_json' | base64 --decode > affiche.png
```

```python title="Python"
import base64
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.realmoon.ai/v1", api_key=os.environ["MOONAI_API_KEY"])

img = client.images.generate(
    model="google/gemini-3.1-flash-image",
    prompt="Une affiche rétro d’une fusée au-dessus de Paris",
    size="1024x1536",
    # Paramètre propre à Moon AI : passé par extra_body.
    extra_body={"image_size": "2K"},
)
with open("affiche.png", "wb") as f:
    f.write(base64.b64decode(img.data[0].b64_json))
```

```javascript title="JavaScript"
import fs from 'node:fs';
import OpenAI from 'openai';

const client = new OpenAI({ baseURL: 'https://api.realmoon.ai/v1', apiKey: process.env.MOONAI_API_KEY });

const img = await client.images.generate({
  model: 'google/gemini-3.1-flash-image',
  prompt: 'Une affiche rétro d’une fusée au-dessus de Paris',
  size: '1024x1536',
  // Paramètre propre à Moon AI, envoyé tel quel.
  image_size: '2K',
});
fs.writeFileSync('affiche.png', Buffer.from(img.data[0].b64_json, 'base64'));
```

### Taille et format

Quand vous donnez `size` sans `aspect_ratio` ni `image_size` :

- le format retenu est celui du modèle le plus proche du rapport largeur sur hauteur ;
- la taille retenue est `1K` si le plus grand côté fait au plus 1 100 pixels, `2K` jusqu’à 2 200 pixels, `4K` au-delà (ou la plus grande taille du modèle).

L’image produite peut donc avoir des dimensions un peu différentes de `size`. Sans `size`, `aspect_ratio` ni `image_size`, le modèle choisit.

## Retoucher une image

```http
POST https://api.realmoon.ai/v1/images/edits
```

- Authentification : clé `sk-moon-…` avec la portée `inference`.
- Corps : `multipart/form-data` (avec l’en-tête `Content-Length`) ou JSON, 90 Mo au plus.
- Réponse : un objet image (voir [Réponse](https://realmoon.ai/documentation/api/images/#reponse)).

### Paramètres

Tous les paramètres de la [création](https://realmoon.ai/documentation/api/images/#generations) s’appliquent, plus les images :

| Paramètre | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `image` | fichier, chaîne ou tableau | oui | En multipart : un ou plusieurs fichiers dans le champ `image` ou `image[]`. En JSON : une chaîne ou une liste de chaînes (adresse `data:` en base64, base64 seul, ou adresse `https://`). |
| `images` | tableau | non | En JSON, forme d’OpenAI : `[{"image_url": "…"}]`. S’ajoute à `image`. |
| `mask` |  | non | Non accepté (`400 unsupported_parameter`) : décrivez la modification dans la consigne. |

| Règle | Valeur |
| --- | --- |
| Types d’image | PNG, JPEG, WebP, GIF |
| Taille d’une image | 20 Mo et 40 mégapixels au plus |
| Nombre d’images | `max_input_images` du modèle dans `/v1/models` |
| Taille du corps | 90 Mo au plus |

Une image donnée par une adresse `https://` est lue par le fournisseur du modèle, jamais par Moon AI.

### Exemple

```bash title="cURL"
curl https://api.realmoon.ai/v1/images/edits \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -F model=google/gemini-3.1-flash-image \
  -F prompt="Même photo, en noir et blanc" \
  -F image=@photo.png
```

```python title="Python"
edit = client.images.edit(
    model="google/gemini-3.1-flash-image",
    image=open("photo.png", "rb"),
    prompt="Même photo, en noir et blanc",
)
with open("photo-nb.png", "wb") as f:
    f.write(base64.b64decode(edit.data[0].b64_json))

# Plusieurs images : une liste.
combo = client.images.edit(
    model="google/gemini-3.1-flash-image",
    image=[open("produit.png", "rb"), open("decor.png", "rb")],
    prompt="Le produit de la première image posé dans le décor de la seconde",
)
```

```javascript title="JavaScript"
const edit = await client.images.edit({
  model: 'google/gemini-3.1-flash-image',
  image: fs.createReadStream('photo.png'),
  prompt: 'Même photo, en noir et blanc',
});
fs.writeFileSync('photo-nb.png', Buffer.from(edit.data[0].b64_json, 'base64'));
```

Le même appel en JSON, avec une image en base64 et une image à une adresse :

```json title="Corps JSON"
{
  "model": "google/gemini-3.1-flash-image",
  "prompt": "Le produit de la première image posé dans le décor de la seconde",
  "images": [
    { "image_url": "data:image/png;base64,iVBORw0KGgo…" },
    { "image_url": "https://example.com/decor.jpg" }
  ]
}
```

## Réponse

Les deux points d’accès renvoient le même objet.

```json title="Réponse"
{
  "created": 1793577600,
  "model": "google/gemini-3.1-flash-image",
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "output_format": "png" }
  ],
  "usage": { "images": 1, "credits": 650 }
}
```

| Champ | Type | Description |
| --- | --- | --- |
| `created` | entier | Date en secondes Unix. |
| `model` | chaîne | Le modèle appelé. |
| `data[].b64_json` | chaîne | L’image en base64, avec `response_format: "b64_json"`. |
| `data[].url` | chaîne | L’image en adresse `data:`, avec `response_format: "url"`. |
| `data[].output_format` | chaîne | Format du fichier : `png`, `jpeg`, `webp`, `gif` ou `svg`. |
| `usage.images` | entier | Nombre d’images produites. |
| `usage.credits` | entier | Crédits facturés pour la requête. |

Quand vous demandez plusieurs images et que certaines échouent, la réponse ne contient que celles qui ont été produites : comparez `usage.images` à `n`.

En-têtes : `X-Moon-Request-Id`, `X-Moon-Prompt-Storage: none`, `X-Moon-Blur: not_applied` (Moon Blur ne s’applique pas aux images ni à leur description) et `Cache-Control: no-store`.

## Modèles

Liste au 5 novembre 2026 ; la liste à jour, avec les prix, vient de `GET /v1/models?type=image`.

| Modèle | Formats | Tailles | Images en entrée |
| --- | --- | --- | --- |
| `google/gemini-3.1-flash-image` (Nano Banana 2) | 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9 | 1K, 2K, 4K | 8 |
| `google/gemini-3-pro-image` (Nano Banana Pro) | 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9 | 1K, 2K, 4K | 8 |
| `google/gemini-3.1-flash-lite-image` | 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 | 1K, 2K, 4K | 4 |
| `openai/gpt-image-2`, `openai/gpt-image-1-mini` | 1:1, 3:2, 2:3 | une seule | 4 |
| `black-forest-labs/flux.2-pro`, `flux.2-max`, `flux.2-klein-4b`, `flux-3-image` | 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 | une seule | 4 |
| `bytedance-seed/seedream-5-0-pro`, `seedream-5-0-lite` | 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 | une seule | 4 |
| `qwen/qwen-image-3`, `x-ai/grok-imagine-image-2.0` | 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 | une seule | 4 |
| `recraft/recraft-v4.1`, `recraft/recraft-v4.1-vector` (sortie SVG) | 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 | une seule | 4 |

`image_size` n’est accepté que par les modèles à plusieurs tailles.

## Coûts

- Avant l’appel, la requête retient le plus qu’elle peut coûter : `max_credits_per_unit` (ou celui de la taille demandée) fois le nombre d’images, plus les images envoyées.
- Après, vous payez le coût réel annoncé par le fournisseur (à défaut, le prix de la liste), et le reste de la retenue est rendu aussitôt.
- Une requête qui échoue, refusée avant toute création, ou coupée par notre délai, ne coûte rien.
- Un modèle qui répond par du texte au lieu d’une image (refus de sécurité, consigne mal comprise) facture le texte qu’il a écrit, et l’API répond `400 content_policy_violation` : reformulez la consigne.

Voir [Coûts et porte-monnaie](https://realmoon.ai/documentation/api/couts/) pour la réserve et le règlement.

## Limites

- Toutes les images d’une requête sont faites en même temps ; la requête répond en 90 secondes environ au plus.
- Au plus 8 requêtes d’images en cours à la fois par workspace (au-delà : `429 too_many_concurrent`, `Retry-After: 5`).

## Erreurs

| HTTP | `code` | Signification |
| --- | --- | --- |
| 400 | `missing_required_parameter` | `model`, `prompt` ou `image` absent. |
| 400 | `unknown_parameter` | Paramètre inconnu (`param` le nomme). |
| 400 | `unsupported_value` | Valeur hors de ce que le modèle accepte (`n`, `size`, `aspect_ratio`, `image_size`, `quality`, `response_format`). |
| 400 | `unsupported_parameter` | `mask`, `stream`, `image_size` sur un modèle à taille unique, image envoyée à `/generations`, ou paramètre refusé par le modèle (avec une indication). |
| 400 | `unsupported_model` | Le modèle ne fait pas de retouche. |
| 400 | `string_above_max_length` | Consigne de plus de 8 000 caractères. |
| 400 | `too_many_images` | Plus d’images que `max_input_images`. |
| 400 | `invalid_image` | Image illisible, d’un autre type, ou de plus de 40 mégapixels. |
| 400 | `content_policy_violation` | Le système de sécurité du modèle a refusé l’image. |
| 400 | `invalid_request_error` | Le modèle a refusé la requête sans autre précision. |
| 400 | `null` | Corps JSON invalide, base64 invalide, champ de fichier inattendu ou formulaire illisible. |
| 403 | `org_policy` | Les règles de votre organisation refusent ce modèle. |
| 404 | `model_not_found` | Modèle inconnu ou qui ne sert pas ce point d’accès. |
| 411 | `length_required` | Envoi multipart sans en-tête `Content-Length`. |
| 413 | `request_too_large`, `file_too_large` | Corps ou image trop volumineux. |
| 429 | `too_many_concurrent` | Trop de requêtes d’images en cours dans le workspace. |
| 429 | `upstream_rate_limited` | Le modèle est surchargé : réessayez après `Retry-After` (10 secondes). |
| 502, 504 | `upstream_error`, `upstream_timeout` | Le modèle a échoué ou n’a pas répondu à temps. |
| 503 | `upstream_unavailable` | Le service est momentanément indisponible. |

Les erreurs de clé, de solde et de plafonds sont dans [Erreurs](https://realmoon.ai/documentation/api/erreurs/).

## Voir aussi

- [Modèles](https://realmoon.ai/documentation/api/modeles/#medias) : les champs `aspect_ratios`, `image_sizes` et `max_input_images`.
- [Solde et coût d’une requête](https://realmoon.ai/documentation/api/solde/) : relire le coût avec `X-Moon-Request-Id`.

---

Documentation Moon AI › API développeur › Images. Page : https://realmoon.ai/documentation/api/images/. Modifiée le 5 novembre 2026.

© 2026 Stellarr Studio SAS. Tous droits réservés. Moon AI, Moon Blur et Stellarr Studio sont des marques déposées à l’INPI.