> ## 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 Seedream 5.5

> Générez des images à partir de texte ou de 10 références au maximum : fond transparent, décomposition en calques configurable et OCR via une API asynchrone.

```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": "seedream-5-5",
  "prompt": "An orange cat sticker with clean edges",
  "size": "2K",
  "background": "transparent",
  "output_format": "png"
}'
```

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

payload = {
  "model": "seedream-5-5",
  "prompt": "An orange cat sticker with clean edges",
  "size": "2K",
  "background": "transparent",
  "output_format": "png"
}
response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const payload = {
  "model": "seedream-5-5",
  "prompt": "An orange cat sticker with clean edges",
  "size": "2K",
  "background": "transparent",
  "output_format": "png"
};
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

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

Envoyez la requête à `POST /v1/images/generations`, conservez `data[0].task_id`, puis consultez `GET /v1/tasks/{task_id}`.

## Modes

| Mode | Activation | Images d’entrée | Prompt |
| - | - | - | - |
| Génération d’images | Par défaut | 0–10 | Obligatoire |
| Décomposition en calques | `layer_decomposition: true` | Exactement 1 | Facultatif |

## Authentification

**Authorization** `string` *required*

Utilisez `Authorization: Bearer <token>`, où `<token>` est votre APIMart API Key.

## Paramètres de requête

**model** `string` *required*

Utilisez `seedream-5-5`.

**prompt** `string`

Obligatoire pour la génération depuis du texte ou des images. Facultatif pour la décomposition : le modèle identifie automatiquement sujets, texte et arrière-plan. Vous pouvez préciser les éléments à séparer.

**image\_urls** `string[]`

