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

# Generación de imágenes Seedream-5.0-Flash

>  - Modo de procesamiento asíncrono, devuelve un ID de tarea para consultas posteriores
- Admite text-to-image, generación con una imagen de referencia y con múltiples referencias (hasta 10)
- Admite niveles de resolución 1K / 1.5K / 2K, o píxeles exactos mediante `size`
- Modelo de una sola imagen: una imagen por solicitud; salida PNG / JPEG
- Los enlaces de las imágenes generadas son válidos durante 72 horas; guárdelos cuanto antes 

<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": "Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas",
      "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": "Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas",
      "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: "Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas",
    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":     "Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas",
          "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": "Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas",
            "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" => "Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas",
      "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: "Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas",
    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": "Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas",
      "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"": ""Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas"",
              ""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\":\"Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas\","
              "\"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": @"Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas",
              @"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": "Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas",
    "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': 'Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas',
      '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 = "Paisaje urbano nocturno de estilo ciberpunk, luces de neón reflejándose en las calles mojadas",
    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>

## Autorización

<ParamField header="Authorization" type="string" required>
  Todos los endpoints de la API requieren autenticación mediante Bearer Token

  Obtenga su clave de API:

  Visite la [página de gestión de claves de API](https://apimart.ai/keys) para obtener su clave de API

  Añádala a la cabecera de la solicitud:

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

<Info>
  **Modelo de imagen única**: `seedream-5-0-flash` genera solo 1 imagen por solicitud (excepto en la descomposición por capas). Los siguientes parámetros se **rechazan** (HTTP 400, sin tarea ni cobro):

  * `n > 1`
  * `sequential_image_generation` (no se admite la generación en grupo)
  * `stream` (no se admite streaming)
  * `tools` (no se admite la búsqueda web)
  * más de 10 elementos en `image_urls`
</Info>

<CardGroup cols={2}>
  <Card title="Edición interactiva" icon="crosshairs">
    Use coordenadas `<point>` / `<bbox>` en el prompt o cargue una imagen con anotaciones dibujadas a mano para ubicar las ediciones con precisión.

    * Coordenadas de punto: `<point>x y</point>` (especifican un solo punto; el modelo determina el área afectada)
    * Coordenadas de cuadro delimitador: `<bbox>x1 y1 x2 y2</bbox>` (especifican las coordenadas superior izquierda e inferior derecha para controlar con precisión el tamaño del área de edición)
  </Card>

  <Card title="Descomposición por capas" icon="layer-group">
    Separe una imagen en una imagen base y hasta 16 capas PNG transparentes, con información de posición y orden de apilamiento.
  </Card>
</CardGroup>

## Cuerpo de la solicitud

<ParamField body="model" type="string" default="seedream-5-0-flash" required>
  Nombre del modelo de generación de imágenes

  * `seedream-5-0-flash` (recomendado)
  * También se acepta: `seedream-5.0-pro`
</ParamField>

<ParamField body="nsfw_check" type="boolean" default="false">
  Indica si se debe moderar el contenido antes de enviar la tarea de imagen.

  * `true`: revisar los prompts y las imágenes de entrada con `omni-moderation-latest`
  * `false` u omitido: no enviar una solicitud de moderación, sin coste ni latencia de moderación adicionales (predeterminado)
</ParamField>

<ParamField body="prompt" type="string" required>
  Descripción textual para la generación de la imagen

  Es opcional cuando `layer_decomposition: true`; si se omite, el modelo identifica y separa automáticamente los elementos principales de la imagen.

  Además de chino e inglés, la generación nativa de texto admite ruso, árabe, filipino, tailandés, turco, coreano, malayo, español, portugués, indonesio, francés, alemán, vietnamita y japonés.

  > **Consejo:** manténgala en menos de 600 palabras en inglés; una descripción demasiado larga puede perder detalle.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  Nivel de resolución (se aceptan minúsculas). Es una extensión de API Mart equivalente a indicar el nivel directamente en `size`.

  * `1K` (predeterminado)
  * `1.5K` (mismo precio que 1K, mejor calidad — prefiera 1.5K salvo motivo en contra)
  * `2K`

  Niveles no admitidos como 3K / 4K devuelven 400.

  Si se proporcionan `size` como nivel y `resolution`, prevalece `size`.

  <Warning>
    Cuando `size` es un **valor de píxel exacto** (p. ej. `2048x1024`), este campo se **ignora** y las dimensiones salen solo de `size`.
  </Warning>
</ParamField>

<ParamField body="size" type="string" default="auto">
  Una palabra clave de nivel, una relación de aspecto, `auto` o **dimensiones exactas en píxeles**.

  ### Forma ①: nivel de resolución (recomendado)

  El nivel puede indicarse directamente en `size` o mediante el campo de extensión de API Mart `resolution`:

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

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

  Ambas formas son equivalentes. Si solo se especifica un nivel, describa el diseño deseado en el prompt (por ejemplo, "cartel vertical" o "portada horizontal") y deje que el modelo elija la relación de aspecto.

  ### Forma ②: nivel + relación de aspecto

  Se usa con `resolution`. Proporciones admitidas:

  * `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `2:1`, `1:2`, `21:9`
  * También acepta separador `x` estilo `16x9`
  * `2x1` equivale a `2:1` y `1x2` equivale a `1:2`. La `x` debe escribirse en minúscula y no se admiten espacios.
  * `auto` (predeterminado): solo el nivel de resolución; la proporción final se elige según el prompt / las referencias

  Proporciones fuera de la lista (p. ej. `9:21`) devuelven 400 — **sin fallback silencioso a 1:1**.

  **Nivel × proporción → píxeles de salida:**

  | Resolución | 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" }
  ```

  ### Forma ③: píxeles exactos

  Cuando `size` es `widthxheight`, los píxeles se usan tal cual y `resolution` no aplica. Acepta `2048X1024` / `2048×1024`.

  | Restricción                    | Rango                                                         |
  | ------------------------------ | ------------------------------------------------------------- |
  | Píxeles totales (ancho × alto) | `[921600, 4624220]` (aprox. `1280×720` \~ `2048×2048×1.1025`) |
  | Proporción (ancho / alto)      | `[1/16, 16]`                                                  |

  <Warning>
    Los límites se aplican al **producto** de ancho y alto, no a cada lado por separado. Ejemplo: `512×512` es demasiado pequeño (400); `2048×1024` es válido.
  </Warning>
</ParamField>

<ParamField body="background" type="string" default="opaque">
  Modo de fondo de salida:

  * `opaque`: fondo opaco (predeterminado)
  * `transparent`: fondo transparente

  `transparent` solo está disponible para solicitudes de imagen a imagen con exactamente una imagen de entrada que ya tenga canal alfa; también se requiere `output_format: "png"`.
</ParamField>

<ParamField body="layer_decomposition" type="boolean" default="false">
  Indica si se descompone la imagen en capas. Al activarlo, el modelo devuelve una imagen base y hasta 16 capas PNG con canal alfa.

  Se requiere exactamente una imagen PNG o JPEG. Debe contener entre `[262144, 36000000]` píxeles totales y no superar 30 MB. `size` solo acepta `1K`, `1.5K`, `2K` o `auto`, y su valor predeterminado es `auto`. `output_format` solo controla el formato de la imagen base; las capas descompuestas siempre son PNG.
</ParamField>

<ParamField body="optimize_prompt_options" type="object" default={'{"mode":"standard"}'}>
  Modo de optimización del prompt:

  * `standard`: modo estándar con mejor calidad (predeterminado)

  También se acepta la forma plana `"optimize_prompt_options.mode": "standard"`.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Número de imágenes que se generarán. Solo se admite `1`; use `seedream-5-0-lite` para generar grupos de imágenes.
</ParamField>

<ParamField body="image_urls" type="array">
  Lista de URL de imágenes de referencia para image-to-image con una / varias referencias, **hasta 10**

  Dos formatos:

  **1. URL pública**

  * `http://` o `https://`
  * Ejemplo: `https://example.com/image.jpg`

  **2. Base64 (Data URI)**

  * Formato: `data:image/<format>;base64,<data>` — `<format>` debe ir en **minúsculas**
  * Ejemplo: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABg...`

  **Límites por imagen:**

  * Formatos: jpeg / png / webp / bmp / tiff / gif / heic / heif
  * Proporción (a/al): `[1/16, 16]`
  * Cada lado > 14 px
  * Tamaño ≤ 30 MB
  * Píxeles totales ≤ `6000×6000` (36.000.000)

  > **Facturación:** la primera imagen de referencia es gratuita; cada imagen adicional tiene un recargo fijo.
</ParamField>

<ParamField body="output_format" type="string" default="jpeg">
  Formato de salida de la imagen

  * `jpeg` (predeterminado)
  * `png`

  > **Compatibilidad:** `response_format` equivale a `output_format`; otros valores se tratan como `jpeg`.
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  Si se añade una marca de agua "AI generated" en la esquina inferior derecha

  * `true`: añadir marca de agua
  * `false`: sin marca de agua (predeterminado)
</ParamField>

## Ejemplos de solicitud

### Text-to-image (nivel + proporción)

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Escena nocturna de ciudad cyberpunk, reflejos de neón en calles mojadas",
  "resolution": "2K",
  "size": "2:1",
  "output_format": "png"
}
```

### Text-to-image (píxeles exactos)

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Imagen hero de e-commerce minimalista, fondo blanco, producto centrado",
  "size": "1600x1600"
}
```

### Multi-referencia

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Reemplazar el atuendo de la imagen 1 por el de la imagen 2",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/dress.jpg"
  ],
  "resolution": "2K",
  "size": "auto"
}
```

