> ## 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 longues Kling V4 Long Image

> Créez des fiches produit ou des maquettes de pages web en 1K / 2K. Longueurs short / medium / long pour le commerce, références de produit, style et sujet. Un PNG 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": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "nsfw_check": true
}'
```

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

payload = {
  "model": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "nsfw_check": True
}
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": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "nsfw_check": true
};
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_kling_v4_long_image"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": "invalid_request_error",
    "message": "reference image is not accessible for kling-v4-long-image: image_urls[0] returned HTTP 404; make sure the URL is public and still valid",
    "param": "",
    "type": "invalid_request_error"
  }
}
```

Envoyez une requête asynchrone à `POST /v1/images/generations` avec `model: "kling-v4-long-image"`. Récupérez `data[0].task_id`, puis consultez `GET /v1/tasks/{task_id}`. Chaque requête renvoie un PNG vertical ; le mode web produit une image de la maquette.

## Choisir un mode

| Mode | `skill` | Références | Longueur |
| - | - | - | - |
| Fiche produit | `ecommerce` | `image_urls` : 1–3 images produit obligatoires | `short` / `medium` / `long` |
| Maquette web | `webpage` | `image_with_roles` : style et sujet facultatifs, une image de chaque au maximum | Omettre `length` |

## Authentification

**Authorization** `string` *required*

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

## Paramètres de requête

**model** `string` *required*

Doit être `kling-v4-long-image`.

**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*

Obligatoire et non vide, y compris après suppression des espaces. Jusqu’à 166 000 caractères en anglais seul, 71 000 en chinois ou langues similaires ; calcul proportionnel pour les textes mixtes. Décrivez la disposition, les sections, les textes, le style et le sujet.

**skill** `string` *required*

Obligatoire : `ecommerce` pour une fiche produit ou `webpage` pour une maquette web, sans distinction de casse. Les champs de référence diffèrent selon le mode.

**length** `string` (default: medium)

Uniquement pour `skill: "ecommerce"` : `short`, `medium` (par défaut) ou `long`, soit environ 2–5, 6–10 ou 11–18 sections. Le contenu et la hauteur réels dépendent du résultat. Omettez ce champ en mode web, sinon HTTP 400.

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

Accepte `1K` (par défaut) et `2K`, sans distinction de casse, pour toutes les longueurs commerciales, y compris `long + 2K`. Largeur de sortie : 1024 ou 2048 px ; la hauteur dépend du contenu. `4K` n’est pas pris en charge.

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

