Flux 图像生成 API 集成指南

在本篇文章中，我们将为您介绍 Flux 图像生成 API 的集成步骤。通过该 API，您可以输入自定义参数以生成官方的 Flux 图像。Flux 图像生成 API 是一个强大的工具，适用于需要图像生成的应用场景，如内容创作、游戏开发和广告设计等。

环境准备/前置条件

在开始之前，您需要满足以下前置条件：

注册并登录 Ace Data Cloud 账户。
申请 Flux 图像生成 API 服务，具体步骤见下文。

详细步骤

1. 申请 API

要使用该 API，您首先需要在 Flux 图像生成 API 页面申请相应的服务。进入页面后，点击"获取"按钮，如下图所示：

如果您尚未登录或注册，系统会自动引导您进行相应操作。注册或登录后，您将会返回到当前页面。

首次申请时，您将获得免费的使用配额，可以免费使用该 API。

2. 基本用法

了解基本的使用方法后，您需要输入 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	不支持纵横比

选择完毕后，您可以看到右侧生成的代码示例，如下图所示：

点击"尝试"按钮进行测试，您将获得如下 JSON 结果：

json 复制代码

{
  "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
    }
  ]
}

返回结果包含多个字段，说明如下：

success: 图像生成任务的状态。
task_id: 当前图像生成任务的 ID。
trace_id: 当前图像生成的追踪 ID。
data: 当前图像生成任务的结果列表，其中包含：
image_url: 图像生成任务的链接。
prompt: 提示内容。

3. 编辑图像任务

若要编辑特定图像，需传入 image_url 参数，链接指向需编辑的图像，此时 action 仅支持 edit，并可指定以下内容：

model: 用于此图像编辑任务的模型，支持 flux-kontext-max 和 flux-kontext-pro。

示例输入如下：

填写完后，系统将自动生成如下代码：

对应的代码如下：

python 复制代码

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)

运行后，您将立即获得如下结果：

json 复制代码

{
  "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
    }
  ]
}

生成效果为原始图像的编辑结果。

4. 异步回调

由于 Flux 图像生成 API 的生成时间相对较长，约需 1-2 分钟，若 API 长时间未响应，HTTP 请求将保持连接，导致额外的系统资源消耗。因此，此 API 还支持异步回调。

具体流程如下：客户端发起请求时，需额外指定 callback_url 字段。请求后，API 会立即返回一个结果，包含 task_id 字段，表示当前任务 ID。任务完成后，生成结果将以 POST JSON 形式发送至客户端指定的 callback_url，也包含 task_id 字段，便于通过 ID 关联任务结果。

具体操作如下：

首先，您需要一个能够接收 HTTP 请求的 Webhook 回调服务，开发者应将其替换为自己 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 上查看生成的图像结果，内容如下：

```json { "success": true, "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c