> ## Documentation Index
> Fetch the complete documentation index at: https://gccai.heqingsong.uk/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedream-5-0-pro",
    "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://gccai.heqingsong.uk/v1/images/generations"

payload = {
    "model": "seedream-5-0-pro",
    "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://gccai.heqingsong.uk/v1/images/generations";

const payload = {
  model: "seedream-5-0-pro",
  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://gccai.heqingsong.uk/v1/images/generations"

    payload := map[string]interface{}{
        "model":      "seedream-5-0-pro",
        "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://gccai.heqingsong.uk/v1/images/generations";

        String payload = """
        {
          "model": "seedream-5-0-pro",
          "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://gccai.heqingsong.uk/v1/images/generations";

$payload = [
    "model" => "seedream-5-0-pro",
    "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://gccai.heqingsong.uk/v1/images/generations")

payload = {
  model: "seedream-5-0-pro",
  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://gccai.heqingsong.uk/v1/images/generations")!

let payload: [String: Any] = [
    "model": "seedream-5-0-pro",
    "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://gccai.heqingsong.uk/v1/images/generations";

        var payload = @"{
            ""model"": ""seedream-5-0-pro"",
            ""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://gccai.heqingsong.uk/v1/images/generations";
        const char *payload = "{"
            "\"model\":\"seedream-5-0-pro\","
            "\"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://gccai.heqingsong.uk/v1/images/generations"];

        NSDictionary *payload = @{
            @"model": @"seedream-5-0-pro",
            @"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://gccai.heqingsong.uk/v1/images/generations"

let payload = {|{
  "model": "seedream-5-0-pro",
  "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://gccai.heqingsong.uk/v1/images/generations');

  final payload = {
    'model': 'seedream-5-0-pro',
    '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://gccai.heqingsong.uk/v1/images/generations"

payload <- list(
  model = "seedream-5-0-pro",
  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"))
```

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

## Autorização

**Authorization** `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://gccai.heqingsong.uk/keys) para obter sua chave de API

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

```
Authorization: Bearer YOUR_API_KEY
```

> [!NOTE]
>
> **Modelo de imagem única**: `seedream-5-0-pro` 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`

> **Edição interativa**
>
> 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)

> **Decomposição em camadas**
>
> Divida uma imagem em uma imagem base e até 16 camadas PNG transparentes, com informações de posição e empilhamento.

## Corpo da requisição

**model** `string` *required* (default: seedream-5-0-pro)

Nome do modelo de geração de imagens

* `seedream-5-0-pro` (recomendado)
* Também aceito: `seedream-5.0-pro`

**nsfw\_check** `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)

**prompt** `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.

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

Nível de resolução (minúsculas aceitas). Esta é uma extensão da GccAi 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`.

**size** `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 GccAi `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.

**background** `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.

**layer\_decomposition** `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.

**optimize\_prompt\_options** `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.

**n** `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.

**image\_urls** `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.

**output\_format** `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`.

**watermark** `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)

## Exemplos de requisição

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

```json theme={null}
{
  "model": "seedream-5-0-pro",
  "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-pro",
  "prompt": "Imagem hero de e-commerce minimalista, fundo branco, produto centralizado",
  "size": "1600x1600"
}
```

### Multi-referência

```json theme={null}
{
  "model": "seedream-5-0-pro",
  "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-pro",
  "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-pro",
  "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-pro",
  "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-pro",
  "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-pro",
  "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-pro",
  "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://gccai.heqingsong.uk"
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-pro",
        "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.

## Cenários completos de cURL

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

```bash theme={null}
curl -X POST "https://gccai.heqingsong.uk/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "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://gccai.heqingsong.uk/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "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://gccai.heqingsong.uk/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "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://gccai.heqingsong.uk/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "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.

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

> [!NOTE]
>
> 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.

## 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](https://gccai.heqingsong.uk/pt/api-reference/tasks/status.md) a cada 5–10 segundos e defina o tempo limite do cliente como **5 minutos**. Salve os resultados gerados prontamente.

## Resposta

**code** `integer`

Código de status da resposta

**data** `array`

Array de dados da resposta

**Propriedades**

**status** `string`

Status da tarefa

* `submitted` - Enviada

**task\_id** `string`

Identificador único da tarefa


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