Перейти к основному содержанию
В этой статье будет представлено руководство по интеграции 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
    }
  ]
}
Как видно, сгенерированный эффект — это редактирование оригинального изображения, результат аналогичен вышеупомянутому.

​
Асинхронный обратный вызов

由于 Flux Images Generation API 生成的时间相对较长，大约需要 1-2 分钟，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。 整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，生成图片的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。 下面我们通过示例来了解下具体怎样操作。 首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 https://webhook.site/，打开该网站即可得到一个 Webhook URL，如图所示： 将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab。 接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入相应的参数，具体的内容如图所示：

点击运行，可以发现会立即得到一个结果，如下： 
{
  "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"
}

​
结论

通过本文档，您已经了解了如何使用 Flux Images Generation API 可通过输入提示词来生成图片。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。