Flux Tasks API 的串接與使用

Flux Tasks API 的主要功能是透過輸入 Flux Images Generation API 或 Flux Videos API 回傳的平台任務 ID，來查詢該任務的執行情況。本文檔將詳細介紹 Flux Tasks API 的串接說明，協助您輕鬆整合並充分利用該 API 的強大功能。透過 Flux Tasks API，您可以輕鬆實現查詢 Flux Images Generation API 的任務執行情況。影片提交與輪詢的完整範例請參見 Flux Videos API 整合指南。查詢既有任務不會另外收取生成費用。

申請流程

要使用 Flux Images Generation API，首先前往 Ace Data Cloud 控制台取得您的 API Token，留作備用。

如果您尚未登入或註冊，會自動跳轉至登入頁面邀請您註冊及登入，完成後會自動返回目前頁面。 一個 API Token 即可呼叫平台所有服務，無須為每個服務分別申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可在控制台儲值通用餘額。

📘 完整文件：Flux Images Generation API →

請求範例

Flux Tasks API 可用於查詢 Flux Images Generation API 的結果。關於如何使用 Flux Images Generation API，請參考文件 Flux Images Generation API 。我們以 Flux Images Generation API 服務回傳的一個任務 ID 為例，示範如何使用該 API。假設我們有一個任務 ID：2db0168c-2373-4367-8d9a-9dc778802e8a，接下來示範如何透過傳入一個任務 ID 來。

任務範例圖

設定請求標頭和請求主體

Request Headers 包括：

accept：指定接收 JSON 格式的回應結果，此處填寫為 application/json。
authorization：呼叫 API 的金鑰，申請之後可以直接下拉選擇。

Request Body 包括：

id：上傳的任務 ID。
action：對任務的操作方式。

設定如下圖所示：

程式碼範例

可以發現，在頁面右側已經自動產生了各種語言的程式碼，如圖所示：

部分程式碼範例如下：

CURL

curl -X POST 'https://api.acedata.cloud/flux/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "2c454ff3-4f8f-47f0-8147-acb29a84d1c2",
  "action": "retrieve"
}'

Python

import requests

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

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

payload = {
    "id": "2c454ff3-4f8f-47f0-8147-acb29a84d1c2",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

回應範例

請求成功後，API 將回傳此處圖片任務的詳細資訊。例如：

{
  "_id": "677de81d550a4144a5f4cf62",
  "id": "2db0168c-2373-4367-8d9a-9dc778802e8a",
  "api_id": "deefc5d7-7f22-43e9-929e-f2b6afee60b7",
  "application_id": "001c2f84-2a4a-4c4d-ba3f-8a89f43b5be2",
  "created_at": 1736304669.779,
  "started_at": 1736304669.839,
  "finished_at": 1736304679.439,
  "elapsed": 9.6,
  "credential_id": "b00bddd3-140f-4343-a9a2-affb312b60de",
  "request": {
    "action": "generate",
    "size": "1024x1024",
    "prompt": "a white siamese cat"
  },
  "trace_id": "6624929c-bb80-40c0-81e8-d96af8405d19",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "2db0168c-2373-4367-8d9a-9dc778802e8a",
    "trace_id": "6624929c-bb80-40c0-81e8-d96af8405d19",
    "data": [
      {
        "prompt": "a white siamese cat",
        "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
        "seed": 281520112,
        "timings": {
          "inference": 3.193
        }
      }
    ]
  }
}

回傳結果一共有多個欄位，request 欄位就是發起任務時的 request body，而 response 欄位則是任務完成後回傳的 response body。欄位介紹如下。

id，產生此圖片任務的 ID，用於唯一識別此次圖片生成任務。
request，查詢圖片任務中的請求資訊。
response，查詢圖片任務中的回傳資訊。
created_at，任務建立時間，Unix 時間戳記（秒，浮點）。
started_at，任務開始執行時間，Unix 時間戳記（秒，浮點）。
finished_at，任務完成時間，Unix 時間戳記（秒，浮點）。任務未完成時不回傳此欄位。
elapsed，任務執行耗時，單位為秒（浮點，保留 3 位小數）。任務未完成時不回傳此欄位。

批次查詢操作

這是針對多個任務 ID 進行查詢圖片任務詳情，與上方不同的是需要將 action 選擇為 retrieve_batch Request Body 包括：

ids：上傳的任務 ID 陣列。
action：對任務的操作方式。

設定如下圖所示：

