Інструкція з інтеграції API генерації зображень SeeDream

У цій статті буде представлено інструкцію з інтеграції API генерації зображень SeeDream, який може генерувати офіційні зображення SeeDream шляхом введення налаштовуваних параметрів.

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

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

Якщо ви ще не ввійшли в систему або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу із запрошенням зареєструватися та увійти в систему, після завершення ви автоматично повернетеся на поточну сторінку. Один 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 поточного завдання. Після завершення завдання результат генерації зображення буде надіслано у формі POST JSON на callback_url, вказаний клієнтом, який також містить поле 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. Якщо у вас виникнуть будь-які запитання, будь ласка, звертайтеся до нашої команди технічної підтримки.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Coding

Інші посібники

Інструкція з інтеграції API генерації зображень SeeDream

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

Базове використання

Завдання редагування зображень

Розділення шарів (Seedream 5.0 Pro)

Потоковий вивід

Асинхронний зворотний виклик

Обробка помилок

Приклад відповіді з помилкою

Висновок

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

​Базове використання

​Завдання редагування зображень

​Розділення шарів (Seedream 5.0 Pro)

​Потоковий вивід

​Асинхронний зворотний виклик

​Обробка помилок

​Приклад відповіді з помилкою

​Висновок

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

Базове використання

Завдання редагування зображень

Розділення шарів (Seedream 5.0 Pro)

Потоковий вивід

Асинхронний зворотний виклик

Обробка помилок

Приклад відповіді з помилкою

Висновок