Перейти к основному содержанию
POST
Image Editing / Multi-image Fusion / Batch Sequence
Один эндпоинт, несколько режимов: у Seedream нет отдельного эндпоинта /v1/images/edits. Редактирование, слияние нескольких изображений и пакетная последовательность выполняются через POST /v1/images/generations. Playground на этой странице обращается к тому же эндпоинту, что и Текст-в-изображение — единственное различие состоит в параметрах image и sequential_image_generation в теле запроса.
Режимы:
  • Редактирование одного изображения — image: ["url"] + sequential_image_generation: "disabled"
  • Слияние нескольких изображений — image: ["url1", "url2", ...] + disabled
  • Пакетная последовательность — sequential_image_generation: "auto" + sequential_image_generation_options.max_images: N
  • Изображение-в-последовательность — объединяет оба: массив image + auto + max_images
🖥️ Ограничение Browser Playground (только режим b64_json)В режиме response_format: "url" по умолчанию Playground работает нормально (в ответе просто временная ссылка BytePlus TOS). Если вы переключитесь на response_format: "b64_json", ответ будет содержать base64-строку размером в несколько МБ, и браузерный Playground может показать 请求时发生错误: unable to complete request — запрос на самом деле выполнен успешно; браузер просто не может отобразить такую длинную base64-строку.Рекомендуемый рабочий процесс:
  • Просто хотите посмотреть изображение? Оставьте режим url по умолчанию — Playground возвращает ссылку напрямую (не забудьте скачать ее в свое хранилище в течение 24 часов).
  • Нужен b64_json? Скопируйте пример кода ниже и запустите его локально — код автоматически декодирует и сохранит изображение в файл.
⚠️ Ключевые отличия от редактирования OpenAI gpt-image-2
  • Нет загрузок multipart/form-data — сначала загрузите свои изображения в OSS или на публичный хост изображений, а затем передайте URL в массиве image
  • image — это массив URL, а не повторяющееся поле image[] (в отличие от формата multipart/form-data OpenAI)
  • Нет поля mask — Seedream не поддерживает inpainting по маске alpha-канала; все изображение переписывается по prompt
  • Жесткий лимит на общее количество: входные ссылки + выходные изображения ≤ 15
📎 Порядок нескольких изображений имеет значениеПорядок URL в массиве image становится тем, что в prompt обозначается как «изображение 1 / изображение 2 / изображение 3». Явно указывайте порядок:
Замените одежду на изображении 1 на наряд с изображения 2, сохранив освещение с изображения 3.
Лучше всего работают prompt на английском языке (модель в основном обучена на English), но китайский тоже поддерживается, если формулировка однозначна.

Примеры кода

О extra_body (важно — не подумайте, что это дополнительный уровень вложенности)image, sequential_image_generation и watermark не являются стандартными параметрами images.generate() в OpenAI SDK, поэтому в Python SDK вы обязаны поместить их внутрь extra_body, чтобы передать их.Но extra_body — это всего лишь контейнер параметров SDK: его поля разворачиваются и объединяются с верхним уровнем тела запроса, на том же уровне, что и model и prompt. Фактически отправляемый JSON идентичен примеру cURL ниже (image находится на верхнем уровне); в запросе нет реальной вложенности "extra_body": {...}.Если вы не используете OpenAI SDK, а формируете JSON напрямую (requests / fetch / и т. д.), не записывайте extra_body — просто разместите image и остальные поля на том же уровне, что и model.

Python (OpenAI SDK · редактирование одного изображения)

Python (OpenAI SDK · объединение нескольких изображений)

Python (OpenAI SDK · пакетная последовательность)

cURL (объединение нескольких изображений)

Node.js (fetch · пакетная последовательность)

Передавайте эталонные изображения в виде общедоступных URL, а не в формате base64 (особо отмечается с 2026-09-11)Если элементы массива image являются URL, тело запроса занимает всего несколько КБ, а BytePlus загружает ваши изображения напрямую из своего региона в Сингапуре (проверено: IP-адрес, с которого выполняется загрузка, принадлежит BytePlus, а шлюз APIYI не участвует). Если элементы являются строками data:image/...;base64,..., несколько эталонных изображений высокого разрешения легко увеличивают размер тела до 20–30 МБ. Сначала это тело необходимо полностью загрузить на шлюз APIYI, а затем переслать в Сингапур. Если трансграничная загрузка выполняется медленно, превышается лимит провайдера на входящие запросы — 600 секунд на чтение тела запроса, — и возникает 400 Error when parsing request. Весь запрос завершается с ошибкой и не переключается в режим URL, поскольку шлюз не преобразует base64 в ссылку для загрузки.
  • ✅ Разместите изображения в собственном объектном хранилище или на хостинге изображений и передавайте общедоступные URL без аутентификации, доступные через обычный GET; размер каждого изображения не должен превышать примерно 10 МБ
  • ⚠️ Если без base64 не обойтись, сначала сожмите изображения: длинная сторона — не более 2048 пикселей, перекодируйте с качеством 0.9 и ограничьте общий размер нескольких изображений 6 МБ
  • ❌ Не отправляйте тела в формате base64 размером более 20 МБ и не передавайте адреса из частных сетей или ссылки, требующие входа в систему (BytePlus возвращает InvalidParameter: Error while downloading, если загрузка не выполняется)

