> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Інструкція з інтеграції API генерації зображень SeeDream
> ByteDance Seedream Image Generation API guide - Ace Data Cloud
У цьому документі буде представлено інструкцію з інтеграції API генерації зображень SeeDream, яка дозволяє генерувати зображення від SeeDream за допомогою введення користувацьких параметрів.
## Процес подачі заявки
Щоб використовувати API генерації зображень SeeDream, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications), щоб отримати ваш API Token, зберігши його для подальшого використання.
Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід, після чого ви будете автоматично повернені на цю сторінку.
**Один API Token дозволяє викликати всі послуги платформи, не потрібно окремо подавати заявку на кожну послугу.** Перший запит на отримання токена надає безкоштовний ліміт, щоб ви могли безкоштовно протестувати; якщо ліміт вичерпано, ви можете поповнити загальний баланс в [консолі](https://platform.acedata.cloud/console/coin).
> 📘 Повна документація: [API генерації зображень SeeDream →](https://platform.acedata.cloud/documents/seedream-images)
## Основне використання
Спочатку розглянемо основний спосіб використання, а саме введення підказки `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` можна опитувати для отримання результатів.
Після вибору ви можете помітити, що праворуч також згенеровано відповідний код, як показано на малюнку:
Натисніть кнопку «Спробувати», щоб провести тестування, як показано на малюнку, тут ми отримали наступний результат:
```json theme={null}
{
"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 виглядає так:
```shell theme={null}
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: завантажте зображення, яке потрібно редагувати, одне або кілька.
Приклад заповнення:
Відповідний код:
```python theme={null}
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)
```
Клікнувши "Запустити", ви можете побачити, що відразу отримаєте результат, як показано нижче:
```json theme={null}
{
"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"
}
```
Зміст виглядає так:
```json theme={null}
{
"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`: Внутрішня помилка сервера, щось пішло не так на сервері.
### Приклад відповіді з помилкою
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Висновок
```
За допомогою цього документа ви вже дізналися, як використовувати API генерації зображень SeeDream для створення зображень за допомогою введення підказок. Сподіваємося, що цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, не соромтеся звертатися до нашої команди технічної підтримки.
```