Инструкция по интеграции API генерации изображений SeeDream

В этой статье будет представлена инструкция по интеграции API генерации изображений SeeDream, который позволяет генерировать официальные изображения SeeDream посредством ввода пользовательских параметров.

Процесс подачи заявки

Чтобы использовать API генерации изображений SeeDream, сначала получите ваш API Token в консоли Ace Data Cloud и сохраните его для дальнейшего использования.

Если вы ещё не вошли в систему или не зарегистрировались, вы будете автоматически перенаправлены на страницу входа с предложением зарегистрироваться и войти, после завершения вы автоматически вернётесь на текущую страницу. Один API Token позволяет вызывать все сервисы платформы, не нужно подавать отдельную заявку для каждого сервиса. При первой заявке предоставляется бесплатный лимит для бесплатного тестирования; при недостатке лимита можно пополнить общий баланс в консоли.

📘 Полная документация: API генерации изображений SeeDream →

Базовое использование

Сначала ознакомимся с базовым способом использования: введя промпт prompt, действие генерации action и размер изображения size, можно получить обработанный результат; сначала необходимо просто передать поле action со значением generate, затем также нужно ввести промпт, конкретное содержимое приведено ниже:

Можно увидеть, что здесь мы настроили Request Headers, включая:

accept: в каком формате вы хотите получить результат ответа; здесь указывается application/json, то есть формат JSON.
authorization: ключ для вызова API, после получения заявки его можно напрямую выбрать из выпадающего списка.

Также настроен Request Body, включающий:

prompt: промпт.
model: модель генерации, по умолчанию doubao-seedream-5-0-lite-260128 (SeeDream 5.0 Lite, новейшая). Поддерживаются doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828. Среди них doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) является флагманской моделью для одиночных изображений, генерирует только одиночные изображения и не поддерживает наборы изображений (sequential_image_generation), потоковый режим (stream) и веб-поиск (tools). В model необходимо передавать полную строку модели (например, doubao-seedream-5-0-lite-260128); передача сокращений вроде doubao-seedream-5.0-lite вернёт 400.
image: информация о входных изображениях, поддерживаются URL или кодирование Base64. doubao-seedream-5-0-pro-260628 поддерживает ввод одного или нескольких изображений (до 10), doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 поддерживают ввод одного или нескольких изображений.
size: указывает информацию о размере генерируемого изображения, поддерживаются следующие два способа, их нельзя смешивать. Способ 1 | Указать разрешение генерируемого изображения и описать соотношение сторон изображения на естественном языке в prompt. Поддерживаемые пресеты различаются для каждой модели: doubao-seedream-5-0-pro-260628 поддерживает 1K/1.5K/2K; doubao-seedream-5-0-lite-260128 поддерживает 2K/3K/4K; doubao-seedream-4-5-251128 поддерживает только 2K/4K; doubao-seedream-4-0-250828 поддерживает 1K/2K/4K. Способ 2 | Указать значения ширины и высоты генерируемого изображения в пикселях: по умолчанию 2048x2048, диапазон общего числа пикселей и соотношения сторон различается в зависимости от модели (например, диапазон общего числа пикселей 5.0 Pro — [921600, 4624220], нижний предел общего числа пикселей для 5.0 Lite / 4.5 составляет 3,686,400, для 4.0 — 921,600).
sequential_image_generation: набор изображений: на основе введённого вами содержимого генерируется набор связанных по содержанию изображений. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 поддерживают этот параметр, по умолчанию disabled.
stream: управляет включением режима потокового вывода. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 поддерживают этот параметр, по умолчанию — false.
response_format: указывает формат возврата генерируемого изображения. По умолчанию — url, также поддерживается b64_json.
watermark: добавлять ли водяной знак в сгенерированное изображение. По умолчанию — true.
output_format: указывает формат файла генерируемого изображения, поддерживаются jpeg (по умолчанию) и png. Поддерживается только doubao-seedream-5-0-pro-260628 и doubao-seedream-5-0-lite-260128.
tools: настраивает инструменты, вызываемые моделью, в настоящее время поддерживается web_search (веб-поиск). Поддерживается только Seedream 5.0 Lite.
optimize_prompt_options: конфигурация оптимизации промпта. 5.0 Pro поддерживает standard/fast; 5.0 Lite и 4.5 поддерживают только standard; 4.0 поддерживает standard/fast.
background: поддерживается только для редактирования одиночного изображения в 5.0 Pro. transparent требует ввода одного PNG с прозрачным каналом, и output_format обязательно должен быть png; opaque означает обычный непрозрачный фон.
layer_decomposition: поддерживается только 5.0 Pro. При значении true необходимо ввести один PNG/JPEG, можно не передавать prompt для автоматического разделения либо указать элементы с помощью естественного языка/<bbox>; size поддерживает auto/1K/1.5K/2K. Этот режим нельзя использовать вместе с наборами изображений, потоковым режимом, веб-поиском или background.
callback_url: URL, на который необходимо получить результат обратного вызова.
async: обрабатывать ли в асинхронном режиме. При значении true интерфейс немедленно возвращает task_id, нет необходимости предоставлять callback_url, затем результат получается через опрос /seedream/tasks.

