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

# Seedream-5.0-Flash Bildgenerierung

>  - Asynchroner Verarbeitungsmodus, gibt eine Aufgaben-ID für nachfolgende Abfragen zurück
- Unterstützt Text-zu-Bild, Bild-zu-Bild mit einem Bild und Generierung mit mehreren Referenzbildern (bis zu 10)
- Unterstützt Auflösungsstufen 1K / 1.5K / 2K oder exakte Pixel über `size`
- Einzelbildmodell: ein Bild pro Anfrage; Ausgabe PNG / JPEG
- Links zu generierten Bildern sind 72 Stunden gültig, bitte speichern Sie sie umgehend 

<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": "seedream-5-0-flash",
      "prompt": "Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen",
      "size": "16:9",
      "resolution": "2K"
    }'
  ```

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

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "seedream-5-0-flash",
      "prompt": "Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen",
      "size": "16:9",
      "resolution": "2K"
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "seedream-5-0-flash",
    prompt: "Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen",
    size: "16:9",
    resolution: "2K"
  };

  const headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
  })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io/ioutil"
      "net/http"
  )

  func main() {
      url := "https://api.apimart.ai/v1/images/generations"

      payload := map[string]interface{}{
          "model":      "seedream-5-0-flash",
          "prompt":     "Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen",
          "size":       "16:9",
          "resolution": "2K",
      }

      jsonData, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", "Bearer <token>")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      body, _ := ioutil.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  public class Main {
      public static void main(String[] args) throws Exception {
          String url = "https://api.apimart.ai/v1/images/generations";

          String payload = """
          {
            "model": "seedream-5-0-flash",
            "prompt": "Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen",
            "size": "16:9",
            "resolution": "2K"
          }
          """;

          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(url))
              .header("Authorization", "Bearer <token>")
              .header("Content-Type", "application/json")
              .POST(HttpRequest.BodyPublishers.ofString(payload))
              .build();

          HttpResponse<String> response = client.send(request,
              HttpResponse.BodyHandlers.ofString());

          System.out.println(response.body());
      }
  }
  ```

  ```php PHP theme={null}
  <?php

  $url = "https://api.apimart.ai/v1/images/generations";

  $payload = [
      "model" => "seedream-5-0-flash",
      "prompt" => "Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen",
      "size" => "16:9",
      "resolution" => "2K"
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer <token>",
      "Content-Type: application/json"
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  echo $response;
  ?>
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  url = URI("https://api.apimart.ai/v1/images/generations")

  payload = {
    model: "seedream-5-0-flash",
    prompt: "Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen",
    size: "16:9",
    resolution: "2K"
  }

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(url)
  request["Authorization"] = "Bearer <token>"
  request["Content-Type"] = "application/json"
  request.body = payload.to_json

  response = http.request(request)
  puts response.body
  ```

  ```swift Swift theme={null}
  import Foundation

  let url = URL(string: "https://api.apimart.ai/v1/images/generations")!

  let payload: [String: Any] = [
      "model": "seedream-5-0-flash",
      "prompt": "Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen",
      "size": "16:9",
      "resolution": "2K"
  ]

  var request = URLRequest(url: url)
  request.httpMethod = "POST"
  request.setValue("Bearer <token>", forHTTPHeaderField: "Authorization")
  request.setValue("application/json", forHTTPHeaderField: "Content-Type")
  request.httpBody = try? JSONSerialization.data(withJSONObject: payload)

  let task = URLSession.shared.dataTask(with: request) { data, response, error in
      if let error = error {
          print("Error: \(error)")
          return
      }

      if let data = data, let responseString = String(data: data, encoding: .utf8) {
          print(responseString)
      }
  }

  task.resume()
  ```

  ```csharp C# theme={null}
  using System;
  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main(string[] args)
      {
          var url = "https://api.apimart.ai/v1/images/generations";

          var payload = @"{
              ""model"": ""seedream-5-0-flash"",
              ""prompt"": ""Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen"",
              ""size"": ""16:9"",
              ""resolution"": ""2K""
          }";

          using var client = new HttpClient();
          client.DefaultRequestHeaders.Add("Authorization", "Bearer <token>");

          var content = new StringContent(payload, Encoding.UTF8, "application/json");
          var response = await client.PostAsync(url, content);
          var result = await response.Content.ReadAsStringAsync();

          Console.WriteLine(result);
      }
  }
  ```

  ```c C theme={null}
  #include <stdio.h>
  #include <curl/curl.h>

  int main(void) {
      CURL *curl;
      CURLcode res;

      curl_global_init(CURL_GLOBAL_DEFAULT);
      curl = curl_easy_init();

      if(curl) {
          const char *url = "https://api.apimart.ai/v1/images/generations";
          const char *payload = "{"
              "\"model\":\"seedream-5-0-flash\","
              "\"prompt\":\"Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen\","
              "\"size\":\"16:9\","
              "\"resolution\":\"2K\""
          "}";

          struct curl_slist *headers = NULL;
          headers = curl_slist_append(headers, "Authorization: Bearer <token>");
          headers = curl_slist_append(headers, "Content-Type: application/json");

          curl_easy_setopt(curl, CURLOPT_URL, url);
          curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
          curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

          res = curl_easy_perform(curl);

          if(res != CURLE_OK) {
              fprintf(stderr, "curl_easy_perform() failed: %s\n",
                      curl_easy_strerror(res));
          }

          curl_slist_free_all(headers);
          curl_easy_cleanup(curl);
      }

      curl_global_cleanup();
      return 0;
  }
  ```

  ```objectivec Objective-C theme={null}
  #import <Foundation/Foundation.h>

  int main(int argc, const char * argv[]) {
      @autoreleasepool {
          NSURL *url = [NSURL URLWithString:@"https://api.apimart.ai/v1/images/generations"];

          NSDictionary *payload = @{
              @"model": @"seedream-5-0-flash",
              @"prompt": @"Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen",
              @"size": @"16:9",
              @"resolution": @"2K"
          };

          NSError *error;
          NSData *jsonData = [NSJSONSerialization dataWithJSONObject:payload
                                                            options:0
                                                              error:&error];

          NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
          [request setHTTPMethod:@"POST"];
          [request setValue:@"Bearer <token>" forHTTPHeaderField:@"Authorization"];
          [request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
          [request setHTTPBody:jsonData];

          NSURLSessionDataTask *task = [[NSURLSession sharedSession]
              dataTaskWithRequest:request
              completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                  if (error) {
                      NSLog(@"Error: %@", error);
                      return;
                  }
                  NSString *result = [[NSString alloc] initWithData:data
                                                          encoding:NSUTF8StringEncoding];
                  NSLog(@"%@", result);
              }];

          [task resume];
          [[NSRunLoop mainRunLoop] run];
      }
      return 0;
  }
  ```

  ```ocaml OCaml theme={null}
  (* Requires cohttp and yojson libraries *)
  open Lwt
  open Cohttp
  open Cohttp_lwt_unix

  let url = "https://api.apimart.ai/v1/images/generations"

  let payload = {|{
    "model": "seedream-5-0-flash",
    "prompt": "Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen",
    "size": "16:9",
    "resolution": "2K"
  }|}

  let () =
    let headers = Header.init ()
      |> fun h -> Header.add h "Authorization" "Bearer <token>"
      |> fun h -> Header.add h "Content-Type" "application/json"
    in
    let body = Cohttp_lwt.Body.of_string payload in

    let response = Client.post ~headers ~body (Uri.of_string url) >>= fun (resp, body) ->
      body |> Cohttp_lwt.Body.to_string >|= fun body_str ->
      print_endline body_str
    in
    Lwt_main.run response
  ```

  ```dart Dart theme={null}
  import 'dart:convert';
  import 'package:http/http.dart' as http;

  void main() async {
    final url = Uri.parse('https://api.apimart.ai/v1/images/generations');

    final payload = {
      'model': 'seedream-5-0-flash',
      'prompt': 'Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen',
      'size': '16:9',
      'resolution': '2K'
    };

    final response = await http.post(
      url,
      headers: {
        'Authorization': 'Bearer <token>',
        'Content-Type': 'application/json',
      },
      body: jsonEncode(payload),
    );

    print(response.body);
  }
  ```

  ```r R theme={null}
  library(httr)
  library(jsonlite)

  url <- "https://api.apimart.ai/v1/images/generations"

  payload <- list(
    model = "seedream-5-0-flash",
    prompt = "Cyberpunk-Stadtansicht bei Nacht, Neonlichter spiegeln sich auf nassen Straßen",
    size = "16:9",
    resolution = "2K"
  )

  response <- POST(
    url,
    add_headers(
      Authorization = "Bearer <token>",
      `Content-Type` = "application/json"
    ),
    body = toJSON(payload, auto_unbox = TRUE),
    encode = "raw"
  )

  cat(content(response, "text"))
  ```