### Recomendado: 1.5K mismo precio, mejor calidad

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Un gato naranja lindo en el alféizar al sol de la tarde, cinematográfico",
  "resolution": "1.5K",
  "size": "16:9"
}
```

### Descomposición por capas

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

También puede usar coordenadas `<bbox>` normalizadas a `0–1000` para identificar con precisión los elementos que desea extraer:

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Separa la imagen en capas precisas. El texto está en <bbox>180 64 812 198</bbox>; el loro está en <bbox>347 305 642 997</bbox>.",
  "image_urls": ["https://example.com/poster.png"],
  "layer_decomposition": true
}
```

### Edición interactiva

Describa con lenguaje natural las anotaciones dibujadas a mano en la imagen:

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Edita la imagen según el boceto. Añade una pila de revistas en el área marcada abajo a la izquierda y una taza de café en el área marcada a la derecha. Elimina todas las líneas del boceto y conserva la composición.",
  "image_urls": ["https://example.com/sketch.png"],
  "size": "2K",
  "output_format": "png"
}
```

O indique ubicaciones precisas con `<point>` / `<bbox>`:

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Coloca el sujeto de la imagen 1 en <bbox>179 283 796 986</bbox> dentro de la imagen 2, en <bbox>118 331 933 871</bbox>.",
  "image_urls": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}
```

