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-4-5-251128, doubao-seedream-4-0-250828, doubao-seedream-3-0-t2i-250415, doubao-seededit-3-0-i2i-250628. Из них 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 поддерживают ввод одного или нескольких изображений, doubao-seededit-3-0-i2i-250628 поддерживает только ввод одного изображения, doubao-seedream-3-0-t2i-250415 не поддерживает этот параметр.
size: указывает информацию о размере генерируемого изображения, поддерживает следующие два способа, которые нельзя комбинировать. Способ 1 | Указывает разрешение генерируемого изображения и описывает соотношение сторон изображения на естественном языке в prompt. Поддерживаемые предустановки различаются для каждой модели: doubao-seedream-5-0-pro-260628 поддерживает 1K/2K; doubao-seedream-5-0-260128 поддерживает 2K/3K/4K; doubao-seedream-4-5-251128 поддерживает только 2K/4K; doubao-seedream-4-0-250828 поддерживает 1K/2K/4K; doubao-seedream-3-0-t2i-250415 и doubao-seededit-3-0-i2i-250628 не поддерживают предустановки, принимают только способ 2. Способ 2 | Указывает значения пикселей ширины и высоты генерируемого изображения: по умолчанию 2048x2048, общий диапазон пикселей и соотношение сторон различаются в зависимости от модели (например, для 5.0 Pro общий диапазон пикселей [921600, 4194304], для 5.0 Lite / 4.5 нижний предел общего пикселя 3,686,400, для 4.0 нижний предел 921,600, для 3.0-t2i / seededit-3.0-i2i диапазон [512x512, 2048x2048]).
seed: случайное число, используемое для управления случайностью генерируемого контента. Диапазон значений от [-1, 2147483647]. Только doubao-seedream-3-0-t2i-250415 поддерживает этот параметр.
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.
guidance_scale: степень соответствия результата модели и подсказки, чем больше значение, тем сильнее связь. Диапазон значений [1, 10]. doubao-seedream-3-0-t2i-250415 имеет значение по умолчанию 2.5, doubao-seededit-3-0-i2i-250628 имеет значение по умолчанию 5.5, другие модели не поддерживают.
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 (сетевой поиск). Поддерживается только doubao-seedream-5-0-260128.
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-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 поддерживают ввод одного или нескольких изображений, doubao-seededit-3-0-i2i-250628 поддерживает только одно изображение.
image: загружаемое изображение для редактирования, одно или несколько.

Пример заполнения:

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

import requests

url = "https://api.acedata.cloud/flux/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 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"
}

Заключение

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

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

AI Чат

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

AI Видео

AI Аудио

Веб и данные

CAPTCHA

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

Прокси

Продвинутый

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

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

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

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

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

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

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

Заключение

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

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

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

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

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

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

​Заключение

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

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

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

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

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

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

Заключение