Інтеграція та використання Fish Tasks API

Основною функцією Fish Tasks API є запит стану виконання завдання шляхом введення ID завдання, згенерованого Fish Audios Generation API. У цьому документі буде детально представлено інструкції з інтеграції 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 。 Візьмемо як приклад один ID завдання, повернений сервісом Fish Audios Generation API, щоб продемонструвати, як використовувати цей 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 timestamp (секунди, число з рухомою комою).
started_at — час початку виконання завдання, Unix timestamp (секунди, число з рухомою комою).
finished_at — час завершення завдання, Unix timestamp (секунди, число з рухомою комою). Це поле не повертається, якщо завдання не завершено.
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. Якщо у вас виникнуть будь-які запитання, будь ласка, зв’яжіться з нашою командою технічної підтримки в будь-який час.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Coding

Інші посібники

Інтеграція та використання Fish Tasks API

Процес подання заявки

Приклад запиту

Зображення прикладу завдання

Налаштування заголовків запиту та тіла запиту

Приклад коду

CURL

Приклад відповіді

Операція пакетного запиту

Приклад коду

Приклад відповіді

CURL

Обробка помилок

Приклад відповіді з помилкою

Висновок

​Процес подання заявки

​Приклад запиту

​Зображення прикладу завдання

​Налаштування заголовків запиту та тіла запиту

​Приклад коду

​CURL

​Приклад відповіді

​Операція пакетного запиту

​Приклад коду

​Приклад відповіді

​CURL

​Обробка помилок

​Приклад відповіді з помилкою

​Висновок

Процес подання заявки

Приклад запиту

Зображення прикладу завдання

Налаштування заголовків запиту та тіла запиту

Приклад коду

CURL

Приклад відповіді

Операція пакетного запиту

Приклад коду

Приклад відповіді

CURL

Обробка помилок

Приклад відповіді з помилкою

Висновок