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

# Geração de Imagens Seedream-5.0-Flash

>  - Modo de processamento assíncrono, retorna um ID de tarefa para consultas posteriores
- Suporta text-to-image, image-to-image com uma referência e com múltiplas imagens de referência (até 10)
- Suporta níveis de resolução 1K / 1.5K / 2K, ou pixels exatos via `size`
- Modelo de imagem única: uma imagem por solicitação; saída PNG / JPEG
- Os links das imagens geradas são válidos por 72 horas, salve-os o quanto 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": "Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas",
      "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": "Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas",
      "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: "Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas",
    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":     "Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas",
          "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": "Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas",
            "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" => "Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas",
      "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: "Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas",
    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": "Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas",
      "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"": ""Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas"",
              ""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\":\"Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas\","
              "\"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": @"Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas",
              @"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": "Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas",
    "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': 'Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas',
      '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 = "Paisagem urbana noturna em estilo cyberpunk, luzes de neon refletindo nas ruas molhadas",
    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>

## Autorização

<ParamField header="Authorization" type="string" required>
  Todos os endpoints da API exigem autenticação por Bearer Token

  Obtenha sua chave de API:

  Acesse a [página de gerenciamento de chaves de API](https://apimart.ai/keys) para obter sua chave de API

  Adicione-a ao cabeçalho da requisição:

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

<Info>
  **Modelo de imagem única**: `seedream-5-0-flash` gera apenas 1 imagem por solicitação (exceto na decomposição em camadas). Os seguintes parâmetros são **rejeitados** (HTTP 400, sem tarefa e sem cobrança):

  * `n > 1`
  * `sequential_image_generation` (a geração em grupo não é compatível)
  * `stream` (streaming não é compatível)
  * `tools` (pesquisa na web não é compatível)
  * mais de 10 itens em `image_urls`
</Info>

<CardGroup cols={2}>
  <Card title="Edição interativa" icon="crosshairs">
    Use coordenadas `<point>` / `<bbox>` no prompt ou envie uma imagem com anotações desenhadas à mão para direcionar as edições com precisão.

    * Coordenadas de ponto: `<point>x y</point>` (especificam um único ponto; o modelo determina a área afetada)
    * Coordenadas da caixa delimitadora: `<bbox>x1 y1 x2 y2</bbox>` (especificam as coordenadas superior esquerda e inferior direita para controlar com precisão o tamanho da área de edição)
  </Card>

  <Card title="Decomposição em camadas" icon="layer-group">
    Divida uma imagem em uma imagem base e até 16 camadas PNG transparentes, com informações de posição e empilhamento.
  </Card>
</CardGroup>

## Corpo da requisição

<ParamField body="model" type="string" default="seedream-5-0-flash" required>
  Nome do modelo de geração de imagens

  * `seedream-5-0-flash` (recomendado)
  * Também aceito: `seedream-5.0-pro`
</ParamField>

<ParamField body="nsfw_check" type="boolean" default="false">
  Define se o conteúdo deve ser moderado antes do envio da tarefa de imagem.

  * `true`: verificar prompts e imagens de entrada com `omni-moderation-latest`
  * `false` ou omitido: não enviar solicitação de moderação, sem custo nem latência adicionais de moderação (padrão)
</ParamField>

<ParamField body="prompt" type="string" required>
  Descrição textual para a geração da imagem

  Opcional quando `layer_decomposition: true`; se omitido, o modelo identifica e separa automaticamente os principais elementos da imagem.

  Além de chinês e inglês, a geração nativa de texto é compatível com russo, árabe, filipino, tailandês, turco, coreano, malaio, espanhol, português, indonésio, francês, alemão, vietnamita e japonês.

  > **Dica:** mantenha até 600 palavras em inglês; descrições longas demais podem perder detalhes.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  Nível de resolução (minúsculas aceitas). Esta é uma extensão da API Mart equivalente a informar o nível diretamente em `size`.

  * `1K` (padrão)
  * `1.5K` (mesmo preço que 1K, melhor qualidade — prefira 1.5K salvo motivo contrário)
  * `2K`

  Níveis não suportados como 3K / 4K retornam 400.

  Se `size` no formato de nível e `resolution` forem fornecidos juntos, `size` terá precedência.

  <Warning>
    Quando `size` é um **valor de pixel exato** (ex.: `2048x1024`), este campo é **ignorado** e as dimensões vêm apenas de `size`.
  </Warning>
</ParamField>

<ParamField body="size" type="string" default="auto">
  Uma palavra-chave de nível, proporção, `auto` ou **dimensões exatas em pixels**.

  ### Formato ①: nível de resolução (recomendado)

  O nível pode ser informado diretamente em `size` ou pelo campo de extensão da API Mart `resolution`:

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

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

  As duas formas são equivalentes. Quando apenas um nível for informado, descreva o layout desejado no prompt (por exemplo, "pôster vertical" ou "capa horizontal") e deixe o modelo escolher a proporção.

  ### Formato ②: nível + proporção

  Usado com `resolution`. Proporções suportadas:

  * `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `2:1`, `1:2`, `21:9`
  * Também aceita separador `x` no estilo `16x9`
  * `2x1` equivale a `2:1` e `1x2` equivale a `1:2`. O `x` deve ser minúsculo e espaços não são aceitos.
  * `auto` (padrão): só o nível de resolução; a proporção final vem do prompt / referências

  Proporções fora da lista (ex.: `9:21`) retornam 400 — **sem fallback silencioso para 1:1**.

  **Nível × proporção → pixels de saída:**

  | Resolução | 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" }
  ```

  ### Formato ③: pixels exatos

  Quando `size` é `widthxheight`, os pixels são usados como estão e `resolution` não se aplica. Aceita `2048X1024` / `2048×1024`.

  | Restrição                          | Intervalo                                                       |
  | ---------------------------------- | --------------------------------------------------------------- |
  | Total de pixels (largura × altura) | `[921600, 4624220]` (cerca de `1280×720` \~ `2048×2048×1.1025`) |
  | Proporção (largura / altura)       | `[1/16, 16]`                                                    |

  <Warning>
    Os limites se aplicam ao **produto** largura × altura, não a cada lado isolado. Exemplo: `512×512` é pequeno demais (400); `2048×1024` é válido.
  </Warning>
</ParamField>

<ParamField body="background" type="string" default="opaque">
  Modo do fundo de saída:

  * `opaque`: fundo opaco (padrão)
  * `transparent`: fundo transparente

  `transparent` está disponível apenas para solicitações de imagem para imagem com exatamente uma imagem de entrada que já possua canal alfa; `output_format: "png"` também é obrigatório.
</ParamField>

<ParamField body="layer_decomposition" type="boolean" default="false">
  Define se a imagem será decomposta em camadas. Quando ativado, o modelo retorna uma imagem base e até 16 camadas PNG com canal alfa.

  É necessária exatamente uma imagem PNG ou JPEG. Ela deve conter entre `[262144, 36000000]` pixels no total e ter no máximo 30 MB. `size` aceita apenas `1K`, `1.5K`, `2K` ou `auto`, com padrão `auto`. `output_format` controla apenas o formato da imagem base; as camadas decompostas são sempre PNG.
</ParamField>

<ParamField body="optimize_prompt_options" type="object" default={'{"mode":"standard"}'}>
  Modo de otimização do prompt:

  * `standard`: modo padrão com melhor qualidade (padrão)

  A forma plana `"optimize_prompt_options.mode": "standard"` também é aceita.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Número de imagens a gerar. Apenas `1` é compatível; use `seedream-5-0-lite` para geração de imagens em grupo.
</ParamField>

<ParamField body="image_urls" type="array">
  Lista de URLs de imagens de referência para image-to-image com uma / várias referências, **até 10**

  Dois formatos:

  **1. URL pública**

  * `http://` ou `https://`
  * Exemplo: `https://example.com/image.jpg`

  **2. Base64 (Data URI)**

  * Formato: `data:image/<format>;base64,<data>` — `<format>` deve estar em **minúsculas**
  * Exemplo: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABg...`

  **Limites por imagem:**

  * Formatos: jpeg / png / webp / bmp / tiff / gif / heic / heif
  * Proporção (l/a): `[1/16, 16]`
  * Cada lado > 14 px
  * Tamanho ≤ 30 MB
  * Total de pixels ≤ `6000×6000` (36.000.000)

  > **Cobrança:** primeira imagem de referência gratuita; cada imagem adicional com sobretaxa fixa.
</ParamField>

<ParamField body="output_format" type="string" default="jpeg">
  Formato de saída da imagem

  * `jpeg` (padrão)
  * `png`

  > **Compatibilidade:** `response_format` é equivalente a `output_format`; outros valores são tratados como `jpeg`.
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  Se deve adicionar marca d'água "AI generated" no canto inferior direito

  * `true`: adicionar marca d'água
  * `false`: sem marca d'água (padrão)
</ParamField>

## Exemplos de requisição

### Text-to-image (nível + proporção)

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Cena noturna de cidade cyberpunk, reflexos de neon em ruas molhadas",
  "resolution": "2K",
  "size": "2:1",
  "output_format": "png"
}
```

### Text-to-image (pixels exatos)

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Imagem hero de e-commerce minimalista, fundo branco, produto centralizado",
  "size": "1600x1600"
}
```

### Multi-referência

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Substituir a roupa da imagem 1 pela roupa da imagem 2",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/dress.jpg"
  ],
  "resolution": "2K",
  "size": "auto"
}
```

