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

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

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

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

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

📘 Повна документація: API генерації зображень SeeDream →

Основне використання

Спочатку розгляньте основний спосіб використання, а саме введення підказки 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 за посиланням 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-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. Якщо будь-який шар не згенеровано, вся розділка зазнає невдачі.

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

При налаштуванні Lite/4.x stream: true, заголовок запиту використовує 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 запит повертає результат, що містить поле 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. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

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

Проксі

Advanced

Coding

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

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

Основне використання

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

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

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

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

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

Приклад відповіді на помилку

Висновок

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

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

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

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

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

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

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

​Приклад відповіді на помилку

​Висновок

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

Основне використання

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

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

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

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

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

Приклад відповіді на помилку

Висновок