> ## 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.5 > Genera imágenes desde texto o hasta 10 referencias, con fondo transparente, descomposición en capas configurable y OCR mediante una API así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" } ] } ``` Envía a `POST /v1/images/generations`, guarda `data[0].task_id` y consulta `GET /v1/tasks/{task_id}`. ## Modos | Modo | Activación | Imágenes de entrada | Prompt | | - | - | - | - | | Generación de imágenes | Predeterminado | 0–10 | Obligatorio | | Descomposición en capas | `layer_decomposition: true` | Exactamente 1 | Opcional | ## Autenticación **Authorization** `string` *required* Usa `Authorization: Bearer `, donde `` es tu APIMart API Key. ## Parámetros de solicitud **model** `string` *required* Usa `seedream-5-5`. **prompt** `string` Obligatorio para generar desde texto o imágenes. Opcional en descomposición: el modelo identifica sujetos, texto y fondo automáticamente. Puedes indicar qué elementos separar. **image\_urls** `string[]` Hasta 10 referencias para generar; exactamente 1 imagen para descomponer. Acepta URL públicas o Data URI Base64 de imágenes. Sube archivos locales mediante la [API de carga](https://docs.apimart.ai/es/api-reference/uploads/images.md) y utiliza la `url` devuelta. Usa URL `http(s)` accesibles públicamente o `data:image/;base64,…`, con el nombre del formato en minúsculas en la Data URI. * Formatos admitidos: JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC y HEIF. AVIF y JP2 no se admiten. * Por imagen: máximo **30 MiB (31,457,280 bytes)** y **36 millones de píxeles totales**. Comprueba ancho × alto; no es un límite de 6000 píxeles por lado. * Exceder tamaño o píxeles devuelve HTTP 400 síncrono. AVIF y JP2 pueden crear una tarea antes del rechazo del proveedor; las tareas fallidas se reembolsan. Convierte esos formatos antes de enviar. El endpoint de subida tiene sus propias restricciones de formato. Para formatos admitidos por el modelo pero no por ese endpoint, usa una URL pública o Data URI. **size** `string` Generación: `2K` predeterminado; admite nivel, proporción o píxeles exactos. Descomposición: `auto` predeterminado; solo `1K` / `1.5K` / `2K` / `auto`. En generación, `size: "auto"` equivale a `2K`. Una relación de aspecto sin `resolution` también usa `2K`. Para píxeles exactos, omite `resolution` y usa enteros positivos para ancho y alto. **resolution** `string` En generación, usa `1K` / `1.5K` / `2K` con una proporción en `size`. En descomposición es un alias de plataforma para `size`: prevalece `size`, se usa `resolution` solo si falta `size` y, si faltan ambos, se aplica `auto`. Admite `1K` / `1.5K` / `2K` / `auto`; proporciones o píxeles se rechazan de forma síncrona con HTTP 400. No admite `3K` / `4K`. **background** `string` Generación: `auto` (predeterminado), `transparent` u `opaque`. La transparencia funciona desde texto e imágenes. Requiere PNG y no admite `output_format: "jpeg"`. Omite el campo por completo en descomposición, incluso `auto`. **output\_format** `string` (default: png) `png` (predeterminado) o `jpeg`. En descomposición solo afecta a la imagen base; las capas extraídas siempre son PNG transparentes. **n** `integer` Solo `1`. La generación produce una imagen por solicitud. Para la cantidad en descomposición, usa `layer_decomposition_options.max_images`. **watermark** `boolean` (default: false) Indicador opcional para añadir marca de agua. **optimize\_prompt\_options** `object` Solo admite `{"mode":"standard"}`. Omitirlo mantiene el valor predeterminado `standard` del proveedor; Seedream 5.5 no permite desactivar la optimización. El proveedor rechaza `disabled` / `none` / `off` con HTTP 400 y `must be one of: standard`. La plataforma rechaza `fast` inmediatamente con HTTP 400. **layer\_decomposition** `boolean` `true` separa la entrada en una imagen base y capas transparentes. Requiere exactamente una imagen y omitir `background`. `output_format` solo controla la base. **layer\_decomposition\_options** `object` Solo con `layer_decomposition: true`; de lo contrario, HTTP 400. **Parámetros de solicitud** **max\_images** `integer` (default: 30) Entero de `2` a `100`, predeterminado `30`. Máximo total de imágenes de salida, incluida la base; no garantiza esa cantidad. **text\_recognition** `boolean` (default: false) Booleano opcional. `true` solicita OCR con estilos en capas de texto. `text_recognition` puede aparecer solo para texto regular reconocible. Con OCR activado, incluir `prompt` puede impedir que se devuelva el reconocimiento de texto. Si OCR es prioritario, prueba a omitir el prompt de descomposición. No garantiza resultados; los campos siguen siendo opcionales. ## Formatos de tamaño | Formato | Ejemplo | Reglas | | - | - | - | | Nivel | `"size": "2K"` | `1K` / `1.5K` / `2K`; predeterminado `2K`. El modelo elige la proporción según el prompt. | | Proporción + nivel | `"size": "16:9", "resolution": "1.5K"` | Solo generación. Proporciones abajo; también acepta `16x9`. | | Píxeles exactos | `"size": "2048x1152"` | Solo generación. Total: 921.600–4.624.220 píxeles; ancho/alto: 1/16–16. | Proporciones: `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9`, `2:1`, `1:2`. Los límites se aplican al área en píxeles y a la proporción. La descomposición solo admite niveles o `auto`, no proporciones ni píxeles exactos. ### Tamaños de salida en descomposición * Prioridad: `size` → `resolution` → `auto`. `resolution` es un alias de la plataforma; el proveedor solo recibe `size`. `size: "1K"` junto a `resolution: "2K"` aplica `1K`; solo `resolution: "1.5K"` aplica `1.5K`. * Con `1K` / `1.5K` / `2K`, tanto la base como cada capa se generan en el nivel elegido, conservando cada una su proporción. Una base medida en `1K` fue de `840×1248`, con cada capa también cerca de 1,05 millones de píxeles. Son ejemplos, no dimensiones fijas. * `auto` usa las dimensiones originales de entrada: amplía las inferiores a `1K` hasta `1K` y reduce las superiores a `2K` hasta `2K`. ## Ejemplos de solicitud ### Edición y fusión de referencias ```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" }' ``` ### Descomposición y OCR La solicitud produce hasta 10 imágenes, incluida la base. `prompt` es opcional; omite `background`. Sustituye la URL por una imagen accesible. ```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 una tarea Consulta la [API de estado](https://docs.apimart.ai/es/api-reference/tasks/status.md) cada 3 segundos durante los primeros 30 segundos y luego cada 5–10 segundos. La descomposición puede tardar minutos; el servidor espera hasta 13 minutos. Guarda `task_id` y consulta hasta un estado final sin volver a enviar la generación. ```bash theme={null} curl --request GET \ --url 'https://api.apimart.ai/v1/tasks/task_example_seedream55' \ --header 'Authorization: Bearer ' ``` En `data.status`, `pending` / `processing` indica en curso y `completed` indica éxito. Con `failed`, consulta `data.error.message`; el importe se reembolsa automáticamente. Las URL están en `data.result.images[].url[]`. > [!WARNING] > > Las imágenes de resultado se conservan **3 días**; descárgalas pronto. Los registros de tareas también se conservan solo 3 días; después no se pueden consultar mediante `task_id`. > > `data.result.images[].expires_at` devuelve actualmente un timestamp Unix en segundos igual a la finalización de la tarea + 24 horas. Es una indicación conservadora anterior a la eliminación real. No la uses para calcular la conservación efectiva ni una cuenta atrás hasta la eliminación. ## Resultados de capas y OCR Este ejemplo muestra la estructura, no una ejecución registrada. Tamaños, coordenadas y texto son ilustrativos. Los metadatos pueden faltar. ```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 } } ] } ] } } ] } ] } } } ``` En cada `data.result.images[]`, `url`, `sizes`, `output_formats`, `backgrounds` y `layers` se corresponden por índice. Los arrays de metadatos pueden omitirse si su longitud difiere de `url`. | Campo | Descripción | | - | - | | `url[]` | URL de imágenes. En capas, el índice 0 es la base y le siguen las capas. Descarga y guarda los archivos pronto. | | `sizes[]` / `output_formats[]` | Dimensiones y formato reales de cada imagen. | | `backgrounds[]` | Fondo real: `opaque` / `transparent`. Consulta este valor con `background: "auto"`. | | `expires_at` | Actualmente, timestamp Unix igual a la finalización de la tarea + 24 horas (86400 segundos). Es una indicación conservadora, no el momento real de eliminación de la imagen; no la uses como cuenta atrás. | | `layer_decomposition` | Indica si es un resultado de descomposición. | | `layers[i].z_index` | Orden de apilado: base en 0; compón en orden ascendente. | | `layers[i].background` | Base: `opaque`; capas extraídas: `transparent`. | | `layers[i].name` / `description` | Nombre y descripción opcionales de la capa. | | `layers[i].bounding_box` | `absolute`: `[left, top, right, bottom]` en píxeles de la base. `normalized`: el mismo cuadro normalizado a 0–1000. La base no lo incluye. | | `layers[i].text_recognition` | Puede aparecer con OCR activado y texto regular reconocido; ausente en letras artísticas, manuscritas y capas sin texto. | Coordenadas absolutas: `x=left`, `y=top`, `w=right-left`, `h=bottom-top`. Para un lienzo de `W × H`, convierte las coordenadas normalizadas así: ```text theme={null} x = left / 1000 * W y = top / 1000 * H w = (right - left) / 1000 * W h = (bottom - top) / 1000 * H ``` Cada capa se dimensiona por separado en el nivel elegido y puede diferir de su `bounding_box`. Para componer, redimensiónala a `w × h` y colócala en `(x, y)`. No uses directamente los píxeles del archivo como coordenadas de la base. ### Campos de reconocimiento de texto `text_recognition` sigue la estructura OCR del modelo del proveedor. La plataforma transmite sin cambios campos como `text`, `lines`, `runs` y `style`. | Campo | Descripción | | - | - | | `text` | Texto completo de la capa, con líneas separadas por `\n`. | | `lines[].bounding_box` | Cuadro de la línea en las coordenadas de la base. | | `lines[].runs[]` | Fragmentos con distintos estilos en una línea, cada uno con `text` y `style`. | | `runs[].style.similar_font_family` | Familia tipográfica más parecida, o `unknown`. | | `runs[].style.foreground_color` | Color de texto en formato `#RRGGBB`. | | `runs[].style.bold` / `italic` / `underline` / `strikethrough` / `shadow` / `translucent` | Indicadores booleanos de estilo estimados por el modelo; pueden ser imprecisos. | El OCR y la fuente ayudan a mostrar, copiar o editar, pero pueden diferir del original. Las imágenes de las capas se pueden usar sin OCR. ## Facturación Las imágenes de salida y las referencias de entrada se cobran por separado. **Se cobra cada referencia, incluida la primera** y la única imagen usada para descomposición. * Cada salida se clasifica por sus píxeles reales: hasta **2,610,000** inclusive, nivel bajo; por encima, nivel alto. `1K` / `1.5K` corresponden al bajo y `2K` al alto. Las dimensiones exactas usan ancho × alto. * La generación reserva el coste del nivel de salida seleccionado más número de referencias × precio de entrada. Sin `size` o con `auto`, reserva a `2K`. * La descomposición reserva `max_images` × precio del nivel de salida **más una imagen de entrada**. El valor predeterminado de `max_images` es 30, incluida la base; pueden producirse menos imágenes. * Se usa el `size` efectivo, o `resolution` si falta: `1K` / `1.5K` reservan en el nivel bajo; `2K` / `auto`, en el alto. Sin ambos, se aplica `auto` con reserva alta. * La liquidación usa el número real de salidas, los píxeles de cada una y el número de entradas, devolviendo o cobrando la diferencia. La base y cada capa cuentan por separado; no apliques el nivel solicitado a todas las salidas sin considerar su tamaño real. Las tareas fallidas se reembolsan íntegramente. Consulta los [precios de modelos](https://apimart.ai/pricing). ## Errores comunes de parámetros Incluye validaciones de la plataforma y del proveedor. Consulta `error.message` si falla el envío y `data.error.message` si falla una tarea asíncrona. | Fragmento de error | Solución | | - | - | | `does not support optimize_prompt_options.mode=fast` | La plataforma devuelve HTTP 400 de forma síncrona. Solo admite `standard`; omitirlo también mantiene la optimización activa. | | `must be one of: standard` | HTTP 400 del proveedor: `disabled` / `none` / `off` no están admitidos; no se puede desactivar la optimización. | | `only supports background auto, transparent or opaque` | Usa `auto`, `transparent` u `opaque`. | | `cannot combine background=transparent with output_format=jpeg` | Usa `output_format: "png"` para transparencia. | | `does not accept background when layer_decomposition=true` | Elimina `background`, incluso `auto`, en descomposición. | | `layer_decomposition_options requires layer_decomposition=true` | Envía el objeto solo en descomposición. | | `layer_decomposition_options.max_images must be within [2, 100]` | `max_images`: entero de 2 a 100, incluida la base. | | `invalid layer_decomposition_options` | `max_images` debe ser entero, no cadena ni decimal; `text_recognition`, booleano. | | `with layer_decomposition=true requires exactly 1 input image` | Proporciona exactamente una imagen para descomponer. | | `only supports size 1K, 1.5K, 2K or auto` | En descomposición se usa primero `size`, si falta, `resolution`. Solo `1K` / `1.5K` / `2K` / `auto`; proporciones o píxeles devuelven HTTP 400 de forma síncrona. | | `` `n` must be 1 `` | Establece `n` en `1`; no admite lotes. | | `does not support stream` / `does not support tools` | Elimina `sequential_image_generation`, `stream` y `tools`. | | `supports up to 10 reference images` | Proporciona hasta 10 referencias. | | `reference image too large for seedream-5-5` | Cada referencia debe tener como máximo 30 MiB y 36 millones de píxeles. Comprímela o redimensiónala. | | `does not support size` / `requires total pixels` / `requires aspect ratio` | Comprueba el área de píxeles, la relación de aspecto y la notación. 3K / 4K no se admiten. | | `` `prompt` parameter is required `` | La generación requiere un prompt. Solo la descomposición permite omitirlo. | ## Motivos de fallo de la tarea Cuando `data.status` sea `failed`, lee `data.error.message` y `data.error.reason`. Los cargos se reembolsan automáticamente. Si `reason` falta o es desconocido, usa `message` como alternativa. | `data.error.reason` | Acción | | - | - | | `content_policy_violation` | La entrada o salida no superó la revisión de contenido. Modifica el prompt o las imágenes. | | `invalid_parameter` / `unsupported_option` | Parámetro o combinación no admitidos. Ajusta la solicitud. | | `invalid_media` | Imagen dañada o formato no admitido. Comprueba y convierte el archivo. | | `media_unreachable` | URL de imagen inaccesible. Comprueba el acceso público o vuelve a subirla. | | `generation_timeout` | Se agotó el tiempo de generación. Reintenta más tarde. | | `service_unavailable` | Servicio temporalmente ocupado. Reintenta más tarde. | | `delivery_failed` / `internal_error` / `unknown_error` | Error de entrega o interno. Sigue el mensaje devuelto y reintenta más tarde. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.