> ## 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.5 > Gere imagens a partir de texto ou até 10 referências, com fundo transparente, decomposição em camadas configurável e OCR por API assíncrona. ```bash cURL theme={null} curl --request POST \ --url https://api.apimart.ai/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "seedream-5-5", "prompt": "An orange cat sticker with clean edges", "size": "2K", "background": "transparent", "output_format": "png" }' ``` ```python Python theme={null} import requests payload = { "model": "seedream-5-5", "prompt": "An orange cat sticker with clean edges", "size": "2K", "background": "transparent", "output_format": "png" } response = requests.post( "https://api.apimart.ai/v1/images/generations", headers={"Authorization": "Bearer "}, json=payload, timeout=60, ) response.raise_for_status() print(response.json()) ``` ```javascript JavaScript theme={null} const payload = { "model": "seedream-5-5", "prompt": "An orange cat sticker with clean edges", "size": "2K", "background": "transparent", "output_format": "png" }; const response = await fetch("https://api.apimart.ai/v1/images/generations", { method: "POST", headers: { "Authorization": "Bearer ", "Content-Type": "application/json" }, body: JSON.stringify(payload) }); if (!response.ok) throw new Error(await response.text()); console.log(await response.json()); ``` ```json 200 theme={null} { "code": 200, "data": [ { "status": "submitted", "task_id": "task_example_seedream55" } ] } ``` Envie para `POST /v1/images/generations`, salve `data[0].task_id` e consulte `GET /v1/tasks/{task_id}`. ## Modos | Modo | Ativação | Imagens de entrada | Prompt | | - | - | - | - | | Geração de imagens | Padrão | 0–10 | Obrigatório | | Decomposição em camadas | `layer_decomposition: true` | Exatamente 1 | Opcional | ## Autenticação **Authorization** `string` *required* Use `Authorization: Bearer `, em que `` é sua APIMart API Key. ## Parâmetros da requisição **model** `string` *required* Use `seedream-5-5`. **prompt** `string` Obrigatório para gerar a partir de texto ou imagens. Opcional na decomposição: o modelo identifica elementos, texto e fundo automaticamente. Você também pode descrever o que separar. **image\_urls** `string[]` Até 10 referências na geração; exatamente 1 imagem na decomposição. Aceita URL pública ou Data URI Base64 de imagem. Para arquivos locais, use a [API de upload](https://docs.apimart.ai/pt/api-reference/uploads/images.md) e envie a `url` retornada. Use URLs `http(s)` acessíveis publicamente ou `data:image/;base64,…`, com o nome do formato em minúsculas na Data URI. * Formatos aceitos: JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC e HEIF. AVIF e JP2 não são aceitos. * Por imagem: no máximo **30 MiB (31,457,280 bytes)** e **36 milhões de pixels no total**. Verifique largura × altura; não é um limite de 6000 pixels por lado. * Exceder tamanho ou pixels retorna HTTP 400 síncrono. AVIF e JP2 podem criar uma tarefa antes de serem rejeitados pelo provedor; falhas são reembolsadas. Converta esses formatos antes do envio. O endpoint de upload tem restrições próprias de formato. Para formatos aceitos pelo modelo mas não pelo upload, use URL pública ou Data URI. **size** `string` Geração: padrão `2K`, aceita nível, proporção ou pixels exatos. Decomposição: padrão `auto`, apenas `1K` / `1.5K` / `2K` / `auto`. Na geração de imagens, `size: "auto"` equivale a `2K`. Proporções sem `resolution` também usam `2K`. Para pixels exatos, omita `resolution` e use inteiros positivos para largura e altura. **resolution** `string` Na geração, use `1K` / `1.5K` / `2K` com uma proporção em `size`. Na decomposição, é um alias de plataforma para `size`: `size` tem prioridade, `resolution` só vale quando `size` é omitido e, sem ambos, vale `auto`. Aceita `1K` / `1.5K` / `2K` / `auto`; proporções ou pixels são rejeitados de forma síncrona com HTTP 400. Sem `3K` / `4K`. **background** `string` Geração: `auto` (padrão), `transparent` ou `opaque`. Transparência funciona com texto e imagens. Exige PNG e não permite `output_format: "jpeg"`. Na decomposição, omita o campo completamente, inclusive `auto`. **output\_format** `string` (default: png) `png` (padrão) ou `jpeg`. Na decomposição, controla apenas a imagem base; as camadas extraídas são sempre PNG transparentes. **n** `integer` Apenas `1`. A geração produz uma imagem por requisição. Controle a quantidade da decomposição com `layer_decomposition_options.max_images`. **watermark** `boolean` (default: false) Indicador opcional para adicionar marca-d’água. **optimize\_prompt\_options** `object` Aceita apenas `{"mode":"standard"}`. Omitir mantém o padrão `standard` do provedor; não é possível desativar a otimização no Seedream 5.5. O provedor rejeita `disabled` / `none` / `off` com HTTP 400 e `must be one of: standard`. A plataforma rejeita `fast` imediatamente com HTTP 400. **layer\_decomposition** `boolean` `true` separa a entrada em imagem base e camadas transparentes. Exige exatamente uma imagem e ausência de `background`. `output_format` controla apenas a base. **layer\_decomposition\_options** `object` Apenas com `layer_decomposition: true`; caso contrário, HTTP 400. **Parâmetros da requisição** **max\_images** `integer` (default: 30) Inteiro de `2` a `100`, padrão `30`. Limite total de imagens de saída, incluindo a base; não garante essa quantidade. **text\_recognition** `boolean` (default: false) Booleano opcional. `true` solicita OCR com estilos para camadas de texto. `text_recognition` pode aparecer apenas para texto regular reconhecível. Com OCR ativado, enviar `prompt` pode impedir o retorno do reconhecimento de texto. Se OCR for a prioridade, tente omitir o prompt de decomposição. Isso não garante resultados; trate os campos como opcionais. ## Formatos de tamanho | Formato | Exemplo | Regras | | - | - | - | | Nível | `"size": "2K"` | `1K` / `1.5K` / `2K`; padrão `2K`. O modelo escolhe a proporção conforme o prompt. | | Proporção + nível | `"size": "16:9", "resolution": "1.5K"` | Somente geração. Proporções abaixo; também aceita `16x9`. | | Pixels exatos | `"size": "2048x1152"` | Somente geração. Total: 921.600–4.624.220 pixels; largura/altura: 1/16–16. | Proporções: `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9`, `2:1`, `1:2`. Os limites se aplicam à área em pixels e à proporção. A decomposição aceita apenas níveis ou `auto`, não proporções nem pixels exatos. ### Tamanhos de saída na decomposição * Prioridade: `size` → `resolution` → `auto`. `resolution` é um alias da plataforma; o provedor recebe apenas `size`. `size: "1K"` com `resolution: "2K"` usa `1K`; apenas `resolution: "1.5K"` usa `1.5K`. * Com `1K` / `1.5K` / `2K`, a base e cada camada saem no nível escolhido, cada uma preservando sua proporção. Uma base medida em `1K` tinha `840×1248`, e cada camada também tinha cerca de 1,05 milhão de pixels. São exemplos, não dimensões fixas. * `auto` usa as dimensões originais da entrada: amplia entradas abaixo de `1K` para `1K` e reduz entradas acima de `2K` para `2K`. ## Exemplos de requisição ### Edição e fusão de referências ```bash theme={null} curl --request POST \ --url https://api.apimart.ai/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "seedream-5-5", "prompt": "Combine the product in the first image with the setting in the second image", "image_urls": ["https://example.com/product.png", "https://example.com/setting.jpg"], "size": "16:9", "resolution": "1.5K", "output_format": "png" }' ``` ### Decomposição e OCR A requisição produz até 10 imagens, incluindo a base. `prompt` é opcional; omita `background`. Substitua a URL por uma imagem acessível. ```bash theme={null} curl --request POST \ --url https://api.apimart.ai/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "seedream-5-5", "image_urls": ["https://example.com/poster.png"], "layer_decomposition": true, "layer_decomposition_options": { "max_images": 10, "text_recognition": true }, "size": "1K" }' ``` ## Consultar tarefa Consulte a [API de status](https://docs.apimart.ai/pt/api-reference/tasks/status.md) a cada 3 segundos nos primeiros 30 segundos e depois a cada 5–10 segundos. A decomposição pode levar minutos; o servidor aguarda até 13 minutos. Salve `task_id` e consulte até um estado final, sem reenviar a geração. ```bash theme={null} curl --request GET \ --url 'https://api.apimart.ai/v1/tasks/task_example_seedream55' \ --header 'Authorization: Bearer ' ``` Em `data.status`, `pending` / `processing` significa em andamento e `completed` significa sucesso. Com `failed`, consulte `data.error.message`; os valores são reembolsados automaticamente. As URLs ficam em `data.result.images[].url[]`. > [!WARNING] > > As imagens de resultado são armazenadas por **3 dias**; baixe-as prontamente. Os registros das tarefas também são mantidos por apenas 3 dias, após os quais não podem ser consultados por `task_id`. > > `data.result.images[].expires_at` atualmente retorna um timestamp Unix em segundos igual à conclusão da tarefa + 24 horas. É uma indicação conservadora anterior à exclusão real. Não a use para calcular a retenção efetiva ou uma contagem regressiva para exclusão. ## Resultados das camadas e OCR Este exemplo ilustra a estrutura, não uma execução registrada. Dimensões, coordenadas e texto são exemplos. Metadados podem estar ausentes. ```json theme={null} { "code": 200, "data": { "id": "task_example_seedream55", "status": "completed", "progress": 100, "completed": 1794302642, "result": { "images": [ { "url": ["https://example.com/base.png", "https://example.com/title.png"], "sizes": ["840x1248", "1512x702"], "output_formats": ["png", "png"], "backgrounds": ["opaque", "transparent"], "expires_at": 1794389042, "layer_decomposition": true, "layers": [ { "z_index": 0, "size": "840x1248", "output_format": "png", "background": "opaque" }, { "z_index": 1, "size": "1512x702", "output_format": "png", "background": "transparent", "name": "Sale title", "description": "Printed sale title", "bounding_box": { "absolute": [84, 156, 756, 468], "normalized": [100, 125, 900, 375] }, "text_recognition": { "text": "SUMMER SALE", "lines": [ { "bounding_box": { "absolute": [126, 156, 714, 468], "normalized": [150, 125, 850, 375] }, "runs": [ { "text": "SUMMER SALE", "style": { "similar_font_family": "Arial", "foreground_color": "#222222", "bold": true, "italic": false, "underline": false, "strikethrough": false, "shadow": false, "translucent": false } } ] } ] } } ] } ] } } } ``` Em cada `data.result.images[]`, `url`, `sizes`, `output_formats`, `backgrounds` e `layers` correspondem por índice. Arrays de metadados podem ser omitidos se seu tamanho diferir de `url`. | Campo | Descrição | | - | - | | `url[]` | URLs das imagens. No modo de camadas, o índice 0 é a base, seguido das camadas. Baixe e salve os arquivos assim que possível. | | `sizes[]` / `output_formats[]` | Dimensões e formato reais de cada imagem. | | `backgrounds[]` | Fundo real: `opaque` / `transparent`. Consulte esse valor com `background: "auto"`. | | `expires_at` | Atualmente, timestamp Unix igual à conclusão da tarefa + 24 horas (86400 segundos). É uma indicação conservadora, não o momento real de exclusão da imagem; não use como contagem regressiva. | | `layer_decomposition` | Indica se é um resultado de decomposição. | | `layers[i].z_index` | Ordem de empilhamento: base em 0; componha em ordem crescente. | | `layers[i].background` | Base: `opaque`; camadas extraídas: `transparent`. | | `layers[i].name` / `description` | Nome e descrição opcionais da camada. | | `layers[i].bounding_box` | `absolute`: `[left, top, right, bottom]` em pixels da base. `normalized`: o mesmo quadro normalizado para 0–1000. Ausente na base. | | `layers[i].text_recognition` | Pode aparecer com OCR ativado e texto regular reconhecido; ausente em letras artísticas, manuscritas e camadas sem texto. | Coordenadas absolutas: `x=left`, `y=top`, `w=right-left`, `h=bottom-top`. Para uma tela de `W × H`, converta coordenadas normalizadas assim: ```text theme={null} x = left / 1000 * W y = top / 1000 * H w = (right - left) / 1000 * W h = (bottom - top) / 1000 * H ``` Cada camada é dimensionada separadamente no nível escolhido e pode diferir de sua `bounding_box`. Para compor, redimensione para `w × h` e posicione em `(x, y)`. Não use os pixels do arquivo diretamente como coordenadas da base. ### Campos de reconhecimento de texto `text_recognition` segue a estrutura OCR do modelo de origem. A plataforma repassa campos como `text`, `lines`, `runs` e `style` sem alterações. | Campo | Descrição | | - | - | | `text` | Texto completo da camada, com linhas separadas por `\n`. | | `lines[].bounding_box` | Quadro da linha nas coordenadas da base. | | `lines[].runs[]` | Trechos com estilos diferentes em uma linha, cada um com `text` e `style`. | | `runs[].style.similar_font_family` | Família de fonte mais parecida, ou `unknown`. | | `runs[].style.foreground_color` | Cor do texto em `#RRGGBB`. | | `runs[].style.bold` / `italic` / `underline` / `strikethrough` / `shadow` / `translucent` | Indicadores booleanos de estilo estimados pelo modelo; podem ser imprecisos. | OCR e fontes ajudam na exibição, cópia e edição, mas podem diferir do original. As imagens das camadas continuam utilizáveis sem OCR. ## Cobrança Imagens de saída e referências de entrada são cobradas separadamente. **Toda referência é cobrada, inclusive a primeira** e a única entrada usada na decomposição. * Cada saída usa a área real: até **2,610,000** pixels inclusive, faixa baixa; acima disso, faixa alta. `1K` / `1.5K` correspondem à faixa baixa e `2K` à alta. Dimensões exatas usam largura × altura. * A geração reserva o preço da faixa de saída selecionada mais quantidade de referências × preço de entrada. Sem `size` ou com `auto`, reserva em `2K`. * A decomposição reserva `max_images` × preço da faixa de saída **mais uma imagem de entrada**. `max_images` tem padrão 30, incluindo a base; podem ser produzidas menos imagens. * A decomposição usa o `size` efetivo, ou `resolution` se ausente: `1K` / `1.5K` reservam na faixa baixa; `2K` / `auto`, na alta. Sem ambos, vale `auto` com reserva alta. * A liquidação usa a quantidade real de saídas, a faixa de pixels de cada uma e a quantidade de entradas, devolvendo ou cobrando a diferença. Base e camadas contam individualmente; não aplique a faixa solicitada a todas as saídas sem verificar seus pixels. Falhas têm reembolso integral. Consulte os [preços dos modelos](https://apimart.ai/pricing). ## Erros comuns de parâmetros Inclui validações da plataforma e do provedor. Leia `error.message` para falhas no envio e `data.error.message` para falhas de tarefas assíncronas. | Trecho do erro | Solução | | - | - | | `does not support optimize_prompt_options.mode=fast` | A plataforma retorna HTTP 400 de forma síncrona. Apenas `standard` é permitido; omitir também mantém a otimização ativa. | | `must be one of: standard` | HTTP 400 do provedor: `disabled` / `none` / `off` não são aceitos; não é possível desativar a otimização. | | `only supports background auto, transparent or opaque` | Use `auto`, `transparent` ou `opaque`. | | `cannot combine background=transparent with output_format=jpeg` | Use `output_format: "png"` para transparência. | | `does not accept background when layer_decomposition=true` | Remova `background`, inclusive `auto`, na decomposição. | | `layer_decomposition_options requires layer_decomposition=true` | Envie o objeto apenas em decomposição. | | `layer_decomposition_options.max_images must be within [2, 100]` | `max_images`: inteiro de 2 a 100, incluindo a base. | | `invalid layer_decomposition_options` | Use inteiro para `max_images`, não string nem decimal; booleano para `text_recognition`. | | `with layer_decomposition=true requires exactly 1 input image` | Envie exatamente uma imagem para decompor. | | `only supports size 1K, 1.5K, 2K or auto` | Na decomposição, prioriza `size`, senão `resolution`. Apenas `1K` / `1.5K` / `2K` / `auto`; proporções ou pixels retornam HTTP 400 de forma síncrona. | | `` `n` must be 1 `` | Defina `n` como `1`; geração em lote não é aceita. | | `does not support stream` / `does not support tools` | Remova `sequential_image_generation`, `stream` e `tools`. | | `supports up to 10 reference images` | Envie até 10 referências. | | `reference image too large for seedream-5-5` | Cada referência deve ter no máximo 30 MiB e 36 milhões de pixels. Comprima ou redimensione. | | `does not support size` / `requires total pixels` / `requires aspect ratio` | Verifique área em pixels, proporção e notação do tamanho. 3K / 4K não são aceitos. | | `` `prompt` parameter is required `` | A geração exige prompt. Somente a decomposição permite omiti-lo. | ## Motivos de falha da tarefa Quando `data.status` for `failed`, leia `data.error.message` e `data.error.reason`. As cobranças são devolvidas automaticamente. Se `reason` estiver ausente ou for desconhecido, use `message` como alternativa. | `data.error.reason` | Ação | | - | - | | `content_policy_violation` | Entrada ou saída reprovada na análise de conteúdo. Altere o prompt ou as imagens. | | `invalid_parameter` / `unsupported_option` | Parâmetro ou combinação não aceitos. Ajuste a solicitação. | | `invalid_media` | Imagem danificada ou formato não aceito. Verifique e converta. | | `media_unreachable` | URL da imagem inacessível. Verifique o acesso público ou envie novamente. | | `generation_timeout` | Tempo limite de geração excedido. Tente mais tarde. | | `service_unavailable` | Serviço temporariamente ocupado. Tente mais tarde. | | `delivery_failed` / `internal_error` / `unknown_error` | Falha de entrega ou erro interno. Siga a mensagem retornada e tente mais tarde. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.