### Recomendado: 1.5K mesmo preço, melhor qualidade

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Um gato laranja fofo no peitoril da janela ao sol da tarde, cinematográfico",
  "resolution": "1.5K",
  "size": "16:9"
}
```

### Decomposição em camadas

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

Você também pode usar coordenadas `<bbox>` normalizadas para `0–1000` a fim de identificar com precisão os elementos a extrair:

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Separe a imagem em camadas precisas. O texto está em <bbox>180 64 812 198</bbox>; o papagaio está em <bbox>347 305 642 997</bbox>.",
  "image_urls": ["https://example.com/poster.png"],
  "layer_decomposition": true
}
```

### Edição interativa

Descreva em linguagem natural as anotações desenhadas à mão na imagem:

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Edite a imagem de acordo com o esboço. Adicione uma pilha de revistas na área marcada no canto inferior esquerdo e uma xícara de café na área marcada à direita. Remova todas as linhas do esboço e preserve a composição.",
  "image_urls": ["https://example.com/sketch.png"],
  "size": "2K",
  "output_format": "png"
}
```

Ou indique locais com precisão usando `<point>` / `<bbox>`:

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Coloque o objeto da imagem 1 em <bbox>179 283 796 986</bbox> na imagem 2, na posição <bbox>118 331 933 871</bbox>.",
  "image_urls": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}
```

