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

# Kling V4 Long Image Bilderzeugung

> Lange Produktdetailbilder und Webseitenentwürfe in 1K / 2K erzeugen. Unterstützt short / medium / long für E-Commerce sowie Produkt-, Stil- und Motivvorlagen. Eine PNG-Datei pro Anfrage.

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

Senden Sie mit `model: "kling-v4-long-image"` eine asynchrone Anfrage an `POST /v1/images/generations`. Lesen Sie `data[0].task_id` aus und fragen Sie `GET /v1/tasks/{task_id}` ab. Jede Anfrage liefert ein langes PNG; der Webseitenmodus erzeugt ein Bild des Seitendesigns.

## Modus wählen

| Modus | `skill` | Referenzbilder | Länge |
| - | - | - | - |
| Produktdetailseite | `ecommerce` | `image_urls`: 1–3 Produktbilder erforderlich | `short` / `medium` / `long` |
| Webseitendesign | `webpage` | `image_with_roles`: optional je ein Stil- und Motivbild | `length` weglassen |

## Authentifizierung

**Authorization** `string` *required*

Verwenden Sie `Authorization: Bearer <token>`. `<token>` ist Ihr APIMart-API-Schlüssel.

## Anfrageparameter

**model** `string` *required*

Muss `kling-v4-long-image` sein.

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

Legt fest, ob der Inhalt vor dem Absenden des Bildauftrags moderiert wird.

* `true`: Prompts und Eingabebilder mit `omni-moderation-latest` prüfen
* `false` oder nicht angegeben: keine Moderationsanfrage und damit keine zusätzlichen Moderationskosten oder Verzögerung (Standard)

**prompt** `string` *required*

Erforderlich und nicht nur Leerzeichen. Maximal 166.000 Zeichen bei rein englischem Text und 71.000 bei rein chinesischem Text und ähnlichen Sprachen; gemischte Texte werden anteilig berechnet. Beschreiben Sie Layout, Abschnitte, Texte, Stil und Motiv.

**skill** `string` *required*

Erforderlich: `ecommerce` für Produktdetailseiten oder `webpage` für Webseitendesigns, unabhängig von Groß- und Kleinschreibung. Die Modi verwenden unterschiedliche Referenzfelder.

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

Nur für `skill: "ecommerce"`: `short`, `medium` (Standard) oder `long`, ungefähr 2–5, 6–10 bzw. 11–18 Inhaltsabschnitte. Inhalt und Höhe richten sich nach dem Ergebnis. Im Webseitenmodus muss das Feld fehlen, sonst folgt HTTP 400.

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

Unterstützt `1K` (Standard) und `2K`, unabhängig von Groß- und Kleinschreibung. Beide gelten für alle E-Commerce-Längen, auch `long + 2K`. Die Ausgabebreite beträgt 1024 bzw. 2048 px; die Höhe hängt vom Inhalt ab. `4K` wird nicht unterstützt.

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

