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

> Text-zu-Bild, bis zu 5 Referenzbilder und 1K / 2K / 4K oder exakte Pixelmaße. Ein Bild pro Anfrage.

<Info>
  Dieser Endpunkt arbeitet asynchron. Nach dem Absenden die Task-ID aus `data[0].task_id` lesen und Status und Bild über die [Task-Abfrage](/de/api-reference/tasks/status) abrufen. Alle 3–5 Sekunden abfragen; empfohlenes Gesamtzeitlimit des Clients: 5 Minuten. Bei `completed` oder `failed` stoppen.
</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>

## Request-Header

<ParamField header="Authorization" type="string" required>
  Bearer-Authentifizierung: `Bearer <token>`. `<token>` ist Ihr APIMart API Key.
</ParamField>

## Request-Parameter

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

<ParamField body="prompt" type="string" required>
  Textbeschreibung für Generierung oder Bearbeitung. Chinesisch und Englisch werden unterstützt; darf nicht leer sein.
</ParamField>

<ParamField body="size" type="string" default="auto">
  Ausgabeseitenverhältnis oder exakte Pixelmaße.

  * Seitenverhältnis: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
  * Exakte Pixelmaße: etwa `2000x1104`; die untenstehenden Grenzen gelten.
  * `auto` oder nicht angegeben: Das Modell entscheidet anhand des Prompts.

  Bei exakten Pixelmaßen bestimmt `resolution` nicht die Bildgröße.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  Auflösungsstufe: `1K`, `2K` oder `4K`; Standard: `1K`.

  Bei exakten Pixelmaßen bestimmt dieses Feld nicht die Größe. Immer einen unterstützten Wert verwenden; andere Werte führen zu HTTP 400.
</ParamField>

<ParamField body="width" type="integer">
  Exakte Ausgabebreite in Pixeln. Muss zusammen mit `height` angegeben werden und hat Vorrang vor `size` und `resolution`.

  Breite: 256–8192; Breite × Höhe darf 8.294.400 nicht überschreiten. Vielfache von 16 werden empfohlen.
</ParamField>

<ParamField body="height" type="integer">
  Exakte Ausgabehöhe in Pixeln. Muss zusammen mit `width` angegeben werden.

  Höhe: 256–8192; Breite × Höhe darf 8.294.400 nicht überschreiten. Vielfache von 16 werden empfohlen.
</ParamField>

<ParamField body="image_urls" type="string[]">
  Öffentliche URLs für maximal 5 Referenzbilder. Ohne Bilder: Text-zu-Bild; mit Bildern: referenzbasierte Generierung über denselben Endpunkt.

  JPEG, PNG und WEBP werden unterstützt. Empfohlen: unter 7MB pro Bild. URLs müssen öffentlich zugänglich sein.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Inhalte, die im Bild nicht erscheinen sollen.
</ParamField>

<ParamField body="seed" type="integer">
  Zufalls-Seed; muss eine nicht negative Ganzzahl sein. `0` oder Auslassen bedeutet zufällig.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Nur ein Bild pro Anfrage. Nur `1` ist zulässig; andere Werte führen zu HTTP 400.
</ParamField>

## Größenauswahl

Priorität: `width` / `height` als Paar → exakte Pixel in `size` → Seitenverhältnis oder `auto` in `size` mit `resolution`.

Bei exakten Pixelmaßen müssen Breite und Höhe jeweils 256–8192 betragen, insgesamt maximal 8.294.400 Pixel. Für beide werden Vielfache von 16 empfohlen.

### Beispiel mit exakten Pixelmaßen

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

Alternativ `width` und `height` weglassen und `"size": "2000x1104"` übergeben.

### Beispiel mit Referenzbild

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

Beispiel-URLs durch tatsächlich öffentlich erreichbare Bild-URLs ersetzen. Für mehrere Referenzen weitere URLs in `image_urls` angeben, insgesamt maximal 5.

## Antwort auf die Übermittlung

<ResponseField name="code" type="integer">
  Antwortstatuscode; `200` bedeutet Erfolg.
</ResponseField>

<ResponseField name="data" type="array">
  Ergebnis der Task-Übermittlung.

  <Expandable title="Task-Felder anzeigen">
    <ResponseField name="status" type="string">
      `submitted` bedeutet erfolgreiche Übermittlung, nicht abgeschlossene Bildgenerierung.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Task-ID zur Abfrage von Status und Ergebnis.
    </ResponseField>
  </Expandable>
</ResponseField>

## Task-Ergebnisse abfragen

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

Beispiel einer erfolgreichen Antwort (Bild-URL ist ein Platzhalter):

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

* `pending` / `processing`: weiter abfragen.
* `completed`: Bild-URL aus `data.result.images[0].url[0]` lesen; `url` ist ein Array aus Zeichenfolgen.
* `failed`: Abfragen stoppen und Ursache aus `data.error.message` lesen. Vollständige Erstattung. Prompt-Verstöße und abgelehnte Inhalte werden ebenfalls als Fehlschlag behandelt.

Bilder werden im Plattform-CDN gespeichert. Vor dem in `expires_at` angegebenen Zeitpunkt herunterladen und sichern.

## Abrechnung

Abrechnung pro Bild. Aktuelle Preise unter [Modellpreise](https://apimart.ai/pricing).

* Bei Seitenverhältnissen wird nach der `resolution`-Stufe abgerechnet.
* Bei exakten Pixelmaßen bestimmt die kürzere Seite die Stufe:

| Stufe | Kürzere Seite |
| - | - |
| 1K | Bis 1024 Pixel |
| 2K | 1025–2048 Pixel |
| 4K | Über 2048 Pixel |

Fehlgeschlagene Tasks werden vollständig erstattet.

## Häufige Parameterfehler

Folgende Fälle geben synchron HTTP 400 zurück, ohne Task-Erstellung oder Kosten:

| Problem | Vorgehen |
| - | - |
| Leerer `prompt` | Nicht leeren Prompt angeben |
| `n` ist nicht `1` | Nur ein Bild pro Anfrage anfordern |
| Negativer `seed` | Nicht negative Ganzzahl verwenden; `0` bedeutet zufällig |
| Nicht unterstützte `resolution` | `1K`, `2K` oder `4K` verwenden |
| Nicht unterstütztes Seitenverhältnis in `size` | Eines der 10 Verhältnisse oben oder `auto` verwenden |
| Pixelmaße außerhalb der Grenzen | Breite und Höhe jeweils 256–8192, insgesamt maximal 8.294.400 Pixel |
| Mehr als 5 Referenzbilder | `image_urls` auf maximal 5 Bilder reduzieren |


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