### Edición del canal alfa

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Cambia el loro por un pavo real y conserva el fondo transparente",
  "image_urls": ["https://cdn.example.com/images/layer.png"],
  "background": "transparent",
  "output_format": "png",
  "size": "2K"
}
```

## Ejemplo completo: enviar una tarea y obtener la imagen

El siguiente script muestra el flujo completo: enviar una tarea asíncrona, consultar su estado, gestionar los estados de error y leer la URL final de la imagen. Sustituya `YOUR_API_KEY` antes de ejecutarlo.

```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. Enviar la tarea de generación
create_response = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers=headers,
    json={
        "model": "seedream-5-0-flash",
        "prompt": "Un pueblo acuático de Jiangnan con estilo de tinta y una ligera niebla matinal",
        "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"Tarea enviada: {task_id}")

# 2. Consultar el estado de la tarea
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"Estado: {status}; progreso: {task.get('progress', 0)}%")

    if status == "success":
        image = task["result"]["images"][0]
        print("URL de la imagen:", image["url"][0])
        print("Tamaño de la imagen:", image["sizes"][0])
        print("Formato de la imagen:", image["output_formats"][0])
        break

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

    time.sleep(5)
```

Cuando se completa correctamente, el endpoint de consulta de tareas devuelve:

```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>
  Las imágenes devueltas se replican en almacenamiento administrado por la plataforma. Aun así, descárguelas y guárdelas cuanto antes en su propio sistema; no trate la URL del resultado como almacenamiento permanente.
