Luma Tasks API 的對接和使用

Luma Tasks API 的主要功能是通過輸入 Luma Videos Generation API 生成的任務ID來查詢該任務的執行情況。本文檔將詳細介紹 Luma Tasks API 的對接說明，幫助您輕鬆集成並充分利用該 API 的強大功能。通過 Luma Tasks API，您可以輕鬆實現查詢 Luma Videos Generation API 的任務執行情況。

申請流程

要使用 Luma Videos Generation API，首先到 Ace Data Cloud 控制台獲取您的 API Token，留作備用。

如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。 一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可在控制台充值通用餘額。

📘 完整文檔：Luma Videos Generation API →

請求示例

Luma Tasks API 可以用於查詢 Luma Videos Generation API 的結果。關於怎樣使用 Luma Videos Generation API，請參考文檔 Luma Videos Generation API。我們以 Luma Videos Generation API 服務返回的任務ID一個為例，演示如何使用該 API。假設我們有一個任務ID：50fc6182-fa86-4c7d-ac12-2fa27ec2f151，接下來演示如何通過傳入一個任務ID來。

任務示例圖

設置請求頭和請求體

Request Headers 包括：

accept：指定接收 JSON 格式的響應結果，這裡填寫為 application/json。
authorization：調用 API 的密鑰，申請之後可以直接下拉選擇。

Request Body 包括：

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

設置如下圖所示：

代碼示例

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

部分代碼示例如下：

CURL

curl -X POST 'https://api.acedata.cloud/luma/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "50fc6182-fa86-4c7d-ac12-2fa27ec2f151",
  "action": "retrieve"
}'

Python

import requests

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

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

payload = {
    "id": "50fc6182-fa86-4c7d-ac12-2fa27ec2f151",
    "action": "retrieve"
}

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

響應示例

請求成功後，API 將返回此處視頻任務的詳情信息。例如：

{
  "_id": "66d297a3550a4144a5a5db42",
  "id": "50fc6182-fa86-4c7d-ac12-2fa27ec2f151",
  "api_id": "94fc9028-5a9f-4875-aae4-38463bd30ac5",
  "application_id": "06484a45-9d04-498a-98a7-67086dee8166",
  "created_at": 1725077411.961,
  "credential_id": "e6a879e5-a7c0-4f7b-9d6f-f9a837421a50",
  "request": {
    "action": "generate",
    "prompt": "Astronauts shuttle from space to volcano"
  },
  "trace_id": "0b7c1c1a-045c-4145-a434-609cba88f0a9",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "50fc6182-fa86-4c7d-ac12-2fa27ec2f151",
    "video_id": "4b088fc8-2bbc-4706-80a6-a0fb118adc1a",
    "prompt": "Astronauts shuttle from space to volcano",
    "video_url": "https://platform.cdn.acedata.cloud/luma/50fc6182-fa86-4c7d-ac12-2fa27ec2f151.mp4",
    "video_height": 752,
    "video_width": 1360,
    "state": "completed",
    "thumbnail_url": "https://platform.cdn.acedata.cloud/luma/50fc6182-fa86-4c7d-ac12-2fa27ec2f151.jpg",
    "thumbnail_width": 1360,
    "thumbnail_height": 752
  },
  "finished_at": 1725077566.241
}

返回結果一共有多個字段，request 字段就是發起任務時的 request body，同時response 字段是任務完成後返回的response body，其結果和 Luma Videos Generation API 的請求和返回一致。字段介紹如下。