После выбора можно заметить, что справа также сгенерирован соответствующий код, как показано на изображении:

Нажмите кнопку «Try», чтобы провести тестирование; как показано на изображении выше, здесь мы получили следующий результат:

{
  "success": true,
  "task_id": "80ceeed1-17d4-4eb7-82e0-18b34290f36e",
  "trace_id": "96b7fdc8-0fc8-4e2e-82a9-83c0a82f0a08",
  "data": [
    {
      "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting",
      "size": "2048x2048",
      "image_url": "https://cdn.acedata.cloud/assets/examples/seedream/db93b46e-c302-4676-8a11-63f0ba638a27-1c6f66f6b7e8.jpg"
    }
  ]
}

Результат возвращает несколько полей, описание которых приведено ниже:

success — статус задачи генерации видео в данный момент.
task_id — ID задачи генерации видео в данный момент.
trace_id — ID отслеживания генерации видео в данный момент.
data — список результатов задачи генерации изображения в данный момент.
- image_url — ссылка задачи генерации изображения в данный момент.
- prompt — промпт.
- size: пиксели сгенерированного изображения

Можно увидеть, что мы получили удовлетворительную информацию об изображении, нам нужно лишь получить сгенерированное изображение SeeDream по адресу ссылки на изображение из data в результате. Кроме того, если вы хотите сгенерировать соответствующий код интеграции, его можно напрямую скопировать и сгенерировать, например, код CURL приведён ниже:

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-5-0-lite-260128",
  "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting"
}'

Задача редактирования изображения

Если вы хотите отредактировать определённое изображение, сначала в параметр image необходимо передать ссылку на изображение, которое нужно отредактировать

model: модель, используемая для данной задачи редактирования изображения; doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 поддерживают ввод изображений.
image: загрузите изображение, которое необходимо отредактировать, одно или несколько

Пример заполнения приведён ниже:

Соответствующий код:

import requests

url = "https://api.acedata.cloud/seedream/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedream-4-0-250828",
  "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
  "image": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"],
  "size": "2K",
  "watermark": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Нажав «Запустить», можно обнаружить, что результат будет получен немедленно, как показано ниже:

{
  "success": true,
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
  "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
  "data": [
    {
      "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

Можно увидеть, что сгенерированный эффект является результатом редактирования исходного изображения, результат аналогичен приведённому выше.

Разделение на слои (Seedream 5.0 Pro)

Разделение на слои разделяет одно входное изображение на 1 фоновое изображение и до 16 независимо редактируемых прозрачных PNG-слоёв. Следующий запрос позволяет модели автоматически распознать основные элементы; если необходимо указать элементы, можно добавить prompt, также можно использовать нормализованные координаты <bbox> в промпте.

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "model": "doubao-seedream-5-0-pro-260628",
  "image": "https://example.com/poster.png",
  "layer_decomposition": true,
  "size": "2K",
  "watermark": false
}'

Возвращаемые data упорядочены по z_index снизу вверх. У фонового изображения z_index равен 0; слои также содержат name, description и bounding_box.absolute/normalized. При сборке с использованием абсолютных координат масштабируйте слой до [right-left, bottom-top], поместите его в [left, top], затем накладывайте в порядке возрастания z_index. Если генерация любого слоя завершится с ошибкой, всё разделение завершится с ошибкой.

Потоковый вывод

Когда для Lite/4.x установлено stream: true, используйте в заголовке запроса accept: application/x-ndjson. Интерфейс построчно возвращает image_generation.partial_succeeded или image_generation.partial_failed, а в конце возвращает единственное событие image_generation.completed и итоговый usage; только событие завершения инициирует одно списание средств. Потоковый режим нельзя использовать вместе с async или callback_url.

Асинхронный обратный вызов

Поскольку время генерации SeeDream Images Generation API относительно длительное, примерно 1–2 минуты, если API долго не отвечает, HTTP-запрос будет постоянно поддерживать соединение, что приводит к дополнительному потреблению системных ресурсов, поэтому этот API также предоставляет поддержку асинхронных обратных вызовов. Общий процесс таков: когда клиент инициирует запрос, он дополнительно указывает поле callback_url; после того как клиент инициирует API-запрос, API немедленно вернёт результат, содержащий информацию поля task_id, представляющего ID текущей задачи. После завершения задачи результат генерации изображения будет отправлен в указанное клиентом callback_url в виде POST JSON, который также включает поле task_id, таким образом результаты задачи можно связать по ID. Если у вас нет общедоступного адреса для обратного вызова, вы также можете не указывать callback_url, а установить в запросе значение поля async как true. В этом случае интерфейс также немедленно вернёт task_id, но не отправит результат, вам необходимо передать этот task_id для вызова интерфейса /seedream/tasks, чтобы опрашивать статус задачи и получить окончательный результат. Ниже мы рассмотрим конкретный способ работы на примере. Нажав «Запустить», можно обнаружить, что результат будет получен немедленно, как показано ниже:

{
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}

Содержимое приведено ниже:

{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "Сохраните позу модели и струящуюся форму жидкого наряда без изменений. Измените материал одежды с серебряного металла на полностью прозрачную воду (или стекло). Сквозь поток жидкости видны детали кожи модели. Эффект света и тени смещается от отражения к преломлению.",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

Можно увидеть, что в результате есть поле task_id, остальные поля аналогичны приведённым выше; с помощью этого поля можно реализовать связь задач.

Обработка ошибок

При вызове API, если возникает ошибка, API возвращает соответствующий код ошибки и информацию. Например:

400 token_mismatched：Неверный запрос, возможно, из-за отсутствующих или недопустимых параметров.
400 api_not_implemented：Неверный запрос, возможно, из-за отсутствующих или недопустимых параметров.
401 invalid_token：Не авторизован, недопустимый или отсутствующий токен авторизации.
429 too_many_requests：Слишком много запросов, вы превысили лимит частоты запросов.
500 api_error：Внутренняя ошибка сервера, на сервере что-то пошло не так.

Пример ответа с ошибкой

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Заключение

Из этого документа вы уже узнали, как использовать SeeDream Images Generation API для генерации изображений путём ввода подсказок. Надеемся, этот документ поможет вам лучше интегрировать и использовать данный API. Если у вас возникнут какие-либо вопросы, пожалуйста, свяжитесь с нашей командой технической поддержки в любое время.

Начало работы

AI Чат

AI Изображение

AI Видео

AI Аудио

Веб и данные

CAPTCHA

Идентичность

Coding

Другие руководства

Инструкция по интеграции API генерации изображений SeeDream

Процесс подачи заявки

Базовое использование

Задача редактирования изображения

Разделение на слои (Seedream 5.0 Pro)

Потоковый вывод

Асинхронный обратный вызов

Обработка ошибок

Пример ответа с ошибкой

Заключение

​Процесс подачи заявки

​Базовое использование

​Задача редактирования изображения

​Разделение на слои (Seedream 5.0 Pro)

​Потоковый вывод

​Асинхронный обратный вызов

​Обработка ошибок

​Пример ответа с ошибкой

​Заключение

Процесс подачи заявки

Базовое использование

Задача редактирования изображения

Разделение на слои (Seedream 5.0 Pro)

Потоковый вывод

Асинхронный обратный вызов

Обработка ошибок

Пример ответа с ошибкой

Заключение