Uniquement pour le commerce : 1–3 images produit obligatoires. En mode web, omettez ce champ et utilisez `image_with_roles`. Fournissez des URL directes publiques. Les fichiers locaux peuvent être envoyés via l’[API d’envoi d’images](https://docs.apimart.ai/fr/api-reference/uploads/images.md), puis référencés par l’`url` renvoyée.

**image\_with\_roles** `object[]`

Facultatif, uniquement en mode web. Au plus une image `style` et une image `subject` ; une ou les deux peuvent être omises. Omettez ce champ en mode commerce.

**Élément du tableau**

**url** `string` *required*

URL directe et publique de l’image de référence.

**role** `string` *required*

`style` guide le style visuel et la disposition ; `subject` indique le sujet à conserver. Chaque rôle ne peut apparaître qu’une fois.

**n** `integer`

Chaque requête génère une seule image longue. Omettez le champ ou utilisez l’entier `1` ; les autres valeurs renvoient HTTP 400.

**watermark** `boolean`

Omettez le champ ou utilisez `false` ; `true` renvoie HTTP 400.

> [!WARNING]
>
> N’envoyez pas `size`, `aspect_ratio`, `width`, `height`, `mask_url`, `sequential_image_generation` ni `sequential_image_generation_options`. Même `null` ou une chaîne vide dans ces champs renvoie HTTP 400.

## Exigences et références dans le prompt

Formats JPG / JPEG / PNG. Au plus 30 MB par image, au moins 300 px sur chaque côté, rapport entre 2:5 et 5:2. Une URL renvoyant HTTP 403 / 404 / 410, des dimensions ou un rapport invalides, ou un fichier trop volumineux provoque HTTP 400 synchrone, sans tâche ni frais de génération. Les autres échecs de récupération, comme un délai du serveur d’origine dépassé, sont d’abord acceptés ; la tâche échoue ensuite et les frais prélevés sont remboursés.

Utilisez `@Image1`, `@Image2`, etc. dans le prompt. En commerce, l’ordre suit `image_urls` ; en web, le style précède le sujet. Si une seule image est fournie, elle correspond à `@Image1`.

## Exemples de requêtes

Envoyez ces requêtes à `POST /v1/images/generations`. Remplacez les URL d’exemple par des liens directs accessibles.

### Fiche produit longue en 2K

```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": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a long product detail page using the front view in @Image1, side view in @Image2, and close-up in @Image3. Include key features, materials, use scenes, and care instructions.",
  "image_urls": [
    "https://example.com/product-front.jpg",
    "https://example.com/product-side.jpg",
    "https://example.com/product-detail.png"
  ],
  "length": "long",
  "resolution": "2K"
}'
```

### Page web avec références de style et de sujet

```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": "kling-v4-long-image",
  "skill": "webpage",
  "prompt": "Design a product landing page using the visual style of @Image1 and preserving the product in @Image2. Include a hero section, features, and a call to action.",
  "image_with_roles": [
    {
      "url": "https://example.com/style.png",
      "role": "style"
    },
    {
      "url": "https://example.com/product.jpg",
      "role": "subject"
    }
  ],
  "resolution": "2K"
}'
```

### Page web à partir du prompt uniquement

```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": "kling-v4-long-image",
  "skill": "webpage",
  "prompt": "Design a welcoming coffee shop webpage with warm colors, a hero section, a menu, and store information",
  "resolution": "1K"
}'
```

## Consulter la tâche

Interrogez l’[API de suivi des tâches](https://docs.apimart.ai/fr/api-reference/tasks/status.md) environ toutes les 10 secondes. Conservez le `task_id` et évitez de soumettre à nouveau la génération si l’attente se prolonge.

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

| État (`data.status`) | Traitement |
| - | - |
| `pending` / `processing` | Continuez les requêtes. `data.cost` est le montant prélevé à l’avance et `data.billing_status` vaut `held`. |
| `completed` | Lisez `data.result.images[0].url[0]`. `data.billing_status` vaut `settled` et `data.cost` est le montant final. |
| `failed` | Lisez `data.error.message`. `data.billing_status` vaut `refunded`, `data.cost` vaut `0` ; les frais prélevés sont entièrement remboursés. |

Voici la structure d’un résultat réussi. `images` et `url` sont des tableaux ; ce modèle renvoie une seule image longue par requête.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_kling_v4_long_image",
    "status": "completed",
    "progress": 100,
    "billing_status": "settled",
    "result": {
      "images": [
        {
          "url": [
            "https://example.com/generated-long-image.png"
          ],
          "expires_at": 1795331293
        }
      ]
    }
  }
}
```

Téléchargez l’image avant l’horodatage Unix en secondes indiqué par `data.result.images[0].expires_at`. Le lien expire ensuite.

> [!NOTE]
>
> La génération prend généralement plusieurs minutes ; un exemple `long + 2K` a pris 432 secondes. `estimated_time` renvoie actuellement toujours 60 secondes : ne l’utilisez ni comme compte à rebours ni comme seuil d’expiration. La durée varie avec le contenu et la charge ; cet exemple n’est pas une limite.
>
> La hauteur et le poids varient selon le contenu. Un exemple `long + 2K` mesurait `2048×46615` et 63,9 MB ; ces valeurs ne sont pas des limites. Les résultats peuvent dépasser 50 MB : prévoyez le coût de téléchargement et d’affichage des grandes images.

## Facturation

Chaque requête facture une image longue au niveau de sortie choisi, plus les références : **prix du niveau de sortie + nombre de références × prix par référence**. Produit, style et sujet sont tous comptés ; la première référence est payante.

Les 8 niveaux sont listés ci-dessous. Clés tarifaires : `kling-v4-long-image@<niveau>` et `kling-v4-long-image@input` pour les références. Dans la requête de génération, `resolution` reste limité à `1K` ou `2K`.

| Mode | Longueur | `1K` | `2K` |
| - | - | - | - |
| Fiche produit | `short` | `1K-SHORT` | `2K-SHORT` |
| Fiche produit | `medium` | `1K-MEDIUM` | `2K-MEDIUM` |
| Fiche produit | `long` | `1K-LONG` | `2K-LONG` |
| Maquette web | Omettre `length` | `1K-WEBPAGE` | `2K-WEBPAGE` |

Les frais sont prélevés à l’envoi, finalisés en cas de succès et entièrement remboursés en cas d’échec. Consultez la [page des tarifs](https://apimart.ai/pricing) pour les prix et remises du compte.

## Erreurs courantes

Ces erreurs renvoient HTTP 400 de manière synchrone, sans tâche ni frais de génération. Les erreurs d’envoi figurent dans `error.message`, celles après création dans `data.error.message`.

| Extrait de l’erreur | Solution |
| - | - |
| `` `prompt` is required for kling-v4-long-image `` | Fournissez un prompt non vide. |
| `` `skill` is required for kling-v4-long-image `` | Fournissez `skill`. |
| `` `skill` must be ecommerce or webpage for kling-v4-long-image `` | Utilisez `ecommerce` ou `webpage`. |
| `` skill=ecommerce on kling-v4-long-image requires 1 to 3 product images in `image_urls` `` | Le commerce exige 1–3 images produit. |
| `` skill=ecommerce on kling-v4-long-image supports at most 3 product images in `image_urls` `` | Au maximum 3 images produit. |
| `` `image_with_roles` is only for skill=webpage on kling-v4-long-image `` | En commerce, utilisez `image_urls` et omettez `image_with_roles`. |
| `` `length` must be short, medium or long for kling-v4-long-image `` | Utilisez `short`, `medium` ou `long`. |
| `` `length` only applies to skill=ecommerce for kling-v4-long-image `` | Omettez `length` en mode web. |
| `` skill=webpage on kling-v4-long-image does not take `image_urls` `` | En web, omettez `image_urls` et utilisez `image_with_roles`. |
| `` `image_with_roles[0].role` must be style or subject for kling-v4-long-image `` | Utilisez uniquement `style` ou `subject`. |
| `kling-v4-long-image supports at most 1 image with role style` | Une image par rôle au maximum ; le sujet ne peut pas non plus être dupliqué. |
| `` `resolution` must be 1K or 2K for kling-v4-long-image `` | Utilisez `1K` ou `2K`. |
| `` `size` is not supported by kling-v4-long-image `` | Retirez les champs de dimensions, rapport ou série non acceptés ; pas de `null` ni de chaîne vide. |
| `` `n` is not supported by kling-v4-long-image: each request returns one long image `` | Omettez `n` ou utilisez l’entier `1`. |
| `reference image is not accessible for kling-v4-long-image` | Vérifiez l’accès public, la validité du lien et les réponses 403 / 404 / 410. |
| `unsupported reference image dimensions for kling-v4-long-image` | Au moins 300 px par côté, rapport de 2:5 à 5:2. |
| `reference image too large for kling-v4-long-image` | Au plus 30 MB par référence. |


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