id，生成此視頻任務的 ID，用於唯一標識此次視頻生成任務。
video_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": "66d297a3550a4144a5a5db42",
      "id": "50fc6182-fa86-4c7d-ac12-2fa27ec2f151",
      "api_id": "94fc9028-5a9f-4875-aae4-38463bd30ac5",
      "application_id": "06484a45-9d04-498a-98a7-67086dee8166",
      "created_at": 1725077411.961,
      "credential_id": "e6a879e5-a7c0-4f7b-9d6f-f9a837421a50",
      "request": {
        "action": "generate",
        "prompt": "宇航員從太空穿梭到火山"
      },
      "trace_id": "0b7c1c1a-045c-4145-a434-609cba88f0a9",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "50fc6182-fa86-4c7d-ac12-2fa27ec2f151",
        "video_id": "4b088fc8-2bbc-4706-80a6-a0fb118adc1a",
        "prompt": "宇航員從太空穿梭到火山",
        "video_url": "https://platform.cdn.acedata.cloud/luma/50fc6182-fa86-4c7d-ac12-2fa27ec2f151.mp4",
        "video_height": 752,
        "video_width": 1360,
        "state": "completed",
        "thumbnail_url": "https://platform.cdn.acedata.cloud/luma/50fc6182-fa86-4c7d-ac12-2fa27ec2f151.jpg",
        "thumbnail_width": 1360,
        "thumbnail_height": 752
      },
      "finished_at": 1725077566.241
    },
    {
      "_id": "66d29ed3550a4144a5a6c089",
      "id": "76a05f61-68ad-4c1a-838f-a00cd08cf65b",
      "api_id": "94fc9028-5a9f-4875-aae4-38463bd30ac5",
      "application_id": "06484a45-9d04-498a-98a7-67086dee8166",
      "created_at": 1725079250.921,
      "credential_id": "e6a879e5-a7c0-4f7b-9d6f-f9a837421a50",
      "request": {
        "action": "generate",
        "prompt": "啦啦啦"
      },
      "trace_id": "338f1616-741d-40b6-8d62-c025434024c6",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "76a05f61-68ad-4c1a-838f-a00cd08cf65b",
        "video_id": "5a638d6a-7481-4c5e-8843-36c9d1b5bcd5",
        "prompt": "啦啦啦",
        "video_url": "https://platform.cdn.acedata.cloud/luma/76a05f61-68ad-4c1a-838f-a00cd08cf65b.mp4",
        "video_height": 752,
        "video_width": 1360,
        "state": "completed",
        "thumbnail_url": "https://platform.cdn.acedata.cloud/luma/76a05f61-68ad-4c1a-838f-a00cd08cf65b.jpg",
        "thumbnail_width": 1360,
        "thumbnail_height": 752
      },
      "finished_at": 1725079406.71
    }
  ],
  "count": 2
}

CURL

curl -X POST 'https://api.acedata.cloud/luma/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["50fc6182-fa86-4c7d-ac12-2fa27ec2f151","76a05f61-68ad-4c1a-838f-a00cd08cf65b"],
  "action": "retrieve_batch"
}'

Python

import requests

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

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

payload = {
    "ids": ["50fc6182-fa86-4c7d-ac12-2fa27ec2f151","76a05f61-68ad-4c1a-838f-a00cd08cf65b"],
    "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": "獲取失敗"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

結論

通過本文檔，您已經了解了如何使用 Luma Tasks API 進行查詢單個或批量視頻任務的所有具體詳情信息。希望本文檔能幫助您更好地對接和使用該 API。如有任何問題，請隨時聯繫我們的技術支持團隊。

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

代理

進階

Luma Tasks API 的對接和使用

申請流程

請求示例

任務示例圖

設置請求頭和請求體

代碼示例

CURL

Python

響應示例

批量查詢操作

代碼示例

響應示例

CURL

Python

錯誤處理

錯誤響應示例

結論

​申請流程

​請求示例

​任務示例圖

​設置請求頭和請求體

​代碼示例

​CURL

​Python

​響應示例

​批量查詢操作

​代碼示例

​響應示例

​CURL

​Python

​錯誤處理

​錯誤響應示例

​結論

申請流程

請求示例

任務示例圖

設置請求頭和請求體

代碼示例

CURL

Python

響應示例

批量查詢操作

代碼示例

響應示例

CURL

Python

錯誤處理

錯誤響應示例

結論