程式碼範例

可以發現，在頁面右側已經自動產生了各種語言的程式碼，如圖所示：

部分程式碼範例如下：

回應範例

請求成功後，API 將回傳此次所有批次圖片任務的具體詳細資訊。例如：

{
  "items": [
    {
      "_id": "677de81d550a4144a5f4cf62",
      "id": "2db0168c-2373-4367-8d9a-9dc778802e8a",
      "api_id": "deefc5d7-7f22-43e9-929e-f2b6afee60b7",
      "application_id": "001c2f84-2a4a-4c4d-ba3f-8a89f43b5be2",
      "created_at": 1736304669.779,
      "started_at": 1736304669.839,
      "finished_at": 1736304679.439,
      "elapsed": 9.6,
      "credential_id": "b00bddd3-140f-4343-a9a2-affb312b60de",
      "request": {
        "action": "generate",
        "size": "1024x1024",
        "prompt": "a white siamese cat"
      },
      "trace_id": "6624929c-bb80-40c0-81e8-d96af8405d19",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "2db0168c-2373-4367-8d9a-9dc778802e8a",
        "trace_id": "6624929c-bb80-40c0-81e8-d96af8405d19",
        "data": [
          {
            "prompt": "a white siamese cat",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "seed": 281520112,
            "timings": {
              "inference": 3.193
            }
          }
        ]
      }
    },
    {
      "_id": "677de950550a4144a5f52963",
      "id": "72bdd69d-290d-4710-a6d4-60c78968865a",
      "api_id": "deefc5d7-7f22-43e9-929e-f2b6afee60b7",
      "application_id": "001c2f84-2a4a-4c4d-ba3f-8a89f43b5be2",
      "created_at": 1736304976.278,
      "started_at": 1736304976.338,
      "finished_at": 1736304985.938,
      "elapsed": 9.6,
      "credential_id": "b00bddd3-140f-4343-a9a2-affb312b60de",
      "request": {
        "action": "generate",
        "size": "1024x1024",
        "prompt": "a white siamese cat"
      },
      "trace_id": "1dca4b49-d31d-42e6-83d9-7f0c56f62d31",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "72bdd69d-290d-4710-a6d4-60c78968865a",
        "trace_id": "1dca4b49-d31d-42e6-83d9-7f0c56f62d31",
        "data": [
          {
            "prompt": "a white siamese cat",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "seed": 1437672535,
            "timings": {
              "inference": 3.175
            }
          }
        ]
      }
    }
  ],
  "count": 2
}

回傳結果總共有多個欄位，其中 items 包含批次圖片任務的具體詳細資訊，每個圖片任務的具體資訊與上文的欄位相同，欄位資訊如下。

items，批次圖片任務的所有具體詳細資訊。它是一個陣列，每個陣列的元素和上文查詢單一任務的回傳結果格式相同。
count，此處批次查詢圖片任務的數量。

CURL

curl -X POST 'https://api.acedata.cloud/flux/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["2db0168c-2373-4367-8d9a-9dc778802e8a","72bdd69d-290d-4710-a6d4-60c78968865a"],
  "action": "retrieve_batch"
}'

Python

import requests

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

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

payload = {
    "ids": ["2db0168c-2373-4367-8d9a-9dc778802e8a","72bdd69d-290d-4710-a6d4-60c78968865a"],
    "action": "retrieve_batch"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

錯誤處理

在呼叫 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 Tasks API 查詢單一或批次圖片任務的所有具體詳細資訊。希望本文檔能幫助您更好地串接和使用該 API。如有任何問題，請隨時聯絡我們的技術支援團隊。

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

Coding

更多指南

Flux Tasks API 的串接與使用

申請流程

請求範例

任務範例圖

設定請求標頭和請求主體

程式碼範例

CURL

Python

回應範例

批次查詢操作

程式碼範例

回應範例

CURL

Python

錯誤處理

錯誤回應範例

結論

​申請流程

​請求範例

​任務範例圖

​設定請求標頭和請求主體

​程式碼範例

​CURL

​Python

​回應範例

​批次查詢操作

​程式碼範例

​回應範例

​CURL

​Python

​錯誤處理

​錯誤回應範例

​結論

申請流程

請求範例

任務範例圖

設定請求標頭和請求主體

程式碼範例

CURL

Python

回應範例

批次查詢操作

程式碼範例

回應範例

CURL

Python

錯誤處理

錯誤回應範例

結論