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

# Hy-Image-3.5 Preview Génération d’images

> Génération texte-image, jusqu’à 5 images de référence, sorties 1K / 2K / 4K ou dimensions exactes. Une image par requête.

<Info>
  Cet endpoint est asynchrone. Après soumission, récupérez l’ID dans `data[0].task_id` et consultez le [suivi des tâches](/fr/api-reference/tasks/status) pour l’état et l’image. Interrogez toutes les 3–5 secondes, avec un délai global côté client recommandé de 5 minutes. Arrêtez à `completed` ou `failed`.
</Info>

<RequestExample>
  ```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": "hy-image-v3.5-preview",
      "prompt": "A golden retriever running on a beach in warm evening light",
      "size": "16:9",
      "resolution": "2K"
    }'
  ```

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

  response = requests.post(
      "https://api.apimart.ai/v1/images/generations",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "hy-image-v3.5-preview",
          "prompt": "A golden retriever running on a beach in warm evening light",
          "size": "16:9",
          "resolution": "2K"
      }
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.apimart.ai/v1/images/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "hy-image-v3.5-preview",
      prompt: "A golden retriever running on a beach in warm evening light",
      size: "16:9",
      resolution: "2K"
    })
  });
  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01K..."
      }
    ]
  }
  ```
</ResponseExample>

## En-têtes de requête

<ParamField header="Authorization" type="string" required>
  Authentification Bearer : `Bearer <token>`, où `<token>` est votre APIMart API Key.
</ParamField>

## Paramètres de requête

<ParamField body="model" type="string" required>
  Valeur fixe : `hy-image-v3.5-preview`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Description de génération ou de retouche. Chinois et anglais acceptés ; ne doit pas être vide.
</ParamField>

<ParamField body="size" type="string" default="auto">
  Rapport d’aspect ou dimensions exactes en pixels.

  * Rapport : `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
  * Pixels exacts : par exemple `2000x1104`, sous réserve des limites ci-dessous.
  * `auto` ou omis : le modèle choisit le rapport selon le prompt.

  Avec des dimensions exactes, `resolution` ne détermine pas les dimensions de sortie.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  Niveau de résolution : `1K`, `2K` ou `4K` ; par défaut `1K`.

  Avec des dimensions exactes, ce champ ne détermine pas la taille. Utilisez toujours une valeur prise en charge ; sinon HTTP 400.
</ParamField>

<ParamField body="width" type="integer">
  Largeur exacte en pixels. À fournir avec `height` ; prioritaire sur `size` et `resolution`.

  Largeur de 256 à 8192 ; largeur × hauteur ne doit pas dépasser 8 294 400. Multiples de 16 recommandés.
</ParamField>

<ParamField body="height" type="integer">
  Hauteur exacte en pixels. À fournir avec `width`.

  Hauteur de 256 à 8192 ; largeur × hauteur ne doit pas dépasser 8 294 400. Multiples de 16 recommandés.
</ParamField>

<ParamField body="image_urls" type="string[]">
  URL publiques des images de référence, maximum 5. Sans images : texte-image ; avec images : génération à partir de références via le même endpoint.

  JPEG, PNG et WEBP acceptés. Moins de 7MB par image recommandé. Les URL doivent être publiques.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Contenu à exclure de l’image.
</ParamField>

<ParamField body="seed" type="integer">
  Graine aléatoire ; entier positif ou nul. `0` ou omission utilise une valeur aléatoire.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Une seule image par requête. Seul `1` est accepté ; les autres valeurs renvoient HTTP 400.
</ParamField>

## Choix des dimensions

Priorité : paire `width` / `height` → pixels exacts dans `size` → rapport ou `auto` dans `size` associé à `resolution`.

En pixels exacts, largeur et hauteur entre 256 et 8192 chacune, avec au maximum 8 294 400 pixels au total. Multiples de 16 recommandés pour les deux.

### Exemple en pixels exacts

```json theme={null}
{
  "model": "hy-image-v3.5-preview",
  "prompt": "A minimalist seaside travel poster with a warm sunset",
  "width": 2000,
  "height": 1104
}
```

Vous pouvez aussi omettre `width` et `height` et transmettre `"size": "2000x1104"`.

### Exemple avec image de référence

```json theme={null}
{
  "model": "hy-image-v3.5-preview",
  "prompt": "Make the car in the reference image red, preserving the original background and lighting",
  "image_urls": ["https://example.com/car.png"],
  "size": "16:9",
  "resolution": "2K",
  "negative_prompt": "blur, text watermarks",
  "seed": 42,
  "n": 1
}
```

Remplacez les URL d’exemple par des adresses publiques réelles. Pour plusieurs références, ajoutez des URL dans `image_urls`, jusqu’à 5 images au total.

## Réponse de soumission

<ResponseField name="code" type="integer">
  Code de réponse ; `200` indique un succès.
</ResponseField>

<ResponseField name="data" type="array">
  Résultat de soumission de la tâche.

  <Expandable title="Afficher les champs de la tâche">
    <ResponseField name="status" type="string">
      `submitted` indique une soumission réussie, pas la fin de la génération.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      ID de tâche pour consulter l’état et les résultats.
    </ResponseField>
  </Expandable>
</ResponseField>

## Consulter les résultats

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

Exemple de réponse réussie (URL d’image fictive) :

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.png"]
        }
      ]
    }
  }
}
```

* `pending` / `processing` : continuer les interrogations.
* `completed` : lire l’URL dans `data.result.images[0].url[0]` ; `url` est un tableau de chaînes.
* `failed` : arrêter les interrogations et lire la cause dans `data.error.message`. Remboursement intégral. Les prompts non conformes et les refus de modération sont aussi traités comme des échecs.

Les images sont stockées sur le CDN de la plateforme. Téléchargez-les avant l’échéance `expires_at` indiquée dans le résultat.

## Facturation

Facturation par image. Consultez les [tarifs des modèles](https://apimart.ai/pricing).

* Avec un rapport d’aspect, la facturation suit le niveau `resolution`.
* Avec des pixels exacts, le côté le plus court détermine le niveau :

| Niveau | Côté le plus court |
| - | - |
| 1K | Jusqu’à 1024 pixels |
| 2K | 1025–2048 pixels |
| 4K | Plus de 2048 pixels |

Les tâches échouées sont intégralement remboursées.

## Erreurs de paramètres fréquentes

Les cas suivants renvoient HTTP 400 de manière synchrone, sans création de tâche ni facturation :

| Problème | Action |
| - | - |
| `prompt` vide | Fournir un prompt non vide |
| `n` différent de `1` | Demander une seule image par requête |
| `seed` négatif | Utiliser un entier positif ou nul ; `0` signifie aléatoire |
| `resolution` non prise en charge | Utiliser `1K`, `2K` ou `4K` |
| Rapport `size` non pris en charge | Utiliser l’un des 10 rapports ci-dessus ou `auto` |
| Dimensions hors limites | Largeur et hauteur de 256 à 8192 chacune, total maximal de 8 294 400 pixels |
| Plus de 5 images de référence | Réduire `image_urls` à 5 images maximum |


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