</RequestExample>

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

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "Invalid request parameters",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Invalid authentication credentials",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "Insufficient balance. Please top up your account",
      "type": "payment_required"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": 403,
      "message": "Access forbidden. You don't have permission to access this resource",
      "type": "permission_error"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "Rate limit exceeded. Please try again later",
      "type": "rate_limit_error"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": 500,
      "message": "Internal server error. Please try again later",
      "type": "server_error"
    }
  }
  ```

  ```json 502 theme={null}
  {
    "error": {
      "code": 502,
      "message": "Bad gateway. The server is temporarily unavailable",
      "type": "bad_gateway"
    }
  }
  ```
</ResponseExample>

## Autorisierung

<ParamField header="Authorization" type="string" required>
  Alle API-Endpunkte erfordern eine Bearer-Token-Authentifizierung

  API-Key abrufen:

  Besuchen Sie die [API-Key-Verwaltungsseite](https://apimart.ai/keys), um Ihren API-Key zu erhalten

  Fügen Sie ihn dem Request-Header hinzu:

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

<Info>
  **Einzelbildmodell**: `seedream-5-0-flash` erzeugt pro Anfrage nur 1 Bild (außer bei der Ebenenzerlegung). Die folgenden Parameter werden **abgelehnt** (HTTP 400, kein Task, keine Kosten):

  * `n > 1`
  * `sequential_image_generation` (Gruppengenerierung wird nicht unterstützt)
  * `stream` (Streaming wird nicht unterstützt)
  * `tools` (Websuche wird nicht unterstützt)
  * mehr als 10 Einträge in `image_urls`
</Info>

<CardGroup cols={2}>
  <Card title="Interaktive Bearbeitung" icon="crosshairs">
    Verwenden Sie `<point>`-/`<bbox>`-Koordinaten im Prompt oder laden Sie ein Bild mit handgezeichneten Markierungen hoch, um Bearbeitungsbereiche präzise festzulegen.

    * Punktkoordinaten: `<point>x y</point>` (geben einen einzelnen Punkt an; das Modell bestimmt den Wirkungsbereich)
    * Begrenzungsrahmen-Koordinaten: `<bbox>x1 y1 x2 y2</bbox>` (geben die Koordinaten oben links und unten rechts an, um die Größe des Bearbeitungsbereichs präzise zu steuern)
  </Card>

  <Card title="Ebenenzerlegung" icon="layer-group">
    Zerlegen Sie ein Bild in ein Basisbild und bis zu 16 transparente PNG-Ebenen samt Positions- und Stapelinformationen.
  </Card>
</CardGroup>

## Body

<ParamField body="model" type="string" default="seedream-5-0-flash" required>
  Name des Bildgenerierungsmodells

  * `seedream-5-0-flash` (empfohlen)
  * Ebenfalls akzeptiert: `seedream-5.0-pro`
</ParamField>

<ParamField body="nsfw_check" type="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)
</ParamField>

<ParamField body="prompt" type="string" required>
  Textbeschreibung für die Bildgenerierung

  Bei `layer_decomposition: true` optional; wird der Prompt weggelassen, erkennt und trennt das Modell die Hauptelemente des Bildes automatisch.

  Neben Chinesisch und Englisch unterstützt die native Texterzeugung Russisch, Arabisch, Filipino, Thailändisch, Türkisch, Koreanisch, Malaiisch, Spanisch, Portugiesisch, Indonesisch, Französisch, Deutsch, Vietnamesisch und Japanisch.

  > **Tipp:** Bleiben Sie bei maximal 600 englischen Wörtern; zu lange Beschreibungen können Detailverlust verursachen.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  Auflösungsstufe (Kleinschreibung wird akzeptiert). Dies ist eine API-Mart-Erweiterung und entspricht der direkten Angabe der Stufe in `size`.

  * `1K` (Standard)
  * `1.5K` (gleicher Preis wie 1K, bessere Qualität — bevorzugt 1.5K, sofern kein Grund dagegen)
  * `2K`

  Nicht unterstützte Stufen wie 3K / 4K liefern 400.

  Wenn sowohl `size` als Stufe als auch `resolution` angegeben werden, hat `size` Vorrang.

  <Warning>
    Wenn `size` ein **exakter Pixelwert** ist (z. B. `2048x1024`), wird dieses Feld **ignoriert** und die Abmessungen kommen nur aus `size`.
  </Warning>
</ParamField>

<ParamField body="size" type="string" default="auto">
  Ein Stufenschlüsselwort, Seitenverhältnis, `auto` oder **exakte Pixelmaße**.

  ### Schreibweise ①: Auflösungsstufe (empfohlen)

  Die Stufe kann direkt in `size` oder über das API-Mart-Erweiterungsfeld `resolution` angegeben werden:

  ```json theme={null}
  { "size": "2K" }
  ```

  ```json theme={null}
  { "resolution": "2K" }
  ```

  Beide Schreibweisen sind gleichwertig. Wenn nur eine Stufe angegeben wird, beschreiben Sie das gewünschte Layout im Prompt (z. B. "Poster im Hochformat" oder "Titelbild im Querformat") und lassen Sie das Modell das Seitenverhältnis wählen.

  ### Schreibweise ②: Stufe + Seitenverhältnis

  Zusammen mit `resolution`. Unterstützte Verhältnisse:

  * `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `2:1`, `1:2`, `21:9`
  * Auch `x`-Trenner im Stil `16x9`
  * `2x1` entspricht `2:1`, und `1x2` entspricht `1:2`. Das `x` muss kleingeschrieben werden; Leerzeichen sind nicht zulässig.
  * `auto` (Standard): nur Auflösungsstufe; finales Seitenverhältnis aus Prompt / Referenzen

  Verhältnisse außerhalb der Liste (z. B. `9:21`) liefern 400 — **kein stiller Fallback auf 1:1**.

  **Stufe × Verhältnis → Ausgabepixel:**

  | Auflösung | 1:1       | 4:3       | 3:4       | 16:9      | 9:16      | 3:2       | 2:3       | 2:1       | 1:2       | 21:9      |
  | --------- | --------- | --------- | --------- | --------- | --------- | --------- | --------- | --------- | --------- | --------- |
  | **1K**    | 1024×1024 | 1152×864  | 864×1152  | 1312×736  | 736×1312  | 1248×832  | 832×1248  | 1440×720  | 720×1440  | 1568×672  |
  | **1.5K**  | 1536×1536 | 1792×1344 | 1344×1792 | 2048×1152 | 1152×2048 | 1872×1248 | 1248×1872 | 2176×1088 | 1088×2176 | 2352×1008 |
  | **2K**    | 2048×2048 | 2304×1728 | 1728×2304 | 2560×1440 | 1440×2560 | 2496×1664 | 1664×2496 | 2880×1440 | 1440×2880 | 3024×1296 |

  ```json theme={null}
  { "resolution": "2K", "size": "2:1" }
  ```

  ### Schreibweise ③: exakte Pixel

  Wenn `size` `widthxheight` ist, werden Pixel unverändert verwendet und `resolution` greift nicht. Akzeptiert `2048X1024` / `2048×1024`.

  | Einschränkung                    | Bereich                                                    |
  | -------------------------------- | ---------------------------------------------------------- |
  | Gesamtpixel (Breite × Höhe)      | `[921600, 4624220]` (ca. `1280×720` \~ `2048×2048×1.1025`) |
  | Seitenverhältnis (Breite / Höhe) | `[1/16, 16]`                                               |

  <Warning>
    Grenzen gelten für das **Produkt** aus Breite und Höhe, nicht für jede Kante allein. Beispiel: `512×512` ist zu klein (400); `2048×1024` ist gültig.
  </Warning>