Справочник параметров

Ограничения по количеству в режимах Multi-image и последовательности

Итеративная доработка: передавайте URL предыдущего результата как следующий вход с новой инструкцией по редактированию, чтобы последовательно уточнять результат. Каждый раунд тарифицируется по каждому изображению — следите за накопительной стоимостью.

5.0 Flash: разделение на слои (прозрачные слои)

seedream-5-0-flash-260915 может разделить готовое изображение на базовый фон и отдельные элементы на прозрачных слоях, что удобно для изменения компоновки, смены фона и повторного использования ассетов. Запрос прозрачного фона в prompt не создает альфа-канал, поэтому используйте эту функцию для ассетов на прозрачном фоне.
Результаты тестирования (2026-09-24, UTC+8):
  • С 1 референсным изображением массив data вернул 12 изображений: первое — это базовый фон с удаленными и заполненными элементами (имя файла оканчивается на _base.png, RGB); остальные 11 — прозрачные слои RGBA (от _layer_1.png), каждый из которых содержит один элемент, обрезанный под собственный размер
  • Около 78 секунд при разрешении 1K; аналогичный запрос при 2K ничего не вернул через 15 минут, но тарификация всё равно составила $0.216 за 12 изображений. Используйте 1K и установите таймаут клиента на 300 секунд или более
  • Разделение на слои может завершиться ошибкой: то же изображение однажды вернуло ошибку 400 примерно через 60 секунд (the image content could not be processed for layer decomposition). При ошибках тарификация не начисляется, поэтому просто повторите попытку
  • Области, удаленные с фона, дорисовываются моделью, поэтому проверьте их перед коммерческим использованием
Тарификация разделения на слои выполняется за каждое выходное изображение: каждое возвращенное изображение стоит $0.018. Один запрос вернул 12 изображений и стоил $0.216 (значение usage.generated_images составило 12). Количество слоев зависит от содержимого изображения и не может быть задано заранее, при этом одно и то же изображение каждый раз может разделяться по-разному (одно изображение дало сначала 12, а затем 14 изображений с тарификацией $0.216 и $0.252), поэтому закладывайте в бюджет дюжину или более.

Формат ответа

⚠️ Длина массива data отражает фактическое количество вывода
  • sequential_image_generation: "disabled" → массив из одного элемента data
  • sequential_image_generation: "auto" + max_images: N → обычно N элементов (иногда меньше, если prompt возвращает меньше)
  • Тарификация производится по usage.generated_images, а не по max_images
Запросы на редактирование тарифицируются так же, как text-to-image, — по одному выходному изображению. Входные reference image не тарифицируются отдельно.

Авторизации

Authorization
string
header
обязательно

API Key obtained from APIYI Console

Тело

application/json
model
enum<string>
по умолчанию:seedream-5-0-260128
обязательно

Model ID

Доступные опции:
seedream-5-0-260128,
seedream-5-0-lite-260128,
seedream-4-5-251128,
seedream-4-0-250828,
seedream-5-0-pro-260628,
seedream-5-0-flash-260915
prompt
string
обязательно

Editing / fusion / sequence instruction. For multi-image scenarios, refer to images explicitly as 'image 1 / image 2'

Пример:

"Replace the clothing in image 1 with the outfit from image 2."

image
string<uri>[]

Reference image URL array. Up to 10 images (per official 4.5 / 5.0-pro / 5.0-flash docs; an 11th returns 400 on 5.0-flash in our tests). Note: input + output count ≤ 15

Maximum array length: 10
Пример:
sequential_image_generation
enum<string>
по умолчанию:disabled

Generation mode switch. disabled = single output (default); auto = batch sequence, paired with max_images. Not accepted by 5.0-pro / 5.0-flash — any value returns 400

Доступные опции:
disabled,
auto
sequential_image_generation_options
object

Batch sequence options. Effective only when sequential_image_generation=auto

size
string
по умолчанию:2K

Output size. Preset tiers (vary by version):

  • 1K (4.0 / 5.0-pro / 5.0-flash) / 1.5K (5.0-flash only) / 2K (all) / 3K (5.0 only) / 4K (4.5, 4.0)

Or exact pixel size WxH, total pixels ∈ [1280×720, 4096×4096], aspect ratio ∈ [1/16, 16]

Пример:

"2K"

response_format
enum<string>
по умолчанию:url
Доступные опции:
url,
b64_json
output_format
enum<string>
по умолчанию:jpeg

Output format. The 5.0 series supports png/jpeg; 4.5/4.0 only jpeg

Доступные опции:
png,
jpeg
watermark
boolean
по умолчанию:false
layer_decomposition
boolean
по умолчанию:false

5.0-flash only: pass 1 reference image to get a background base plus several RGBA transparent layers. Billed per output image (12 in one test); use size 1K and a timeout of 300 seconds or more

stream
boolean
по умолчанию:false

Streaming output. Recommended for long prompts and multi-image sequence scenarios. Not accepted by 5.0-pro / 5.0-flash (returns 400)

Ответ

Edited image generated successfully

model
string
Пример:

"seedream-5-0-260128"

created
integer
Пример:

1768518000

data
object[]

Result array. disabled mode returns 1 element; auto mode typically returns max_images elements (may be fewer)

usage
object

Billed by generated_images actual count, NOT by max_images