Інструкція з інтеграції 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-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 штук, з 2-го зображення починається оплата за зображення), 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 за посиланням 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-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"
        }
    ]
}

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

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

Оскільки час генерації 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"
}

Зміст виглядає так:

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

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

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

Проксі

Advanced

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

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

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

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

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

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

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

Висновок

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

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

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

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

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

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

​Висновок

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

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

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

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

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

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

Висновок