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

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

Щоб використовувати API, спочатку потрібно перейти на сторінку API генерації зображень SeeDream для подачі заявки на відповідну послугу. Після переходу на сторінку натисніть кнопку «Acquire», як показано на малюнку: Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід. Після входу або реєстрації ви будете автоматично повернені на поточну сторінку. При першій подачі заявки вам буде надано безкоштовний ліміт, який дозволяє безкоштовно використовувати цей API.

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

Спочатку потрібно ознайомитися з основним способом використання, а саме: введенням підказки prompt, дії action, розміру зображення size, щоб отримати оброблений результат. Спочатку потрібно просто передати поле action, значення якого буде generate, потім потрібно ввести підказку, конкретний зміст якої наведено нижче:

Ми можемо бачити, що тут ми налаштували заголовки запиту, включаючи:
  • accept: формат відповіді, який ви хочете отримати, тут вказано application/json, тобто формат JSON.
  • authorization: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку.
Також налаштовано тіло запиту, яке включає:
  • prompt: підказка.
  • model: модель генерації, за замовчуванням doubao-seedream-4.0.
  • image: інформація про вхідне зображення, підтримує URL або кодування Base64. Серед них, doubao-seedream-4.5, doubao-seedream-4.0 підтримують одноразове або багаторазове введення, doubao-seededit-3.0-i2i підтримує лише одноразове введення, doubao-seededit-3.0-t2i не підтримує цей параметр.
  • size: вказує інформацію про розмір згенерованого зображення, підтримує два способи, які не можна змішувати. Спосіб 1 | Вказати роздільну здатність згенерованого зображення та описати співвідношення сторін, форму або призначення зображення природною мовою в підказці, в результаті чого модель визначить розмір згенерованого зображення. Спосіб 2 | Вказати значення пікселів ширини та висоти зображення: значення за замовчуванням: 2048x2048, залежно від моделі значення за замовчуванням можуть відрізнятися.
  • seed: випадкове число, яке контролює випадковість вмісту, що генерується моделлю. Діапазон значень: [-1, 2147483647]. Лише doubao-seedream-3.0-t2i, doubao-seededit-3.0-i2i підтримують цей параметр.
  • sequential_image_generation: група зображень: на основі введеного вами вмісту генерується набір пов’язаних зображень. Лише doubao-seedream-4.5, doubao-seedream-4.0 підтримують цей параметр, за замовчуванням disabled.
  • stream: контролює, чи включити режим потокового виводу. Лише doubao-seedream-4.5, doubao-seedream-4.0 підтримують цей параметр, за замовчуванням false.
  • guidance_scale: ступінь відповідності результатів моделі та підказки, ступінь свободи згенерованого зображення, також відомий як вага тексту; чим більше значення, тим менша свобода моделі, і тим сильніше кореляція з підказкою користувача. Діапазон значень: [1, 10]. doubao-seedream-3.0-t2i значення за замовчуванням 2.5, doubao-seededit-3.0-i2i значення за замовчуванням 5.5, інші не підтримують.
  • response_format: вказує формат повернення згенерованого зображення. За замовчуванням url, також підтримує b64_json.
  • watermark: чи потрібно додавати водяний знак до згенерованого зображення. За замовчуванням true.
  • callback_url: URL, на який потрібно повернути результати.
Після вибору ви можете помітити, що праворуч також згенеровано відповідний код, як показано на малюнку:

Натисніть кнопку «Try», щоб провести тестування, як показано на малюнку, тут ми отримали наступний результат: 
{
  "success": true,
  "task_id": "25027ba3-0430-4a1b-91c8-d2297f19ba73",
  "trace_id": "8043a9e9-692f-43b0-82f7-5890f798be38",
  "data": [
    {
      "prompt": "a white siamese cat",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.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-4-0-250828",
  "prompt": "a white siamese cat"
}'

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

Якщо ви хочете редагувати певне зображення, спочатку параметр image повинен містити посилання на зображення, яке потрібно редагувати.
  • model: модель, що використовується для редагування зображення, ця задача наразі підтримує doubao-seedream-4.5, doubao-seedream-4.0, підтримує одноразове або багаторазове введення, doubao-seededit-3.0-i2i підтримує лише одноразове введення.
  • 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. Нижче ми розглянемо приклад, щоб зрозуміти, як саме це працює. Натиснувши “Запустити”, можна помітити, що відразу отримується результат, як показано нижче: 
{
  "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. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.