Jusqu’à 10 références en génération ; exactement 1 image en décomposition. URL d’image publique ou Data URI Base64. Pour un fichier local, utilisez l’[API de téléversement](https://docs.apimart.ai/fr/api-reference/uploads/images.md) puis transmettez l’`url` reçue.

Utilisez des URL `http(s)` accessibles publiquement ou `data:image/<format>;base64,…`, avec le nom du format en minuscules dans la Data URI.

* Formats acceptés : JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC et HEIF. AVIF et JP2 ne sont pas acceptés.
* Par image : **30 MiB (31,457,280 octets)** et **36 millions de pixels au total** maximum. Vérifiez largeur × hauteur ; ce n’est pas une limite de 6000 pixels par côté.
* Un dépassement de taille ou de pixels renvoie HTTP 400 immédiatement. AVIF et JP2 peuvent créer une tâche avant son rejet en amont ; les échecs sont remboursés. Convertissez ces formats avant l’envoi.

L’endpoint de téléversement a ses propres restrictions de format. Pour un format accepté par le modèle mais pas par cet endpoint, utilisez une URL publique ou une Data URI.

**size** `string`

Génération : `2K` par défaut, palier, ratio ou dimensions exactes. Décomposition : `auto` par défaut, uniquement `1K` / `1.5K` / `2K` / `auto`.

En génération d’images, `size: "auto"` équivaut à `2K`. Un ratio sans `resolution` utilise aussi `2K`. Pour des dimensions exactes, omettez `resolution` et utilisez des entiers positifs pour largeur et hauteur.

**resolution** `string`

En génération, utilisez `1K` / `1.5K` / `2K` avec un ratio dans `size`. En décomposition, c’est un alias fourni par la plateforme : `size` est prioritaire, `resolution` ne sert que si `size` est omis ; sans les deux, la valeur est `auto`. Valeurs admises : `1K` / `1.5K` / `2K` / `auto`. Les ratios ou pixels sont rejetés de façon synchrone avec HTTP 400. Pas de `3K` / `4K`.

**background** `string`

Génération : `auto` (défaut), `transparent` ou `opaque`. Le fond transparent est disponible depuis du texte ou des images. Il nécessite PNG et exclut `output_format: "jpeg"`. En décomposition, omettez entièrement ce champ, y compris `auto`.

**output\_format** `string` (default: png)

`png` (défaut) ou `jpeg`. En décomposition, concerne uniquement l’image de base ; les calques extraits sont toujours des PNG transparents.

**n** `integer`

Uniquement `1`. La génération produit une image par requête. Utilisez `layer_decomposition_options.max_images` pour le nombre d’images en décomposition.

**watermark** `boolean` (default: false)

Indicateur facultatif d’ajout d’un filigrane.

**optimize\_prompt\_options** `object`

Seul `{"mode":"standard"}` est accepté. Omettre le paramètre active toujours `standard` par défaut chez le fournisseur ; l’optimisation ne peut pas être désactivée dans Seedream 5.5. Le fournisseur rejette `disabled` / `none` / `off` avec HTTP 400 et `must be one of: standard`. La plateforme rejette immédiatement `fast` avec HTTP 400.

**layer\_decomposition** `boolean`

`true` sépare l’entrée en image de base et calques transparents. Exige exactement une image et l’absence de `background`. `output_format` concerne uniquement la base.

**layer\_decomposition\_options** `object`

Uniquement avec `layer_decomposition: true`, sinon HTTP 400.

**Paramètres de requête**

**max\_images** `integer` (default: 30)

Entier de `2` à `100`, défaut `30`. Plafond total des images de sortie, base comprise, sans garantie d’atteindre ce nombre.

**text\_recognition** `boolean` (default: false)

Booléen facultatif. `true` demande l’OCR avec styles des calques de texte. `text_recognition` peut apparaître uniquement pour du texte régulier identifiable.

Avec l’OCR activé, fournir `prompt` peut empêcher le retour des résultats de reconnaissance. Si l’OCR est prioritaire, essayez sans prompt de décomposition. Cela ne garantit pas de résultat : ces champs restent facultatifs.

## Formats de taille

| Format | Exemple | Règles |
| - | - | - |
| Palier | `"size": "2K"` | `1K` / `1.5K` / `2K` ; défaut `2K`. Le modèle choisit le ratio selon le prompt. |
| Ratio + palier | `"size": "16:9", "resolution": "1.5K"` | Génération uniquement. Ratios ci-dessous ; notation `16x9` acceptée. |
| Pixels exacts | `"size": "2048x1152"` | Génération uniquement. Total : 921 600–4 624 220 pixels ; largeur/hauteur : 1/16–16. |

Ratios : `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9`, `2:1`, `1:2`.

Les limites portent sur la surface en pixels et le ratio. La décomposition accepte uniquement les paliers ou `auto`, pas les ratios ni les dimensions exactes.

### Dimensions des sorties en décomposition

* Priorité : `size` → `resolution` → `auto`. `resolution` est un alias de la plateforme ; seul `size` est transmis au fournisseur. `size: "1K"` avec `resolution: "2K"` applique `1K` ; `resolution: "1.5K"` seul applique `1.5K`.

* Avec `1K` / `1.5K` / `2K`, la base et chaque calque sont produits au palier choisi en conservant chacun son propre ratio. Une base mesurée en `1K` faisait `840×1248`, les calques étant aussi proches de 1,05 million de pixels chacun. Ce sont des exemples, pas des dimensions fixes.

* `auto` utilise les dimensions d’origine : les entrées sous `1K` sont agrandies à `1K`, celles au-dessus de `2K` sont réduites à `2K`.

## Exemples de requête

### Édition et fusion de références

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedream-5-5",
  "prompt": "Combine the product in the first image with the setting in the second image",
  "image_urls": ["https://example.com/product.png", "https://example.com/setting.jpg"],
  "size": "16:9",
  "resolution": "1.5K",
  "output_format": "png"
}'
```

### Décomposition et OCR

Cette requête produit au maximum 10 images, base comprise. `prompt` est facultatif ; omettez `background`. Remplacez l’URL par une image accessible.

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedream-5-5",
  "image_urls": ["https://example.com/poster.png"],
  "layer_decomposition": true,
  "layer_decomposition_options": {
    "max_images": 10,
    "text_recognition": true
  },
  "size": "1K"
}'
```

## Consulter une tâche