Nur für E-Commerce: 1–3 Produktbilder erforderlich. Im Webseitenmodus weglassen und `image_with_roles` verwenden. Geben Sie öffentlich erreichbare direkte Bild-URLs an. Lokale Dateien können über die [Bild-Upload-API](https://docs.apimart.ai/de/api-reference/uploads/images.md) hochgeladen werden; verwenden Sie anschließend die zurückgegebene `url`.

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

Optional, nur für Webseiten. Höchstens ein Bild mit `style` und eines mit `subject`; eine oder beide Rollen können entfallen. Im E-Commerce-Modus dieses Feld weglassen.

**Array-Element**

**url** `string` *required*

Öffentlich erreichbare direkte URL des Referenzbilds.

**role** `string` *required*

`style` bestimmt die visuelle Gestaltung und das Layout; `subject` das beizubehaltende Motiv. Jede Rolle darf nur einmal vorkommen.

**n** `integer`

Jede Anfrage erzeugt ein langes Bild. Weglassen oder die Ganzzahl `1` angeben; andere Werte führen zu HTTP 400.

**watermark** `boolean`

Weglassen oder `false` angeben; `true` führt zu HTTP 400.

> [!WARNING]
>
> Senden Sie keine Felder `size`, `aspect_ratio`, `width`, `height`, `mask_url`, `sequential_image_generation` oder `sequential_image_generation_options`. Auch `null` oder eine leere Zeichenfolge führt bei diesen Feldern zu HTTP 400.

## Anforderungen und Referenzmarkierungen

Unterstützt JPG / JPEG / PNG. Pro Bild höchstens 30 MB, beide Seiten mindestens 300 px, Seitenverhältnis von 2:5 bis 5:2. HTTP 403 / 404 / 410 der URL, unzulässige Maße oder Verhältnisse sowie zu große Dateien liefern synchron HTTP 400, ohne Aufgabe oder Generierungsgebühr. Andere Abruffehler wie ein Timeout des Ursprungsservers werden zunächst angenommen; die Aufgabe schlägt danach fehl und vorab abgezogene Gebühren werden erstattet.

Nutzen Sie `@Image1`, `@Image2` usw. im Prompt. E-Commerce folgt der Reihenfolge in `image_urls`, Webseiten der Reihenfolge Stil, dann Motiv. Bei nur einer Rolle ist deren Bild `@Image1`.

## Anfragebeispiele

Senden Sie diese Anfragen an `POST /v1/images/generations`. Ersetzen Sie Beispiel-URLs durch erreichbare direkte Bildlinks.

### Lange Produktseite in 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"
}'
```

### Webseite mit Stil- und Motivvorlage

```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"
}'
```

### Webseite nur aus einem Prompt

```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"
}'
```

## Aufgabe abfragen

Fragen Sie die [Aufgaben-API](https://docs.apimart.ai/de/api-reference/tasks/status.md) etwa alle 10 Sekunden ab. Speichern Sie die `task_id` und vermeiden Sie auch bei längeren Wartezeiten doppelte Generierungsanfragen.

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

| Status (`data.status`) | Vorgehen |
| - | - |
| `pending` / `processing` | Weiter abfragen. `data.cost` ist der vorab abgezogene Betrag, `data.billing_status` ist `held`. |
| `completed` | Lesen Sie `data.result.images[0].url[0]`. `data.billing_status` ist `settled`, `data.cost` ist die endgültige Gebühr. |
| `failed` | Lesen Sie `data.error.message`. `data.billing_status` ist `refunded`, `data.cost` ist `0`; vorab abgezogene Gebühren werden vollständig erstattet. |

Das Beispiel zeigt die Struktur eines erfolgreichen Ergebnisses. `images` und `url` sind Arrays; dieses Modell liefert ein langes Bild pro Anfrage.

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

Laden Sie das Bild vor dem Unix-Zeitstempel in Sekunden unter `data.result.images[0].expires_at` herunter. Danach ist der Link ungültig.

> [!NOTE]
>
> Die Generierung dauert meist mehrere Minuten; ein Beispiel für `long + 2K` benötigte 432 Sekunden. `estimated_time` liefert derzeit immer 60 Sekunden und eignet sich nicht als Countdown oder Timeout-Grenze. Die Dauer hängt von Inhalt und Auslastung ab; der Messwert ist keine Obergrenze.
>
> Bildhöhe und Dateigröße hängen vom Inhalt ab. Ein Beispiel für `long + 2K` hatte `2048×46615` Pixel und 63,9 MB; das sind keine Ausgabegrenzen. Ergebnisse können 50 MB überschreiten. Berücksichtigen Sie den Aufwand für Download und Darstellung großer Bilder.

## Abrechnung

Pro Anfrage wird ein langes Bild nach gewählter Ausgabestufe plus Referenzen berechnet: **Preis der Ausgabestufe + Referenzanzahl × Referenzpreis**. Produkt-, Stil- und Motivbilder zählen alle; auch das erste Referenzbild wird berechnet.

Es gibt die folgenden 8 Ausgabestufen. Preisschlüssel: `kling-v4-long-image@<Stufe>`, für Referenzen `kling-v4-long-image@input`. Im Generierungsaufruf bleibt `resolution` auf `1K` oder `2K` beschränkt.

| Modus | Länge | `1K` | `2K` |
| - | - | - | - |
| Produktdetailseite | `short` | `1K-SHORT` | `2K-SHORT` |
| Produktdetailseite | `medium` | `1K-MEDIUM` | `2K-MEDIUM` |
| Produktdetailseite | `long` | `1K-LONG` | `2K-LONG` |
| Webseitendesign | `length` weglassen | `1K-WEBPAGE` | `2K-WEBPAGE` |

Die Gebühr wird bei Einreichung vorab abgezogen, bei Erfolg abgerechnet und bei Fehler vollständig erstattet. Preise und Kontorabatte finden Sie auf der [Preisseite](https://apimart.ai/pricing).

## Häufige Fehler

Diese Validierungsfehler liefern synchron HTTP 400, ohne Aufgabe oder Generierungsgebühr. Einreichungsfehler stehen in `error.message`, Fehler nach Erstellung in `data.error.message`.

| Fehlerauszug | Abhilfe |
| - | - |
| `` `prompt` is required for kling-v4-long-image `` | Geben Sie einen nicht leeren Prompt an. |
| `` `skill` is required for kling-v4-long-image `` | Geben Sie `skill` an. |
| `` `skill` must be ecommerce or webpage for kling-v4-long-image `` | Nutzen Sie `ecommerce` oder `webpage`. |
| `` skill=ecommerce on kling-v4-long-image requires 1 to 3 product images in `image_urls` `` | E-Commerce benötigt 1–3 Produktbilder. |
| `` skill=ecommerce on kling-v4-long-image supports at most 3 product images in `image_urls` `` | Höchstens 3 Produktbilder angeben. |
| `` `image_with_roles` is only for skill=webpage on kling-v4-long-image `` | Für E-Commerce `image_urls` nutzen und `image_with_roles` weglassen. |
| `` `length` must be short, medium or long for kling-v4-long-image `` | Verwenden Sie `short`, `medium` oder `long`. |
| `` `length` only applies to skill=ecommerce for kling-v4-long-image `` | Im Webseitenmodus `length` weglassen. |
| `` skill=webpage on kling-v4-long-image does not take `image_urls` `` | Für Webseiten `image_urls` weglassen und `image_with_roles` nutzen. |
| `` `image_with_roles[0].role` must be style or subject for kling-v4-long-image `` | Nur `style` oder `subject` verwenden. |
| `kling-v4-long-image supports at most 1 image with role style` | Höchstens ein Bild pro Rolle; auch doppelte Motivbilder sind unzulässig. |
| `` `resolution` must be 1K or 2K for kling-v4-long-image `` | Verwenden Sie `1K` oder `2K`. |
| `` `size` is not supported by kling-v4-long-image `` | Entfernen Sie nicht unterstützte Größen-, Verhältnis- oder Serienfelder; kein `null` oder leerer Text. |
| `` `n` is not supported by kling-v4-long-image: each request returns one long image `` | `n` weglassen oder die Ganzzahl `1` verwenden. |
| `reference image is not accessible for kling-v4-long-image` | Öffentlichen Zugriff und URL-Gültigkeit sowie 403 / 404 / 410 prüfen. |
| `unsupported reference image dimensions for kling-v4-long-image` | Beide Seiten mindestens 300 px, Verhältnis 2:5 bis 5:2. |
| `reference image too large for kling-v4-long-image` | Jedes Referenzbild darf höchstens 30 MB groß sein. |


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