### Edição do canal alfa

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "Transforme o papagaio em um pavão, preservando o fundo transparente",
  "image_urls": ["https://cdn.example.com/images/layer.png"],
  "background": "transparent",
  "output_format": "png",
  "size": "2K"
}
```

## Exemplo completo: enviar uma tarefa e obter a imagem

O script a seguir mostra o fluxo completo: enviar uma tarefa assíncrona, consultar seu status, tratar estados de falha e ler a URL final da imagem. Substitua `YOUR_API_KEY` antes de executá-lo.

```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 a tarefa de geração
create_response = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers=headers,
    json={
        "model": "seedream-5-0-flash",
        "prompt": "Uma cidade aquática de Jiangnan em estilo de pintura a nanquim, com leve névoa 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"Tarefa enviada: {task_id}")

# 2. Consultar o status da tarefa
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}; progresso: {task.get('progress', 0)}%")

    if status == "success":
        image = task["result"]["images"][0]
        print("URL da imagem:", image["url"][0])
        print("Tamanho da imagem:", image["sizes"][0])
        print("Formato da imagem:", image["output_formats"][0])
        break

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

    time.sleep(5)
```

Em caso de sucesso, o endpoint de consulta da tarefa retorna:

```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>
  As imagens retornadas são espelhadas em um armazenamento gerenciado pela plataforma. Mesmo assim, baixe-as e armazene-as prontamente em seu próprio sistema; não trate a URL do resultado como armazenamento permanente.
</Note>

## Cenários completos de cURL

### Composição com várias imagens (até 10 referências)

```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": "Coloque a pessoa da imagem 1 na cena da imagem 2 e unifique a iluminação no entardecer",
    "image_urls": [
      "https://example.com/person.jpg",
      "https://example.com/scene.jpg"
    ],
    "resolution": "1.5K",
    "size": "16:9",
    "output_format": "png"
  }'
```

### Pixels exatos, otimização do prompt e marca-d'água

```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": "Um horizonte urbano cyberpunk com luzes de néon refletidas em ruas molhadas",
    "size": "2048x1024",
    "optimize_prompt_options": { "mode": "standard" },
    "watermark": true
  }'
```

### Decompor e editar uma camada transparente separadamente

Primeiro, decomponha a imagem de origem:

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

Depois, obtenha a URL de uma camada transparente e edite-a separadamente:

```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": "Transforme o papagaio da imagem em um pavão",
    "image_urls": ["https://cdn.example.com/images/image_task_xxx_4.png"],
    "background": "transparent",
    "output_format": "png",
    "size": "2K"
  }'
```

## Resposta e reconstrução da decomposição em camadas

Os arrays `url`, `sizes`, `output_formats` e `layers` correspondem por índice; o índice `0` é sempre a imagem 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 do título",
          "description": "Texto de título grande e amarelo em fonte serifada",
          "bounding_box": {
            "absolute": [383, 120, 1655, 384],
            "normalized": [187, 59, 808, 188]
          }
        },
        {
          "z_index": 2,
          "size": "492x98",
          "output_format": "png",
          "name": "Slogan no canto superior esquerdo",
          "description": "Slogan em inglês com duas linhas na cor branca",
          "bounding_box": {
            "absolute": [140, 451, 631, 548],
            "normalized": [68, 220, 308, 268]
          }
        }
      ]
    }]
  }
}
```

Componha as camadas em ordem crescente de `z_index`. Para reconstruí-las sobre a imagem base de saída usando coordenadas absolutas:

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

Para reconstruí-las em qualquer tela `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>
  A decomposição em camadas é cobrada por imagem. Até 17 imagens são pré-autorizadas quando a tarefa é enviada. Após a conclusão, cada saída é classificada pelo número real de pixels e liquidada separadamente; qualquer excesso de pré-autorização é reembolsado automaticamente. Seu saldo deve cobrir a pré-autorização de 17 imagens, e `size: "auto"` é pré-autorizado no nível 2K.
