Fish Tasks API 的串接與使用

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

申請流程

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

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

📘 完整文件：Fish Audios Generation API →

請求範例

Fish Tasks API 可用於查詢 Fish Audios Generation API 的結果。關於如何使用 Fish Audios Generation API，請參考文件 Fish Videos Generation API 。我們以 Fish Audios Generation API 服務返回的一個任務 ID 為例，示範如何使用該 API。假設我們有一個任務 ID：2725a2d3-f87e-4905-9c53-9988d5a7b2f5，接下來示範如何透過傳入一個任務 ID 來查詢。

任務範例圖

設定請求標頭和請求主體

Request Headers 包括：

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

Request Body 包括：

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

設定如下圖所示：

程式碼範例

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

部分程式碼範例如下：

CURL

curl -X POST 'https://api.acedata.cloud/fish/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "action": "retrieve"
}'

回應範例

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

{
  "_id": "68cfad98550a4144a5476a92",
  "id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "api_id": "8e6f8083-4683-45fe-a993-3e1d993fc999",
  "application_id": "3559d836-2505-46be-96ea-ea72bcb7c080",
  "created_at": 1758440856.34,
  "started_at": 1758440856.4,
  "finished_at": 1758440869.2,
  "elapsed": 12.8,
  "credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
  "request": {
    "action": "speech",
    "prompt": "a white siamese cat",
    "model": "fish-tts",
    "voice_id": "d7900c21663f485ab63ebdb7e5905036",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  },
  "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
  "type": "audios",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
    "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
    "data": [
      {
        "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
      }
    ]
  }
}

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

id，生成此任務的 ID，用於唯一識別此次生成任務。
request，查詢任務中的請求資訊。
response，查詢任務中的返回資訊；最終成功時其中的 cost.amount 是該次合成實際扣除的 Credits。
created_at，任務建立時間，Unix 時間戳（秒，浮點數）。
started_at，任務開始執行時間，Unix 時間戳（秒，浮點數）。
finished_at，任務完成時間，Unix 時間戳（秒，浮點數）。任務未完成時不返回該欄位。
elapsed，任務執行耗時，單位為秒（浮點數，保留 3 位小數）。任務未完成時不返回該欄位。

批次查詢操作

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

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

設定如下圖所示：

程式碼範例

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

部分程式碼範例如下：

回應範例

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

{
  "items": [
    {
      "_id": "68cfad98550a4144a5476a92",
      "id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
      "api_id": "8e6f8083-4683-45fe-a993-3e1d993fc999",
      "application_id": "3559d836-2505-46be-96ea-ea72bcb7c080",
      "created_at": 1758440856.34,
      "started_at": 1758440856.4,
      "finished_at": 1758440869.2,
      "elapsed": 12.8,
      "credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
      "request": {
        "action": "speech",
        "prompt": "a white siamese cat",
        "model": "fish-tts",
        "voice_id": "d7900c21663f485ab63ebdb7e5905036",
        "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
      },
      "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
      "type": "audios",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
        "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
        "data": [
          {
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
          }
        ]
      }
    },
    {
      "_id": "68cfad98550a4144a5476a92",
      "id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
      "api_id": "8e6f8083-4683-45fe-a993-3e1d993fc999",
      "application_id": "3559d836-2505-46be-96ea-ea72bcb7c080",
      "created_at": 1758440856.34,
      "started_at": 1758440856.4,
      "finished_at": 1758440869.2,
      "elapsed": 12.8,
      "credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
      "request": {
        "action": "speech",
        "prompt": "a white siamese cat",
        "model": "fish-tts",
        "voice_id": "d7900c21663f485ab63ebdb7e5905036",
        "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
      },
      "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
      "type": "audios",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
        "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
        "data": [
          {
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
          }
        ]
      }
    }
  ],
  "count": 2
}

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

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

CURL

curl -X POST 'https://api.acedata.cloud/fish/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["2725a2d3-f87e-4905-9c53-9988d5a7b2f5","2725a2d3-f87e-4905-9c53-9988d5a7b2f5"],
  "action": "retrieve_batch"
}'

錯誤處理

在呼叫 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"
}

結論

透過本文檔，您已經瞭解如何使用 Fish Tasks API 查詢單個或批次任務的所有具體詳細資訊。希望本文檔能幫助您更好地串接和使用該 API。如有任何問題，請隨時聯絡我們的技術支援團隊。

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

Coding

更多指南

Fish Tasks API 的串接與使用

申請流程

請求範例

任務範例圖

設定請求標頭和請求主體

程式碼範例

CURL

回應範例

批次查詢操作

程式碼範例

回應範例

CURL

錯誤處理

錯誤回應範例

結論

​申請流程

​請求範例

​任務範例圖

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

​程式碼範例

​CURL

​回應範例

​批次查詢操作

​程式碼範例

​回應範例

​CURL

​錯誤處理

​錯誤回應範例

​結論

申請流程

請求範例

任務範例圖

設定請求標頭和請求主體

程式碼範例

CURL

回應範例

批次查詢操作

程式碼範例

回應範例

CURL

錯誤處理

錯誤回應範例

結論