任務中心模組

功能說明

介面字首統一為 http(s)://<your-domain>

生產環境應使用 HTTPS 以保證認證令牌。 HTTP 僅建議用於開發環境。

通用非同步任務管理系統。主要支援 Suno 等平臺的音樂生成任務。包含任務狀態自動更新、失敗重試、配額退還等機制。

🔐 使用者鑑權

獲取我的任務

介面名稱：獲取我的任務
HTTP 方法：GET
路徑：/api/task/self
鑑權要求：使用者
功能簡介：分頁獲取當前使用者的任務列表，支援按平臺、任務 ID、狀態等條件過濾

💡 請求示例：

const response = await fetch('/api/task/self?p=1&page_size=20&platform=suno&task_id=task123&status=SUCCESS&action=song&start_timestamp=1640908800&end_timestamp=1640995200', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "id": 1,
        "created_at": 1640908800,
        "updated_at": 1640909000,
        "task_id": "task123456",
        "platform": "suno",
        "user_id": 1,
        "quota": 1000,
        "action": "song",
        "status": "SUCCESS",
        "fail_reason": "",
        "submit_time": 1640908800,
        "start_time": 1640908900,
        "finish_time": 1640909000,
        "progress": "100%",
        "properties": {},
        "data": {}
      }
    ],
    "total": 25,
    "page": 1,
    "page_size": 20
  }
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "獲取任務列表失敗"
}

🧾 欄位說明：

p （數字）: 頁碼，預設為 1
page_size （數字）: 每頁數量，預設為 20
platform （字串）: 任務平臺，可選
task_id （字串）: 任務 ID 過濾，可選
status （字串）: 任務狀態過濾，可選值："NOT_START"、"SUBMITTED"、"QUEUED"、"IN_PROGRESS"、"FAILURE"、"SUCCESS"、"UNKNOWN"
action （字串）: 任務型別過濾，如"song"、"lyrics"等
start_timestamp （數字）: 開始時間戳，可選
end_timestamp （數字）: 結束時間戳，可選

🧾 返回欄位說明：

id （數字）: 資料庫記錄 ID
task_id （字串）: 第三方任務 ID
platform （字串）: 任務平臺
user_id （數字）: 使用者 ID
quota （數字）: 消耗的配額
action （字串）: 任務型別
status （字串）: 任務狀態
fail_reason （字串）: 失敗原因
submit_time （數字）: 提交時間戳
start_time （數字）: 開始時間戳
finish_time （數字）: 完成時間戳
progress （字串）: 進度百分比
properties （物件）: 任務屬性
data （物件）: 任務結果資料
total （數字）: 符合條件的任務總記錄數
page （數字）: 當前返回的頁碼
page_size （數字）: 每頁展示的任務記錄數

🔐 管理員鑑權

獲取全部任務

介面名稱：獲取全部任務
HTTP 方法：GET
路徑：/api/task/
鑑權要求：管理員
功能簡介：分頁獲取系統中所有任務，支援按渠道 ID、平臺、使用者 ID 等條件過濾

💡 請求示例：

const response = await fetch('/api/task/?p=1&page_size=20&channel_id=1&platform=suno&task_id=task123&status=SUCCESS&action=song&start_timestamp=1640908800&end_timestamp=1640995200', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "id": 1,
        "created_at": 1640908800,
        "task_id": "task123456",
        "platform": "suno",
        "user_id": 1,
        "channel_id": 1,
        "quota": 1000,
        "action": "song",
        "status": "SUCCESS",
        "submit_time": 1640908800,
        "finish_time": 1640909000,
        "progress": "100%",
        "data": {}
      }
    ],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "獲取任務列表失敗"
}

🧾 欄位說明：

p （數字）: 頁碼，預設為 1
page_size （數字）: 每頁數量，預設為 20
channel_id （字串）: 渠道 ID 過濾，可選
platform （字串）: 任務平臺過濾，可選
task_id （字串）: 任務 ID 過濾，可選
status （字串）: 任務狀態過濾，可選
action （字串）: 任務型別過濾，可選
start_timestamp （數字）: 開始時間戳，可選
end_timestamp （數字）: 結束時間戳，可選
返回欄位包含使用者任務的所有欄位，另外增加：
- channel_id （數字）: 使用的渠道 ID

🔐 使用者鑑權

獲取我的任務

🔐 管理員鑑權

獲取全部任務

目錄