</ParamField>

<ParamField body="background" type="string" default="opaque">
  Ausgabe-Hintergrundmodus:

  * `opaque`: deckender Hintergrund (Standard)
  * `transparent`: transparenter Hintergrund

  `transparent` ist nur für Bild-zu-Bild-Anfragen mit genau einem Eingabebild verfügbar, das bereits einen Alphakanal besitzt; zusätzlich ist `output_format: "png"` erforderlich.
</ParamField>

<ParamField body="layer_decomposition" type="boolean" default="false">
  Legt fest, ob das Bild in Ebenen zerlegt wird. Bei Aktivierung gibt das Modell ein Basisbild und bis zu 16 PNG-Ebenen mit Alphakanal zurück.

  Es ist genau ein PNG- oder JPEG-Bild erforderlich. Es muss insgesamt `[262144, 36000000]` Pixel enthalten und darf höchstens 30 MB groß sein. `size` akzeptiert nur `1K`, `1.5K`, `2K` oder `auto` und verwendet standardmäßig `auto`. `output_format` steuert nur das Format des Basisbilds; zerlegte Ebenen sind immer PNG.
</ParamField>

<ParamField body="optimize_prompt_options" type="object" default={'{"mode":"standard"}'}>
  Modus der Prompt-Optimierung:

  * `standard`: Standardmodus mit besserer Qualität (Standard)

  Die flache Schreibweise `"optimize_prompt_options.mode": "standard"` wird ebenfalls akzeptiert.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Anzahl der zu erzeugenden Bilder. Es wird nur `1` unterstützt; verwenden Sie `seedream-5-0-lite` für die Gruppenerzeugung.
