SeeDream Images Generation API интеграция

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

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

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

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

📘 Полная документация: SeeDream Images Generation API →

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

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

Как видно, мы настроили заголовки запроса, включая:

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

Также настроено тело запроса, включая:

prompt: подсказка.
model: модель генерации, по умолчанию doubao-seedream-5-0-260128 (SeeDream 5.0 Lite, последняя версия). Поддерживаются doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-260128 (также принимается официальное сокращение 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-260128), передача сокращений, таких как doubao-seedream-5.0-lite, приведет к ошибке 400.
image: информация о входном изображении, поддерживает URL или кодировку Base64. doubao-seedream-5-0-pro-260628 поддерживает ввод одного или нескольких изображений (много изображений от 2 до 10, начиная со второго изображения, оплата по количеству), doubao-seedream-5-0-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-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-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 поддерживают этот параметр, по умолчанию disabled.
stream: управляет тем, включен ли режим потокового вывода. doubao-seedream-5-0-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-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 можно опрашивать для получения результатов.

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

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

{
  "success": true,
  "task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
  "trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
  "data": [
    {
      "prompt": "Фотореалистичный студийный снимок парфюмерной бутылки из матового стекла на мокром черном сланце, одно основное освещение софтбокса, капли воды, темный мрачный фон, 85 мм макро.",
      "size": "2048x2048",
      "image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
    }
  ]
}

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

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

Можно увидеть, что мы получили удовлетворительную информацию о изображении, нам нужно просто получить сгенерированное изображение SeeDream по ссылке image_url в результате. Кроме того, если вы хотите сгенерировать соответствующий код для интеграции, вы можете просто скопировать его, например, код 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-260128",
  "prompt": "Фотореалистичный студийный снимок парфюмерной бутылки из матового стекла на мокром черном сланце, одно основное освещение софтбокса, капли воды, темный мрачный фон, 85 мм макро."
}'

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

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

model: модель, используемая для редактирования изображения, doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-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": "Сохраните позу модели и форму текучего материала одежды без изменений. Измените материал одежды с серебряного металла на полностью прозрачную воду (или стекло). Через текучесть жидкости видны детали кожи модели. Эффект света и тени смещается от отражения к преломлению.",
  "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": "Сохраните позу модели и форму текучего материала одежды без изменений. Измените материал одежды с серебряного металла на полностью прозрачную воду (или стекло). Через текучесть жидкости видны детали кожи модели. Эффект света и тени смещается от отражения к преломлению.",
      "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. Если генерация любого слоя не удалась, вся операция разделения будет неудачной.

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

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

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

Поскольку время генерации API SeeDream Images Generation относительно долгое, около 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"
}

Содержимое следующее:

```json
{
    "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": "не удалось получить"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Заключение

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

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

AI Чат

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

AI Видео

AI Аудио

Веб и данные

CAPTCHA

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

Прокси

Продвинутый

Coding

SeeDream Images Generation API интеграция

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

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

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

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

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

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

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

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

Заключение

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

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

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

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

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

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

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

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

​Заключение

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

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

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

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

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

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

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

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

Заключение