Utilisez l’[API de statut](https://docs.apimart.ai/fr/api-reference/tasks/status.md) toutes les 3 secondes pendant les 30 premières secondes, puis toutes les 5–10 secondes. La décomposition peut durer plusieurs minutes ; le serveur attend au maximum 13 minutes. Conservez `task_id` et interrogez jusqu’à un état final sans renvoyer la génération.

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/tasks/task_example_seedream55' \
  --header 'Authorization: Bearer <token>'
```

Dans `data.status`, `pending` / `processing` signifie en cours, `completed` signifie réussi. En cas de `failed`, lisez `data.error.message` ; les frais sont remboursés automatiquement. Les URL sont dans `data.result.images[].url[]`.

> [!WARNING]
>
> Les images de résultat sont conservées **3 jours** ; téléchargez-les rapidement. Les enregistrements des tâches sont également conservés 3 jours, après quoi ils ne peuvent plus être consultés par `task_id`.
>
> `data.result.images[].expires_at` renvoie actuellement un timestamp Unix en secondes égal à la fin de la tâche + 24 heures. Cette indication prudente précède la suppression réelle. Ne l’utilisez pas pour calculer la durée réelle de conservation ou un compte à rebours avant suppression.

## Résultats des calques et OCR

Cet exemple illustre la structure, pas une exécution enregistrée. Dimensions, coordonnées et texte sont indicatifs. Les métadonnées peuvent être absentes.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_seedream55",
    "status": "completed",
    "progress": 100,
    "completed": 1794302642,
    "result": {
      "images": [
        {
          "url": ["https://example.com/base.png", "https://example.com/title.png"],
          "sizes": ["840x1248", "1512x702"],
          "output_formats": ["png", "png"],
          "backgrounds": ["opaque", "transparent"],
          "expires_at": 1794389042,
          "layer_decomposition": true,
          "layers": [
            {
              "z_index": 0,
              "size": "840x1248",
              "output_format": "png",
              "background": "opaque"
            },
            {
              "z_index": 1,
              "size": "1512x702",
              "output_format": "png",
              "background": "transparent",
              "name": "Sale title",
              "description": "Printed sale title",
              "bounding_box": {
                "absolute": [84, 156, 756, 468],
                "normalized": [100, 125, 900, 375]
              },
              "text_recognition": {
                "text": "SUMMER SALE",
                "lines": [
                  {
                    "bounding_box": {
                      "absolute": [126, 156, 714, 468],
                      "normalized": [150, 125, 850, 375]
                    },
                    "runs": [
                      {
                        "text": "SUMMER SALE",
                        "style": {
                          "similar_font_family": "Arial",
                          "foreground_color": "#222222",
                          "bold": true,
                          "italic": false,
                          "underline": false,
                          "strikethrough": false,
                          "shadow": false,
                          "translucent": false
                        }
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }
}
```

Dans chaque objet `data.result.images[]`, `url`, `sizes`, `output_formats`, `backgrounds` et `layers` correspondent par indice. Un tableau de métadonnées peut être omis si sa longueur diffère de celle de `url`.

| Champ | Description |
| - | - |
| `url[]` | URL des images. En décomposition, l’indice 0 est la base, suivie des calques. Téléchargez et conservez les fichiers rapidement. |
| `sizes[]` / `output_formats[]` | Dimensions et format réels de chaque image. |
| `backgrounds[]` | Fond réel : `opaque` / `transparent`. Consultez cette valeur avec `background: "auto"`. |
| `expires_at` | Actuellement, timestamp Unix égal à la fin de la tâche + 24 heures (86400 secondes). Cette indication prudente ne correspond pas à la suppression réelle de l’image ; ne l’utilisez pas pour un compte à rebours. |
| `layer_decomposition` | Indique un résultat de décomposition. |
| `layers[i].z_index` | Ordre de superposition : base à 0, composition par ordre croissant. |
| `layers[i].background` | Base : `opaque` ; calques extraits : `transparent`. |
| `layers[i].name` / `description` | Nom et description facultatifs du calque. |
| `layers[i].bounding_box` | `absolute` : `[left, top, right, bottom]` en pixels de la base. `normalized` : même cadre normalisé sur 0–1000. Absent sur la base. |
| `layers[i].text_recognition` | Présent éventuellement si l’OCR est activé et reconnaît du texte régulier ; absent pour les lettrages artistiques, manuscrits et calques sans texte. |

Coordonnées absolues : `x=left`, `y=top`, `w=right-left`, `h=bottom-top`. Pour un canevas de `W × H`, convertissez les coordonnées normalisées ainsi :

```text theme={null}
x = left / 1000 * W
y = top / 1000 * H
w = (right - left) / 1000 * W
h = (bottom - top) / 1000 * H
```

Les fichiers des calques sont dimensionnés séparément au palier choisi et peuvent différer de leur `bounding_box`. Pour composer, redimensionnez chaque calque à `w × h` puis placez-le en `(x, y)`. N’utilisez pas directement les pixels du fichier comme coordonnées de la base.

### Champs de reconnaissance de texte

`text_recognition` suit la structure OCR du modèle en amont. La plateforme transmet sans modification les champs tels que `text`, `lines`, `runs` et `style`.

| Champ | Description |
| - | - |
| `text` | Texte complet du calque, lignes séparées par `\n`. |
| `lines[].bounding_box` | Cadre de la ligne dans le repère de la base. |
| `lines[].runs[]` | Fragments de styles distincts dans une ligne, chacun avec `text` et `style`. |
| `runs[].style.similar_font_family` | Police reconnue la plus proche, sinon `unknown`. |
| `runs[].style.foreground_color` | Couleur du texte au format `#RRGGBB`. |
| `runs[].style.bold` / `italic` / `underline` / `strikethrough` / `shadow` / `translucent` | Indicateurs de style booléens estimés par le modèle, potentiellement imprécis. |

L’OCR et les polices facilitent l’affichage, la copie ou l’édition, sans garantir une correspondance exacte avec l’original. Les images restent utilisables sans OCR.

## Facturation

Les images produites et les références d’entrée sont facturées séparément. **Chaque référence est payante, y compris la première** et l’unique entrée utilisée pour la décomposition.

* Chaque sortie est classée selon ses pixels réels : jusqu’à **2,610,000** pixels inclus, palier bas ; au-delà, palier haut. `1K` / `1.5K` correspondent au palier bas, `2K` au palier haut. Les dimensions exactes utilisent largeur × hauteur.
* La génération réserve le prix du palier de sortie choisi plus nombre de références × prix d’entrée. Sans `size` ou avec `auto`, la réservation utilise `2K`.
* La décomposition réserve `max_images` × prix du palier de sortie **plus une image d’entrée**. `max_images` vaut 30 par défaut, fond inclus ; le résultat réel peut contenir moins d’images.
* La décomposition utilise le `size` effectif, sinon `resolution` : `1K` / `1.5K` réservent au palier bas, `2K` / `auto` au palier haut. Sans les deux, `auto` réserve au palier haut.
* Le règlement dépend du nombre réel de sorties, du palier de pixels de chaque image et du nombre d’entrées, avec remboursement ou complément. Le fond et chaque calque comptent séparément ; n’appliquez pas uniformément le palier demandé à toutes les sorties. Les tâches échouées sont intégralement remboursées.

Voir les [tarifs des modèles](https://apimart.ai/pricing).

## Erreurs de paramètres courantes

Cette liste couvre les validations de la plateforme et du fournisseur. Consultez `error.message` en cas d’échec à l’envoi et `data.error.message` pour une tâche asynchrone échouée.

| Extrait d’erreur | Solution |
| - | - |
| `does not support optimize_prompt_options.mode=fast` | La plateforme renvoie HTTP 400 de façon synchrone. Seul `standard` est accepté ; l’omission laisse l’optimisation active. |
| `must be one of: standard` | HTTP 400 du fournisseur : `disabled` / `none` / `off` ne sont pas acceptés ; la désactivation est impossible. |
| `only supports background auto, transparent or opaque` | Utilisez `auto`, `transparent` ou `opaque`. |
| `cannot combine background=transparent with output_format=jpeg` | Utilisez `output_format: "png"` pour la transparence. |
| `does not accept background when layer_decomposition=true` | Supprimez `background`, même `auto`, en décomposition. |
| `layer_decomposition_options requires layer_decomposition=true` | Envoyez cet objet uniquement en décomposition. |
| `layer_decomposition_options.max_images must be within [2, 100]` | `max_images` doit être un entier de 2 à 100, base comprise. |
| `invalid layer_decomposition_options` | Utilisez un entier pour `max_images`, pas une chaîne ni un décimal ; un booléen pour `text_recognition`. |
| `with layer_decomposition=true requires exactly 1 input image` | Fournissez exactement une image en décomposition. |
| `only supports size 1K, 1.5K, 2K or auto` | En décomposition, priorité à `size`, sinon `resolution`. Uniquement `1K` / `1.5K` / `2K` / `auto` ; ratios ou pixels renvoient HTTP 400 de façon synchrone. |
| `` `n` must be 1 `` | Fixez `n` à `1` ; pas de génération par lots. |
| `does not support stream` / `does not support tools` | Supprimez `sequential_image_generation`, `stream` et `tools`. |
| `supports up to 10 reference images` | Fournissez au maximum 10 références. |
| `reference image too large for seedream-5-5` | Chaque référence doit faire au plus 30 MiB et ne pas dépasser 36 millions de pixels. Compressez ou redimensionnez avant de réessayer. |
| `does not support size` / `requires total pixels` / `requires aspect ratio` | Vérifiez le nombre de pixels, le ratio et la notation de taille. 3K / 4K non pris en charge. |
| `` `prompt` parameter is required `` | La génération d’images exige un prompt. Seule la décomposition permet de l’omettre. |

## Motifs d’échec des tâches

Si `data.status` vaut `failed`, consultez `data.error.message` et `data.error.reason`. Les frais sont remboursés automatiquement. Si `reason` est absent ou inconnu, utilisez `message` comme indication de secours.

| `data.error.reason` | Action |
| - | - |
| `content_policy_violation` | L’entrée ou la sortie a échoué au contrôle de contenu. Modifiez le prompt ou les images. |
| `invalid_parameter` / `unsupported_option` | Paramètre ou combinaison non pris en charge. Modifiez la requête. |
| `invalid_media` | Image d’entrée endommagée ou format non pris en charge. Vérifiez et convertissez l’image. |
| `media_unreachable` | URL de l’image inaccessible. Vérifiez l’accès public ou téléversez à nouveau. |
| `generation_timeout` | Délai de génération dépassé. Réessayez plus tard. |
| `service_unavailable` | Service temporairement occupé. Réessayez plus tard. |
| `delivery_failed` / `internal_error` / `unknown_error` | Erreur de livraison ou erreur interne. Suivez le message retourné et réessayez plus tard. |


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