</ParamField>

<ParamField body="image_urls" type="array">
  Liste der Referenzbild-URLs für Einzel- / Mehrfach-Referenz-Image-to-Image, **bis zu 10**

  Zwei Formate:

  **1. Öffentliche URL**

  * `http://` oder `https://`
  * Beispiel: `https://example.com/image.jpg`

  **2. Base64 (Data URI)**

  * Format: `data:image/<format>;base64,<data>` — `<format>` muss **kleingeschrieben** sein
  * Beispiel: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABg...`

  **Limits pro Bild:**

  * Formate: jpeg / png / webp / bmp / tiff / gif / heic / heif
  * Seitenverhältnis (w/h): `[1/16, 16]`
  * Jede Kante > 14 px
  * Größe ≤ 30 MB
  * Gesamtpixel ≤ `6000×6000` (36,000,000)

  > **Abrechnung:** Erstes Referenzbild kostenlos; jedes weitere mit fester Aufpreisgebühr.
</ParamField>

<ParamField body="output_format" type="string" default="jpeg">
  Ausgabeformat des Bildes

  * `jpeg` (Standard)
  * `png`

  > **Kompatibilität:** `response_format` entspricht `output_format`; andere Werte werden als `jpeg` behandelt.
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  Ob unten rechts ein "AI generated"-Wasserzeichen gesetzt wird

  * `true`: Wasserzeichen hinzufügen
  * `false`: kein Wasserzeichen (Standard)
</ParamField>

## Anfragebeispiele

### Text-zu-Bild (Stufe + Verhältnis)

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Cyberpunk-Stadtnachtszene, Neonspiegelungen auf nassen Straßen",
  "resolution": "2K",
  "size": "2:1",
  "output_format": "png"
}
```