</Note>

## Escenarios completos con cURL

### Composición de varias imágenes (hasta 10 referencias)

```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": "Coloca a la persona de la imagen 1 en la escena de la imagen 2 y unifica la iluminación al atardecer",
    "image_urls": [
      "https://example.com/person.jpg",
      "https://example.com/scene.jpg"
    ],
    "resolution": "1.5K",
    "size": "16:9",
    "output_format": "png"
  }'
```

### Píxeles exactos, optimización del prompt y marca de agua

```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": "Un horizonte urbano ciberpunk con luces de neón reflejadas en calles mojadas",
    "size": "2048x1024",
    "optimize_prompt_options": { "mode": "standard" },
    "watermark": true
  }'
```

### Descomponer y editar una capa transparente por separado

Primero, descomponga la imagen de origen:

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

Después, obtenga la URL de una capa transparente y edítela por separado:

```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": "Cambia el loro de la imagen por un pavo real",
    "image_urls": ["https://cdn.example.com/images/image_task_xxx_4.png"],
    "background": "transparent",
    "output_format": "png",
    "size": "2K"
  }'
```

## Respuesta y reconstrucción de la descomposición por capas

Los arrays `url`, `sizes`, `output_formats` y `layers` se corresponden por índice; el índice `0` siempre es la imagen base:

```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": "Texto del título",
          "description": "Texto de título amarillo grande con tipografía serif",
          "bounding_box": {
            "absolute": [383, 120, 1655, 384],
            "normalized": [187, 59, 808, 188]
          }
        },
        {
          "z_index": 2,
          "size": "492x98",
          "output_format": "png",
          "name": "Eslogan superior izquierdo",
          "description": "Eslogan en inglés de dos líneas en blanco",
          "bounding_box": {
            "absolute": [140, 451, 631, 548],
            "normalized": [68, 220, 308, 268]
          }
        }
      ]
    }]
  }
}
```

Componga las capas en orden ascendente de `z_index`. Para reconstruirlas sobre la imagen base de salida con coordenadas absolutas:

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

Para reconstruirlas sobre cualquier lienzo de `W × H`, use coordenadas normalizadas:

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

<Warning>
  La descomposición por capas se factura por imagen. Al enviar la tarea se preautorizan hasta 17 imágenes. Al finalizar, cada salida se clasifica según su cantidad real de píxeles y se liquida por separado; cualquier exceso de preautorización se reembolsa automáticamente. El saldo debe cubrir la preautorización de 17 imágenes y `size: "auto"` se preautoriza en el nivel 2K.
</Warning>

## Notas de facturación

```
Total = precio unitario de salida + recargo por referencias × max(0, n.º_refs − 1)
```

La salida se tarifica por el **total real de píxeles** (\~2.61M = 2,601,124):

| Condición                                                                                                      | Precio unitario      |
| -------------------------------------------------------------------------------------------------------------- | -------------------- |
| Píxeles totales ≤ 2.61M (1.5K o inferior: `resolution` `1K` / `1.5K` / omitido, o píxeles exactos ≤ 2,601,124) | **\$0.045** / imagen |
| Píxeles totales > 2.61M (superior a 1.5K: `resolution: "2K"`, o píxeles exactos > 2,601,124)                   | **\$0.09** / imagen  |

