> ## 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. # Генерация изображений Seedream 5.5 > Генерация по тексту или максимум 10 референсам, прозрачный фон, настраиваемое разложение на слои и OCR через асинхронный API. ```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" } ] } ``` Отправьте запрос в `POST /v1/images/generations`, сохраните `data[0].task_id` и проверяйте результат через `GET /v1/tasks/{task_id}`. ## Режимы | Режим | Включение | Входные изображения | Промпт | | - | - | - | - | | Генерация изображений | По умолчанию | 0–10 | Обязателен | | Разложение на слои | `layer_decomposition: true` | Ровно 1 | Необязателен | ## Аутентификация **Authorization** `string` *required* Используйте `Authorization: Bearer `, где `` — ваш APIMart API Key. ## Параметры запроса **model** `string` *required* Укажите `seedream-5-5`. **prompt** `string` Обязателен при генерации по тексту или изображению. При разложении необязателен: модель автоматически определяет объекты, текст и фон. Можно описать элементы для разделения. **image\_urls** `string[]` До 10 референсов при генерации; ровно 1 изображение при разложении. Поддерживаются публичные URL изображений и Base64 Data URI. Локальные файлы загрузите через [API загрузки изображений](https://docs.apimart.ai/ru/api-reference/uploads/images.md) и передайте полученный `url`. Используйте общедоступные `http(s)` URL или `data:image/;base64,…`. Название формата в Data URI должно быть в нижнем регистре. * Поддерживаются JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC и HEIF. AVIF и JP2 не поддерживаются. * Не более **30 MiB (31,457,280 байт)** и **36 миллионов пикселей суммарно** на изображение. Проверяется ширина × высота, а не предел 6000 пикселей для каждой стороны. * Превышение размера или площади возвращает синхронный HTTP 400. Для AVIF и JP2 задача может создаться до отказа upstream; при неудаче средства возвращаются. Сначала преобразуйте формат. Endpoint загрузки изображений имеет собственные ограничения форматов. Для формата, поддерживаемого моделью, но не загрузчиком, используйте публичный URL или Data URI. **size** `string` Генерация: по умолчанию `2K`, доступны уровень разрешения, пропорции и точные размеры в пикселях. Разложение: по умолчанию `auto`, только `1K` / `1.5K` / `2K` / `auto`. Для генерации `size: "auto"` означает `2K`. Соотношение сторон без `resolution` также использует `2K`. При точных размерах не передавайте `resolution`; ширина и высота должны быть положительными целыми числами. **resolution** `string` При генерации используйте `1K` / `1.5K` / `2K` вместе с пропорциями в `size`. При разложении это псевдоним `size`, предоставляемый платформой: приоритет у `size`, при его отсутствии используется `resolution`, без обоих — `auto`. Допустимы `1K` / `1.5K` / `2K` / `auto`; пропорции и пиксельные размеры синхронно отклоняются с HTTP 400. `3K` / `4K` не поддерживаются. **background** `string` Генерация: `auto` (по умолчанию), `transparent` или `opaque`. Прозрачный фон доступен при генерации по тексту и изображению. Он требует PNG и несовместим с `output_format: "jpeg"`. При разложении полностью исключите поле, включая `auto`. **output\_format** `string` (default: png) `png` (по умолчанию) или `jpeg`. При разложении влияет только на базовое изображение; выделенные слои всегда имеют формат прозрачного PNG. **n** `integer` Только `1`. Обычная генерация выдаёт одно изображение на запрос. Количество при разложении задаётся через `layer_decomposition_options.max_images`. **watermark** `boolean` (default: false) Необязательный флаг добавления водяного знака. **optimize\_prompt\_options** `object` Поддерживается только `{"mode":"standard"}`. При отсутствии параметра поставщик всё равно включает `standard` по умолчанию; отключить оптимизацию в Seedream 5.5 нельзя. Поставщик отклоняет `disabled` / `none` / `off` с HTTP 400 и `must be one of: standard`. Платформа сразу отклоняет `fast` с HTTP 400. **layer\_decomposition** `boolean` `true` разделяет вход на базовое изображение и прозрачные слои. Требуется ровно одно изображение без поля `background`. `output_format` управляет только базой. **layer\_decomposition\_options** `object` Допустимо только при `layer_decomposition: true`, иначе HTTP 400. **Параметры запроса** **max\_images** `integer` (default: 30) Целое число от `2` до `100`, по умолчанию `30`. Верхний предел общего числа выходных изображений, включая базу, а не гарантированное количество. **text\_recognition** `boolean` (default: false) Необязательное логическое значение. `true` запрашивает OCR со стилями для текстовых слоёв. `text_recognition` может присутствовать только для распознаваемого обычного текста. При включённом OCR передача `prompt` может привести к отсутствию результатов распознавания. Если OCR важнее, попробуйте не указывать промпт разложения. Результат не гарантирован: поля остаются необязательными. ## Форматы размера | Формат | Пример | Правила | | - | - | - | | Уровень | `"size": "2K"` | `1K` / `1.5K` / `2K`; по умолчанию `2K`. Пропорции выбираются моделью по промпту. | | Пропорции + уровень | `"size": "16:9", "resolution": "1.5K"` | Только генерация. Пропорции ниже; также допустимо `16x9`. | | Точные пиксели | `"size": "2048x1152"` | Только генерация. Всего пикселей: 921 600–4 624 220; ширина/высота: 1/16–16. | Пропорции: `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9`, `2:1`, `1:2`. Ограничения относятся к площади в пикселях и пропорциям. Разложение принимает только уровни или `auto`, без пропорций и точных пиксельных размеров. ### Размеры результатов разложения * Приоритет: `size` → `resolution` → `auto`. `resolution` — псевдоним платформы; поставщику передаётся только `size`. При `size: "1K"` и `resolution: "2K"` действует `1K`; только `resolution: "1.5K"` задаёт `1.5K`. * При `1K` / `1.5K` / `2K` база и каждый слой выводятся на выбранном уровне, каждый со своими исходными пропорциями. В одном замере база `1K` имела размер `840×1248`, каждый слой — также около 1,05 млн пикселей. Это примеры, а не фиксированные размеры. * `auto` использует исходные размеры входа: изображения меньше `1K` увеличиваются до `1K`, больше `2K` уменьшаются до `2K`. ## Примеры запросов ### Редактирование и объединение референсов ```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" }' ``` ### Разложение на слои и OCR Запрос выдаёт максимум 10 изображений, включая базу. `prompt` необязателен; `background` не передаётся. Замените URL на доступное изображение. ```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" }' ``` ## Проверка задачи Используйте [API статуса задачи](https://docs.apimart.ai/ru/api-reference/tasks/status.md) каждые 3 секунды в первые 30 секунд, затем каждые 5–10 секунд. Разложение может занять несколько минут; сервер ожидает не более 13 минут. Сохраните `task_id` и проверяйте до конечного состояния, не отправляя генерацию повторно. ```bash theme={null} curl --request GET \ --url 'https://api.apimart.ai/v1/tasks/task_example_seedream55' \ --header 'Authorization: Bearer ' ``` В `data.status` значения `pending` / `processing` означают обработку, `completed` — успех. При `failed` причина находится в `data.error.message`, средства возвращаются автоматически. URL результатов: `data.result.images[].url[]`. > [!WARNING] > > Изображения результатов хранятся **3 дня**; скачайте их своевременно. Записи задач также хранятся только 3 дня, после чего запрос по `task_id` недоступен. > > `data.result.images[].expires_at` сейчас возвращает Unix-время в секундах, равное времени завершения + 24 часа. Это консервативная отметка, предшествующая фактическому удалению. Не используйте её для расчёта реального срока хранения или обратного отсчёта до удаления. ## Результаты слоёв и OCR Пример показывает структуру, а не запись реального запуска. Размеры, координаты и текст приведены для иллюстрации. Метаданные могут отсутствовать. ```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 } } ] } ] } } ] } ] } } } ``` В каждом `data.result.images[]` массивы `url`, `sizes`, `output_formats`, `backgrounds` и `layers` соответствуют друг другу по индексу. Массивы метаданных могут отсутствовать, если их длина отличается от `url`. | Поле | Описание | | - | - | | `url[]` | URL изображений. В режиме слоёв индекс 0 — база, далее идут слои. Скачайте и сохраните файлы своевременно. | | `sizes[]` / `output_formats[]` | Фактические размеры и формат каждого изображения. | | `backgrounds[]` | Фактический фон: `opaque` / `transparent`. При `background: "auto"` используйте это значение. | | `expires_at` | Сейчас это Unix timestamp: время завершения + 24 часа (86400 секунд). Консервативная отметка, а не фактическое время удаления изображения; не используйте её для обратного отсчёта до удаления. | | `layer_decomposition` | Является ли результат разложением на слои. | | `layers[i].z_index` | Порядок наложения: база имеет индекс 0, сборка по возрастанию. | | `layers[i].background` | База: `opaque`; выделенные слои: `transparent`. | | `layers[i].name` / `description` | Необязательные название и описание слоя. | | `layers[i].bounding_box` | `absolute`: `[left, top, right, bottom]` в пикселях базового изображения. `normalized`: та же рамка в диапазоне 0–1000. У базы отсутствует. | | `layers[i].text_recognition` | Может появиться при включённом OCR и распознанном обычном тексте; отсутствует для декоративных надписей, рукописного текста и нетекстовых слоёв. | Абсолютные координаты: `x=left`, `y=top`, `w=right-left`, `h=bottom-top`. Для холста `W × H` преобразуйте нормализованные координаты так: ```text theme={null} x = left / 1000 * W y = top / 1000 * H w = (right - left) / 1000 * W h = (bottom - top) / 1000 * H ``` Каждый слой масштабируется отдельно на выбранном уровне, поэтому размер файла может отличаться от `bounding_box`. При сборке приведите слой к `w × h` и разместите в `(x, y)`. Пиксели файла слоя нельзя напрямую считать координатами базы. ### Поля распознавания текста `text_recognition` следует структуре OCR вышестоящей модели. Платформа передаёт `text`, `lines`, `runs`, `style` и другие поля без изменений. | Поле | Описание | | - | - | | `text` | Полный текст слоя, строки разделены `\n`. | | `lines[].bounding_box` | Рамка строки в координатах базового изображения. | | `lines[].runs[]` | Фрагменты строки с разными стилями, каждый содержит `text` и `style`. | | `runs[].style.similar_font_family` | Наиболее близкое семейство шрифта либо `unknown`. | | `runs[].style.foreground_color` | Цвет текста в формате `#RRGGBB`. | | `runs[].style.bold` / `italic` / `underline` / `strikethrough` / `shadow` / `translucent` | Логические признаки стиля, оценённые моделью; возможны неточности. | OCR и сведения о шрифте помогают отображать, копировать и редактировать текст, но могут отличаться от оригинала. Изображения слоёв доступны и без OCR. ## Оплата Выходные изображения и входные референсы оплачиваются отдельно. **Каждый референс платный, включая первый** и единственное входное изображение для разложения. * Каждая выходная картинка тарифицируется по фактической площади: до **2,610,000** пикселей включительно — низкий тариф, выше — высокий. `1K` / `1.5K` соответствуют низкому, `2K` — высокому. Для точных размеров используется ширина × высота. * При генерации резервируется стоимость выбранного выходного тарифа плюс число референсов × цена входного изображения. Без `size` или с `auto` резервируется `2K`. * Для разложения резервируется `max_images` × выходной тариф **плюс стоимость одного входного изображения**. По умолчанию `max_images` равен 30, включая основу; фактических выходов может быть меньше. * Для разложения действует `size`, иначе `resolution`: `1K` / `1.5K` резервируют по низкому тарифу, `2K` / `auto` — по высокому. Если оба поля отсутствуют, применяется высокий резерв для `auto`. * Итог зависит от фактического количества выходов, площади каждого и количества входов; разница возвращается или доплачивается. Основа и каждый слой считаются отдельными изображениями. Нельзя применять запрошенный тариф ко всем выходам без учёта их размеров. При неудаче возвращается вся сумма. См. [цены моделей](https://apimart.ai/pricing). ## Частые ошибки параметров Здесь приведены проверки платформы и поставщика. При ошибке отправки читайте `error.message`, при ошибке асинхронной задачи — `data.error.message`. | Фрагмент ошибки | Решение | | - | - | | `does not support optimize_prompt_options.mode=fast` | Платформа синхронно возвращает HTTP 400. Допустим только `standard`; без параметра оптимизация тоже включена. | | `must be one of: standard` | HTTP 400 поставщика: `disabled` / `none` / `off` не поддерживаются; отключить оптимизацию нельзя. | | `only supports background auto, transparent or opaque` | Используйте `auto`, `transparent` или `opaque`. | | `cannot combine background=transparent with output_format=jpeg` | Для прозрачности используйте `output_format: "png"`. | | `does not accept background when layer_decomposition=true` | При разложении удалите `background`, включая `auto`. | | `layer_decomposition_options requires layer_decomposition=true` | Передавайте объект только в режиме разложения. | | `layer_decomposition_options.max_images must be within [2, 100]` | `max_images`: целое число 2–100, включая базу. | | `invalid layer_decomposition_options` | `max_images` должен быть целым числом, не строкой или дробью; `text_recognition` — логическим значением. | | `with layer_decomposition=true requires exactly 1 input image` | Для разложения передайте ровно одно изображение. | | `only supports size 1K, 1.5K, 2K or auto` | При разложении сначала используется `size`, иначе `resolution`. Только `1K` / `1.5K` / `2K` / `auto`; пропорции и пиксельные размеры синхронно дают HTTP 400. | | `` `n` must be 1 `` | Укажите `n: 1`; пакетная генерация не поддерживается. | | `does not support stream` / `does not support tools` | Удалите `sequential_image_generation`, `stream` и `tools`. | | `supports up to 10 reference images` | Передайте максимум 10 референсов. | | `reference image too large for seedream-5-5` | На референс допускается не более 30 MiB и 36 миллионов пикселей. Сожмите или уменьшите изображение. | | `does not support size` / `requires total pixels` / `requires aspect ratio` | Проверьте площадь, соотношение сторон и запись размера. 3K / 4K не поддерживаются. | | `` `prompt` parameter is required `` | Для генерации необходим промпт. Пропустить его можно только при разложении. | ## Причины неудачных задач При `data.status = failed` читайте `data.error.message` и `data.error.reason`. Оплата возвращается автоматически. Если `reason` отсутствует или неизвестен, используйте `message`. | `data.error.reason` | Действие | | - | - | | `content_policy_violation` | Вход или результат не прошёл проверку контента. Измените промпт или изображения. | | `invalid_parameter` / `unsupported_option` | Неподдерживаемый параметр или сочетание. Исправьте запрос. | | `invalid_media` | Повреждённое изображение или неподдерживаемый формат. Проверьте и преобразуйте файл. | | `media_unreachable` | URL изображения недоступен. Проверьте публичный доступ или загрузите заново. | | `generation_timeout` | Превышено время генерации. Повторите позже. | | `service_unavailable` | Сервис временно занят. Повторите позже. | | `delivery_failed` / `internal_error` / `unknown_error` | Ошибка доставки или внутренняя ошибка платформы. Следуйте сообщению и повторите позже. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.