### Text-zu-Bild (exakte Pixel)

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Minimales E-Commerce-Hero-Bild, weißer Hintergrund, Produkt zentriert",
  "size": "1600x1600"
}
```

### Mehrere Referenzen

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Outfit in Bild 1 durch Outfit in Bild 2 ersetzen",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/dress.jpg"
  ],
  "resolution": "2K",
  "size": "auto"
}
```

### Empfohlen: 1.5K gleicher Preis, bessere Qualität

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Eine niedliche orangefarbene Katze auf der Fensterbank im Nachmittagslicht, filmisch",
  "resolution": "1.5K",
  "size": "16:9"
}
```

### Ebenenzerlegung

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "image_urls": ["https://example.com/poster.png"],
  "layer_decomposition": true,
  "size": "2K"
}
```

Sie können auch auf `0–1000` normalisierte `<bbox>`-Koordinaten verwenden, um die zu extrahierenden Elemente präzise anzugeben:

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Zerlege das Bild in präzise Ebenen. Der Text befindet sich bei <bbox>180 64 812 198</bbox>; der Papagei bei <bbox>347 305 642 997</bbox>.",
  "image_urls": ["https://example.com/poster.png"],
  "layer_decomposition": true
}
```

### Interaktive Bearbeitung

Beschreiben Sie handgezeichnete Markierungen im Bild in natürlicher Sprache:

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Bearbeite das Bild entsprechend der Skizze. Füge im markierten Bereich unten links einen Stapel Zeitschriften und im markierten Bereich rechts eine Tasse Kaffee hinzu. Entferne alle Skizzenlinien und behalte die Komposition bei.",
  "image_urls": ["https://example.com/sketch.png"],
  "size": "2K",
  "output_format": "png"
}
```