* **1.5K cuesta lo mismo que 1K** (\$0.045).
* Con píxeles exactos en `size`, la facturación usa el **área de salida real**; `resolution` no influye (p. ej. `size: "2048x2048"` → \$0.09).
* La 1.ª imagen de referencia es gratis; cada una adicional tiene recargo.
* Las tareas fallidas se reembolsan por completo.

### Preautorización y liquidación de la descomposición por capas

Como al enviar la tarea no se conocen el número ni las dimensiones finales de las capas, la preautorización aplica reglas conservadoras basadas en la solicitud:

* Píxeles exactos: nivel según el área de píxeles solicitada.
* `1K` / `1.5K`: preautorizado en el nivel 1K.
* `2K`: preautorizado en el nivel 2K.
* `auto`: puede generar hasta 2K, por lo que se preautoriza en el nivel 2K.

Al finalizar, la imagen base y cada capa real se **clasifican y suman individualmente** según su área real de píxeles. El exceso de preautorización se reembolsa automáticamente. Las capas suelen ser mucho menores que la imagen base, por lo que incluso una tarea preautorizada en 2K puede liquidarse por completo en el nivel 1K.

<Info>
  Ejemplo: una entrada de `1080×1080` se descompone en 10 imágenes. La tarea se preautoriza como `17 imágenes × nivel 2K`. Si las 10 imágenes finales no superan 2,61 millones de píxeles, se liquida como `10 imágenes × nivel 1K` y el crédito restante se reembolsa automáticamente.
</Info>

## Errores comunes

| Caso                                                     | Notas                                                                                                         |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Nivel `resolution` no admitido                           | p. ej. 3K / 4K → 400                                                                                          |
| Valor de `size` no admitido                              | No es `1K` / `1.5K` / `2K` / `auto`, una relación de aspecto admitida ni dimensiones de píxeles válidas → 400 |
| Total de píxeles exactos fuera de rango                  | Debe estar en `[921600, 4624220]`                                                                             |
| Proporción de píxeles exactos fuera de rango             | Debe estar en `[1/16, 16]`                                                                                    |
| `n > 1` / parámetros de imágenes agrupadas               | Rechazado por el modelo de imagen única                                                                       |
| Más de 10 imágenes de referencia                         | Rejected                                                                                                      |
| Descomposición sin imagen o con varias imágenes          | Se requiere exactamente una imagen                                                                            |
| Descomposición con relación o píxeles exactos            | `size` solo admite `1K` / `1.5K` / `2K` / `auto`                                                              |
| Fondo transparente para texto a imagen o varias entradas | Se requiere exactamente una imagen de entrada con canal alfa                                                  |
| Fondo transparente con JPEG                              | Establezca `output_format: "png"`                                                                             |
| `stream` / `tools`                                       | No admitido por este modelo; devuelve 400                                                                     |
| Modo de optimización del prompt no válido                | Solo se admite `standard`                                                                                     |

<Note>
  ⏱️ **Generación más lenta**: \~90 s para 1K y \~160 s para 2K (prioridad a la calidad). Consulte [Obtener estado de la tarea](/es/api-reference/tasks/status) cada 5–10 segundos y configure el tiempo de espera del cliente en **5 minutos**. Guarde los resultados generados cuanto antes.
</Note>

## Respuesta

<ResponseField name="code" type="integer">
  Código de estado de la respuesta
</ResponseField>

<ResponseField name="data" type="array">
  Array de datos de la respuesta

  <Expandable title="Propiedades">
    <ResponseField name="status" type="string">
      Estado de la tarea

      * `submitted` - Enviada
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Identificador único de la tarea
    </ResponseField>
  </Expandable>
</ResponseField>