</Warning>

## Notas de cobrança

```
Total = preço unitário de saída + acréscimo de referências × max(0, qtd_refs − 1)
```

A saída é cobrada pelo **total real de pixels** (\~2.61M = 2,601,124):

| Condição                                                                                                    | Preço unitário       |
| ----------------------------------------------------------------------------------------------------------- | -------------------- |
| Total de pixels ≤ 2.61M (1.5K ou menos: `resolution` `1K` / `1.5K` / omitido, ou pixels exatos ≤ 2,601,124) | **\$0.045** / imagem |
| Total de pixels > 2.61M (acima de 1.5K: `resolution: "2K"`, ou pixels exatos > 2,601,124)                   | **\$0.09** / imagem  |

* **1.5K custa o mesmo que 1K** (\$0.045).
* Com pixels exatos em `size`, a cobrança usa a **área de saída real**; `resolution` não influi (ex.: `size: "2048x2048"` → \$0.09).
* A 1ª imagem de referência é grátis; cada adicional tem acréscimo.
* Tarefas com falha são reembolsadas por completo.

### Pré-autorização e liquidação da decomposição em camadas

Como o número e as dimensões finais das camadas não são conhecidos ao enviar a tarefa, a pré-autorização usa regras conservadoras com base na solicitação:

* Pixels exatos: nível definido pela área de pixels solicitada.
* `1K` / `1.5K`: pré-autorizado no nível 1K.
* `2K`: pré-autorizado no nível 2K.
* `auto`: pode gerar até 2K e, por isso, é pré-autorizado no nível 2K.

Após a conclusão, a imagem base e cada camada real são **classificadas e somadas individualmente** com base em suas áreas reais de pixels. O excesso de pré-autorização é reembolsado automaticamente. As camadas geralmente são muito menores que a imagem base, portanto até uma tarefa pré-autorizada em 2K pode ser liquidada integralmente no nível 1K.

<Info>
  Exemplo: uma entrada de `1080×1080` é decomposta em 10 imagens. A tarefa é pré-autorizada como `17 imagens × nível 2K`. Se todas as 10 imagens finais tiverem no máximo 2,61 milhões de pixels, a liquidação usa `10 imagens × nível 1K` e o crédito restante é reembolsado automaticamente.
</Info>

## Erros comuns

| Caso                                                       | Notas                                                                                               |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Nível `resolution` não suportado                           | ex.: 3K / 4K → 400                                                                                  |
| Valor de `size` não compatível                             | Não é `1K` / `1.5K` / `2K` / `auto`, uma proporção compatível nem dimensões de pixels válidas → 400 |
| Total de pixels exatos fora do intervalo                   | Deve estar em `[921600, 4624220]`                                                                   |
| Proporção de pixels exatos fora do intervalo               | Deve estar em `[1/16, 16]`                                                                          |
| `n > 1` / parâmetros de imagens agrupadas                  | Rejeitado pelo modelo de imagem única                                                               |
| Mais de 10 imagens de referência                           | Rejected                                                                                            |
| Decomposição sem imagem ou com várias imagens              | É necessária exatamente uma imagem                                                                  |
| Decomposição com proporção ou pixels exatos                | `size` aceita apenas `1K` / `1.5K` / `2K` / `auto`                                                  |
| Fundo transparente para texto em imagem ou várias entradas | É necessária exatamente uma imagem de entrada com canal alfa                                        |
| Fundo transparente com JPEG                                | Defina `output_format: "png"`                                                                       |
| `stream` / `tools`                                         | Não compatível com este modelo; retorna 400                                                         |
| Modo de otimização de prompt inválido                      | Apenas `standard` é compatível                                                                      |

<Note>
  ⏱️ **Geração mais lenta**: cerca de 90 s para 1K e 160 s para 2K (prioridade para qualidade). Consulte [Obter status da tarefa](/pt/api-reference/tasks/status) a cada 5–10 segundos e defina o tempo limite do cliente como **5 minutos**. Salve os resultados gerados prontamente.
</Note>

## Resposta

<ResponseField name="code" type="integer">
  Código de status da resposta
</ResponseField>

<ResponseField name="data" type="array">
  Array de dados da resposta

  <Expandable title="Propriedades">
    <ResponseField name="status" type="string">
      Status da tarefa

      * `submitted` - Enviada
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Identificador único da tarefa
    </ResponseField>
  </Expandable>
</ResponseField>