Oder geben Sie Positionen mit `<point>` / `<bbox>` präzise an:

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Platziere das Motiv aus Bild 1 bei <bbox>179 283 796 986</bbox> in Bild 2 an Position <bbox>118 331 933 871</bbox>.",
  "image_urls": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}
```

### Bearbeitung mit Alphakanal

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Verwandle den Papagei in einen Pfau und erhalte den transparenten Hintergrund",
  "image_urls": ["https://cdn.example.com/images/layer.png"],
  "background": "transparent",
  "output_format": "png",
  "size": "2K"
}
```

## Vollständiges Beispiel: Task senden und Bild abrufen

Das folgende Skript zeigt den vollständigen Ablauf: einen asynchronen Task senden, den Status abfragen, Fehlerzustände behandeln und die finale Bild-URL auslesen. Ersetzen Sie vor der Ausführung `YOUR_API_KEY`.

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

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.apimart.ai"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# 1. Generierungs-Task senden
create_response = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers=headers,
    json={
        "model": "seedream-5-0-flash",
        "prompt": "Eine Wasserstadt in Jiangnan im Tuschemalerei-Stil mit leichtem Morgennebel",
        "resolution": "1.5K",
        "size": "16:9",
        "output_format": "png",
    },
    timeout=30,
)
create_response.raise_for_status()
task_id = create_response.json()["data"][0]["task_id"]
print(f"Task gesendet: {task_id}")

# 2. Task-Status abfragen
while True:
    task_response = requests.get(
        f"{BASE_URL}/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    )
    task_response.raise_for_status()
    task = task_response.json()
    status = task["status"]
    print(f"Status: {status}; Fortschritt: {task.get('progress', 0)}%")

    if status == "success":
        image = task["result"]["images"][0]
        print("Bild-URL:", image["url"][0])
        print("Bildgröße:", image["sizes"][0])
        print("Bildformat:", image["output_formats"][0])
        break

    if status in {"failed", "cancelled"}:
        raise RuntimeError(task.get("error", f"Task-Status: {status}"))

    time.sleep(5)
```

Bei Erfolg gibt der Endpunkt zur Task-Abfrage Folgendes zurück:

```json theme={null}
{
  "id": "task_01JFXYZ123456789ABCDEF",
  "status": "success",
  "progress": 100,
  "cost": 0.045,
  "result": {
    "images": [
      {
        "url": ["https://cdn.example.com/images/image_task_xxx_0.png"],
        "sizes": ["2048x1152"],
        "output_formats": ["png"],
        "expires_at": 1784696685
      }
    ]
  }
}
```

<Note>
  Zurückgegebene Bilder werden in einen von der Plattform verwalteten Speicher gespiegelt. Laden Sie sie dennoch zeitnah herunter und speichern Sie sie dauerhaft in Ihrem eigenen System; behandeln Sie die Ergebnis-URL nicht als permanenten Speicher.
</Note>

## Vollständige cURL-Szenarien

### Komposition aus mehreren Bildern (bis zu 10 Referenzen)

```bash theme={null}
curl -X POST "https://api.apimart.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-flash",
    "prompt": "Setze die Person aus Bild 1 in die Szene aus Bild 2 und vereinheitliche die Beleuchtung auf Abenddämmerung",
    "image_urls": [
      "https://example.com/person.jpg",
      "https://example.com/scene.jpg"
    ],
    "resolution": "1.5K",
    "size": "16:9",
    "output_format": "png"
  }'
```

### Exakte Pixel, Prompt-Optimierung und Wasserzeichen

```bash theme={null}
curl -X POST "https://api.apimart.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-flash",
    "prompt": "Eine Cyberpunk-Stadtsilhouette mit Neonlichtern, die sich auf nassen Straßen spiegeln",
    "size": "2048x1024",
    "optimize_prompt_options": { "mode": "standard" },
    "watermark": true
  }'
