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

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

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

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

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

Ми можемо бачити, що тут ми налаштували заголовки запиту, включаючи:
  • accept: формат відповіді, який ви хочете отримати, тут вказано application/json, тобто формат JSON.
  • authorization: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку.
Крім того, налаштовано тіло запиту, яке включає:
  • action: дія для завдання генерації зображення.
  • size: розмір згенерованого зображення.
  • count: кількість згенерованих зображень, значення за замовчуванням - 1, цей параметр дійсний лише для завдань генерації зображень, для редагування він недійсний.
  • prompt: підказка.
  • model: модель генерації, за замовчуванням flux-dev.
  • callback_url: URL для отримання результатів.
Параметр size має деякі особливі обмеження, які в основному поділяються на два типи: співвідношення ширини до висоти width x height та співвідношення зображення x:y, конкретно наведено нижче:
МодельДіапазон
flux-2-flexПідтримує співвідношення ширини до висоти x >= 64, має бути кратним 32
flux-2-proПідтримує співвідношення ширини до висоти x >= 64, має бути кратним 32
flux-2-maxПідтримує співвідношення ширини до висоти x >= 64, має бути кратним 32
flux-pro-1.1Підтримує співвідношення ширини до висоти 256 <= x <= 1440, має бути кратним 32
flux-devПідтримує співвідношення ширини до висоти 256 <= x <= 1440, має бути кратним 32
flux-pro-1.1-ultraНе підтримує співвідношення ширини до висоти, підтримує співвідношення зображення
flux-kontext-proНе підтримує співвідношення ширини до висоти, підтримує співвідношення зображення
flux-kontext-maxНе підтримує співвідношення ширини до висоти, підтримує співвідношення зображення
Приклади співвідношення зображення: “1:1”, “16:9”, “21:9”, “3:2”, “2:3”, “4:5”, “5:4”, “3:4”, “4:3”, “9:16”, “9:21”. Після вибору ви можете помітити, що праворуч також згенеровано відповідний код, як показано на малюнку:

Натисніть кнопку «Try», щоб провести тестування, як показано на малюнку, тут ми отримали наступний результат: 
{
  "success": true,
  "task_id": "226eb763-9eab-4d06-ad57-d59753a03307",
  "trace_id": "089f8b46-0167-4f25-88ee-3c3f88d80e84",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://fal.media/files/lion/NVhtlwwGYQD6HrGaEfrzu_341484fad6d84b21b73f4f8824a3f98a.png",
      "timings": 1752743801
    },
    {
      "prompt": "a white siamese cat",
      "image_url": "https://fal.media/files/monkey/8UEQpFbQCYVOK1wKP3aV0_9bbc26fad64049b18d0244b99ef66ad1.png",
      "timings": 1752743801
    }
  ]
}
У повернутому результаті є кілька полів, описаних нижче:
  • success: статус завдання генерації відео.
  • task_id: ID завдання генерації відео.
  • trace_id: ID відстеження генерації відео.
  • data: список результатів завдання генерації зображення.
    • image_url: посилання на завдання генерації зображення.
    • prompt: підказка.
Ми можемо бачити, що отримали задовільну інформацію про зображення, нам потрібно лише отримати згенероване зображення Flux за адресою посилання з data. Крім того, якщо ви хочете згенерувати відповідний код інтеграції, ви можете просто скопіювати його, наприклад, код CURL виглядає так: 
curl -X POST 'https://api.acedata.cloud/flux/images' \
-H 'authorization: Bearer {token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "a white siamese cat",
  "model": "flux-kontext-pro",
  "count": 2
}'

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

Якщо ви хочете редагувати певне зображення, спочатку параметр image_url повинен містити посилання на зображення, яке потрібно редагувати, у цьому випадку action підтримує лише edit, і ви можете вказати наступні параметри:
  • model: модель, яка використовується для редагування зображення, ця задача наразі підтримує flux-kontext-max, flux-kontext-pro.
  • image_url: завантажте зображення, яке потрібно редагувати.
Приклад заповнення наведено нижче:

Після заповнення автоматично згенеровано код, як показано нижче:

Відповідний код: 
import requests

url = "https://api.acedata.cloud/flux/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "edit",
    "prompt": "a white siamese cat",
    "model": "flux-kontext-pro",
    "image_url": "https://cdn.acedata.cloud/ytj2qy.png"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Натиснувши «Запустити», ви можете помітити, що відразу отримаєте результат, як показано нижче: 
{
  "success": true,
  "task_id": "2a7979ff-1f77-4380-92c6-a2dc37c3b4c8",
  "trace_id": "732b65c0-48d9-49f7-b568-64e5acffe4c0",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://fal.media/files/monkey/aEUXJZ6Faj9YXUCQVs01Q_af0cea56c558441c9ba8df67b200812d.png",
      "timings": 1752744073
    }
  ]
}
Ми можемо бачити, що згенерований ефект є редагуванням оригінального зображення, результат схожий на попередній.

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

Оскільки час генерації зображень за допомогою API Flux Images Generation є відносно тривалим, приблизно 1-2 хвилини, якщо API довго не відповідає, HTTP запит буде постійно підтримувати з’єднання, що призведе до додаткових витрат системних ресурсів, тому цей API також надає підтримку асинхронних зворотних викликів. Загальний процес такий: коли клієнт ініціює запит, додатково вказується поле callback_url, після ініціації запиту API відразу повертає результат, що містить інформацію про поле task_id, яке представляє поточний ідентифікатор завдання. Коли завдання завершено, результат генерації зображення буде надіслано на вказаний клієнтом callback_url у форматі POST JSON, в якому також міститься поле task_id, таким чином результати завдання можна пов’язати за допомогою ID. Далі ми розглянемо приклад, щоб зрозуміти, як саме це працює. По-перше, зворотний виклик Webhook — це сервіс, який може приймати HTTP запити, розробники повинні замінити його на URL свого HTTP сервера. Для зручності демонстрації використовується публічний зразок сайту Webhook https://webhook.site/, відкривши цей сайт, ви отримаєте URL Webhook, як показано на малюнку: Скопіюйте цей URL, і ви зможете використовувати його як Webhook, приклад тут: https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. Далі ми можемо налаштувати поле callback_url на вказаний вище URL Webhook, одночасно заповнивши відповідні параметри, конкретний зміст, як показано на малюнку:

Натиснувши “Запустити”, ви відразу отримаєте результат, як показано нижче: 
{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}
Почекавши деякий час, ми можемо спостерігати результати генерації зображення на https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab, як показано на малюнку: Зміст такий: 
{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://sf-maas-uat-prod.oss-cn-shanghai.aliyuncs.com/outputs/f4f8d407-377a-408a-82d0-427a5a836f09_0.png",
      "seed": 1698551532,
      "timings": {
        "inference": 3.328
      }
    }
  ]
}
Можна побачити, що в результаті є поле 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 Flux Images Generation для генерації зображень за допомогою введення підказок. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої технічної підтримки.