```

### Transparente Ebene zerlegen und separat bearbeiten

Zerlegen Sie zuerst das Ausgangsbild:

```bash theme={null}
curl -X POST "https://api.apimart.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-flash",
    "image_urls": ["https://example.com/poster.png"],
    "layer_decomposition": true,
    "size": "2K"
  }'
```

Rufen Sie danach die URL einer transparenten Ebene ab und bearbeiten Sie sie separat:

```bash theme={null}
curl -X POST "https://api.apimart.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-flash",
    "prompt": "Verwandle den Papagei im Bild in einen Pfau",
    "image_urls": ["https://cdn.example.com/images/image_task_xxx_4.png"],
    "background": "transparent",
    "output_format": "png",
    "size": "2K"
  }'
```

## Antwort der Ebenenzerlegung und Rekonstruktion

Die Arrays `url`, `sizes`, `output_formats` und `layers` entsprechen einander nach Index; Index `0` ist immer das Basisbild:

```json theme={null}
{
  "result": {
    "images": [{
      "url": [
        "https://cdn.example.com/images/image_task_xxx_0.jpeg",
        "https://cdn.example.com/images/image_task_xxx_1.png",
        "https://cdn.example.com/images/image_task_xxx_2.png"
      ],
      "sizes": ["2048x2048", "1273x265", "492x98"],
      "output_formats": ["jpeg", "png", "png"],
      "layer_decomposition": true,
      "layers": [
        { "z_index": 0, "size": "2048x2048", "output_format": "jpeg" },
        {
          "z_index": 1,
          "size": "1273x265",
          "output_format": "png",
          "name": "Titeltext",
          "description": "Großer gelber Titeltext in Serifenschrift",
          "bounding_box": {
            "absolute": [383, 120, 1655, 384],
            "normalized": [187, 59, 808, 188]
          }
        },
        {
          "z_index": 2,
          "size": "492x98",
          "output_format": "png",
          "name": "Slogan oben links",
          "description": "Zweizeiliger englischer Slogan in Weiß",
          "bounding_box": {
            "absolute": [140, 451, 631, 548],
            "normalized": [68, 220, 308, 268]
          }
        }
      ]
    }]
  }
}
```

Setzen Sie die Ebenen in aufsteigender `z_index`-Reihenfolge zusammen. Für die Rekonstruktion auf dem Ausgabe-Basisbild mit absoluten Koordinaten gilt:

```text theme={null}
x = left
y = top
w = right - left
h = bottom - top
```

Verwenden Sie für die Rekonstruktion auf einer beliebigen `W × H`-Zeichenfläche normalisierte Koordinaten:

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

<Warning>
  Die Ebenenzerlegung wird pro Bild abgerechnet. Beim Senden des Tasks werden bis zu 17 Bilder vorautorisiert. Nach Abschluss wird jede Ausgabe anhand ihrer tatsächlichen Pixelzahl eingestuft und einzeln abgerechnet; eine überschüssige Vorautorisierung wird automatisch erstattet. Ihr Guthaben muss die Vorautorisierung für 17 Bilder decken; `size: "auto"` wird in der 2K-Stufe vorautorisiert.
</Warning>

## Abrechnungshinweise

```
Gesamt = Ausgabe-Stückpreis + Referenz-Zuschlag × max(0, Referenzanzahl − 1)
```

Die Ausgabe wird nach **tatsächlichen Gesamtpixeln** gestuft (ca. 2.61M = 2,601,124):

| Bedingung                                                                                                          | Stückpreis         |
| ------------------------------------------------------------------------------------------------------------------ | ------------------ |
| Gesamtpixel ≤ 2.61M (1.5K oder niedriger: `resolution` `1K` / `1.5K` / weggelassen, oder exakte Pixel ≤ 2,601,124) | **\$0.045** / Bild |
| Gesamtpixel > 2.61M (höher als 1.5K: `resolution: "2K"`, oder exakte Pixel > 2,601,124)                            | **\$0.09** / Bild  |

* **1.5K kostet dasselbe wie 1K** (\$0.045).
* Bei exakten Pixeln in `size` zählt die **tatsächliche Ausgabefläche**; `resolution` hat keinen Einfluss (z. B. `size: "2048x2048"` → \$0.09).
* Das erste Referenzbild ist gratis; ab dem zweiten gilt ein Zuschlag.
* Fehlgeschlagene Tasks werden voll erstattet.

### Vorautorisierung und Abrechnung der Ebenenzerlegung

Da Anzahl und Abmessungen der Ebenen beim Senden des Tasks noch unbekannt sind, erfolgt die Vorautorisierung nach konservativen Regeln anhand der Anfrage:

* Exakte Pixel: Einstufung nach der angeforderten Pixelfläche.
* `1K` / `1.5K`: Vorautorisierung in der 1K-Stufe.
* `2K`: Vorautorisierung in der 2K-Stufe.
* `auto`: kann bis zu 2K ausgeben und wird daher in der 2K-Stufe vorautorisiert.

Nach Abschluss werden Basisbild und jede tatsächliche Ebene anhand ihrer realen Pixelfläche **einzeln eingestuft und summiert**. Eine überschüssige Vorautorisierung wird automatisch erstattet. Ebenen sind meist deutlich kleiner als das Basisbild, sodass selbst ein in der 2K-Stufe vorautorisierter Task letztlich vollständig in der 1K-Stufe abgerechnet werden kann.

<Info>
  Beispiel: Eine `1080×1080`-Eingabe wird in 10 Bilder zerlegt. Der Task wird als `17 Bilder × 2K-Stufe` vorautorisiert. Wenn alle 10 finalen Bilder höchstens 2,61 Millionen Pixel enthalten, erfolgt die Abrechnung als `10 Bilder × 1K-Stufe`; das verbleibende Guthaben wird automatisch erstattet.
</Info>

## Häufige Fehler

| Fall                                                              | Hinweise                                                                                                 |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Nicht unterstützte `resolution`-Stufe                             | z. B. 3K / 4K → 400                                                                                      |
| Nicht unterstützter `size`-Wert                                   | Weder `1K` / `1.5K` / `2K` / `auto` noch ein unterstütztes Seitenverhältnis oder gültige Pixelmaße → 400 |
| Exakte-Pixel-Gesamt außerhalb des Bereichs                        | Muss in `[921600, 4624220]` liegen                                                                       |
| Exakte-Pixel-Verhältnis außerhalb des Bereichs                    | Muss in `[1/16, 16]` liegen                                                                              |
| `n > 1` / Parameter für Bildgruppen                               | Vom Einzelbildmodell abgelehnt                                                                           |
| Mehr als 10 Referenzbilder                                        | Rejected                                                                                                 |
| Ebenenzerlegung ohne Bild oder mit mehreren Bildern               | Genau ein Bild ist erforderlich                                                                          |
| Ebenenzerlegung mit Seitenverhältnis oder exakten Pixeln          | `size` unterstützt nur `1K` / `1.5K` / `2K` / `auto`                                                     |
| Transparenter Hintergrund bei Text-zu-Bild oder mehreren Eingaben | Genau ein Eingabebild mit Alphakanal ist erforderlich                                                    |
| Transparenter Hintergrund mit JPEG                                | Setzen Sie `output_format: "png"`                                                                        |
| `stream` / `tools`                                                | Von diesem Modell nicht unterstützt; gibt 400 zurück                                                     |
| Ungültiger Prompt-Optimierungsmodus                               | Nur `standard` wird unterstützt                                                                          |

<Note>
  ⏱️ **Langsamere Generierung**: ca. 90 s für 1K, ca. 160 s für 2K (Qualität hat Vorrang). Fragen Sie den [Task-Status](/de/api-reference/tasks/status) alle 5–10 Sekunden ab und setzen Sie das Client-Timeout auf **5 Minuten**. Speichern Sie erzeugte Ergebnisse zeitnah.
</Note>

## Response

<ResponseField name="code" type="integer">
  Antwort-Statuscode
</ResponseField>

<ResponseField name="data" type="array">
  Antwortdaten-Array

  <Expandable title="Eigenschaften">
    <ResponseField name="status" type="string">
      Aufgabenstatus

      * `submitted` – Eingereicht
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Eindeutige Aufgaben-ID
    </ResponseField>
  </Expandable>
</ResponseField>