Перейти до основного вмісту
У цьому документі буде представлено інструкцію з інтеграції Fish Voices Generation API, яка дозволяє створювати власні голоси, вводячи посилання на аудіо.

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

Щоб використовувати API, спочатку потрібно перейти на сторінку Fish Voices Generation API для подачі заявки на відповідну послугу. Після переходу на сторінку натисніть кнопку «Acquire», як показано на малюнку: Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, запрошуючи вас зареєструватися та увійти. Після входу або реєстрації ви автоматично повернетеся на поточну сторінку. При першій подачі заявки вам буде надано безкоштовний ліміт, який дозволяє безкоштовно використовувати цей API.

​
Основне використання

Спочатку розглянемо основний спосіб використання, а саме введення посилання на аудіо голосу voice_url, після чого ви отримаєте оброблений результат. Конкретний зміст наведено нижче:

Ми бачимо, що тут налаштовані заголовки запиту, включаючи:
  • accept: формат відповіді, який ви хочете отримати, тут вказано application/json, тобто формат JSON.
  • authorization: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку.
Крім того, налаштовано тіло запиту, яке включає:
  • voice_url: посилання на завантажене аудіо голосу.
  • title: заголовок цього голосу.
  • image_urls: обкладинка цього голосу.
  • description: опис цього голосу.
  • callback_url: URL для отримання результатів.
Після вибору ви також можете побачити, що праворуч згенеровано відповідний код, як показано на малюнку:

Натисніть кнопку «Try», щоб провести тестування, як показано на малюнку, і ви отримаєте наступний результат: 
{
  "success": true,
  "task_id": "b01db503-dd9e-4f92-861a-344f14756217",
  "trace_id": "8731a2f1-7736-4a47-98e7-da942f9346a7",
  "data": {
    "_id": "d5d21261512b4852b9ccd709facf93f3",
    "type": "tts",
    "title": "test",
    "description": "test",
    "cover_image": "coverimage/d5d21261512b4852b9ccd709facf93f3",
    "train_mode": "fast",
    "state": "trained",
    "tags": [],
    "samples": [
      {
        "title": "Default Sample",
        "text": "Протягом тривалого спостереження було виявлено, що риби в екосистемі коралових рифів мають складні моделі групової поведінки. Вони використовують зміни кольору та специфічні пози плавання для передачі інформації, ця складна система невербальної комунікації демонструє адаптивну мудрість морських організмів.",
        "task_id": "4ae961828fc94c07b2103dc039a8466b",
        "audio": "task/4ae961828fc94c07b2103dc039a8466b.mp3"
      }
    ],
    "created_at": "2025-09-21T07:29:41.058506Z",
    "updated_at": "2025-09-21T07:29:41.057917Z",
    "languages": [
      "zh"
    ],
    "visibility": "public",
    "lock_visibility": false,
    "default_text": "Протягом тривалого спостереження було виявлено, що риби в екосистемі коралових рифів мають складні моделі групової поведінки. Вони використовують зміни кольору та специфічні пози плавання для передачі інформації, ця складна система невербальної комунікації демонструє адаптивну мудрість морських організмів.",
    "like_count": 0,
    "mark_count": 0,
    "shared_count": 0,
    "task_count": 0,
    "unliked": false,
    "liked": false,
    "marked": false,
    "author": {
      "_id": "7ecad23df62a4174acd6a2a6cb5201ee",
      "nickname": "Matthew Garcia",
      "avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
    }
  }
}
У повернутому результаті є кілька полів, описаних нижче:
  • success: статус створення завдання голосу.
    • data: результат музичного завдання
      • _id: ID завдання на створення голосу, який буде використано для подальшого клонування голосу.
      • title: заголовок голосу.
      • image_url: інформація про обкладинку голосу.
      • description: опис голосу.
      • train_mode: режим, що використовується для створення голосу.
      • tags: стиль голосу.
      • default_text: текстова інформація про голос, що створюється.
Ми отримали задовільну інформацію про голос, і нам потрібно лише виконати завдання клонування голосу, використовуючи data з id. Крім того, якщо ви хочете згенерувати відповідний код інтеграції, ви можете просто скопіювати його, наприклад, код CURL виглядає так: 
curl -X POST 'https://api.acedata.cloud/fish/voices' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "voice_url": "https://platform.r2.fish.audio/task/604133d7b3c7430385382470f67770e8.mp3",
  "title": "test",
  "description": "test"
}'

​
Асинхронний зворотний виклик

Оскільки час генерації Fish Voices Generation API відносно тривалий, приблизно 1-2 хвилини, якщо API довго не відповідає, HTTP запит буде підтримувати з’єднання, що призводить до додаткових витрат системних ресурсів. Тому цей API також підтримує асинхронний зворотний виклик. Загальний процес: коли клієнт ініціює запит, додатково вказується поле callback_url. Після ініціювання запиту API відразу повертає результат, що містить інформацію про поле task_id, яке представляє ID поточного завдання. Коли завдання завершено, результат генерації буде надіслано на вказаний клієнтом callback_url у форматі POST JSON, в якому також буде включено поле task_id, що дозволяє пов’язати результати завдання за ID. Давайте розглянемо приклад, щоб зрозуміти, як це працює. По-перше, зворотний виклик Webhook - це служба, яка може приймати HTTP запити, розробники повинні замінити URL на свій власний HTTP сервер. Для зручності демонстрації використовується публічний веб-сайт з прикладом Webhook https://webhook.site/, відкривши цей сайт, ви отримаєте URL Webhook, як показано на малюнку: Скопіюйте цей URL, і ви зможете використовувати його як Webhook, приклад тут: https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34. Далі ми можемо налаштувати поле callback_url на вказаний Webhook URL, одночасно заповнивши відповідні параметри, конкретний зміст наведено на малюнку:

Натиснувши «Запустити», ви відразу отримаєте результат, як показано нижче: 
{
  "task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8"
}
Зачекайте хвилинку, ми можемо спостерігати результати генерації завдання на https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34, як показано на малюнку: Зміст такий: 
{
    "success": true,
    "task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8",
    "trace_id": "3fcdea82-7c1c-4a0a-b8d8-f7616f722d8f",
    "data": {
        "_id": "fa75e7c3f02f42e79a6aa622b6cf075e",
        "type": "tts",
        "title": "test",
        "description": "test",
        "cover_image": "coverimage/fa75e7c3f02f42e79a6aa622b6cf075e",
        "train_mode": "fast",
        "state": "trained",
        "tags": [],
        "samples": [
            {
                "title": "Default Sample",
                "text": "Дельфіни орієнтуються в океані за допомогою системи ехолокації, ця точна звукова технологія дозволяє їм виявляти навколишнє середовище, шукати їжу та уникати небезпеки. Це не лише демонструє адаптаційні можливості морських істот, але й розкриває чудовий дизайн природи.",
                "task_id": "68cdda24d26e4794bae177e20da740db",
                "audio": "task/68cdda24d26e4794bae177e20da740db.mp3"
            }
        ],
        "created_at": "2025-09-21T07:36:20.200865Z",
        "updated_at": "2025-09-21T07:36:20.200353Z",
        "languages": [
            "zh"
        ],
        "visibility": "public",
        "lock_visibility": false,
        "default_text": "Дельфіни орієнтуються в океані за допомогою системи ехолокації, ця точна звукова технологія дозволяє їм виявляти навколишнє середовище, шукати їжу та уникати небезпеки. Це не лише демонструє адаптаційні можливості морських істот, але й розкриває чудовий дизайн природи.",
        "like_count": 0,
        "mark_count": 0,
        "shared_count": 0,
        "task_count": 0,
        "unliked": false,
        "liked": false,
        "marked": false,
        "author": {
            "_id": "7ecad23df62a4174acd6a2a6cb5201ee",
            "nickname": "Matthew Garcia",
            "avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
        }
    }
}
Можна побачити, що в результаті є поле task_id, інші поля схожі на наведені вище, через це поле можна реалізувати зв’язок завдань.

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

При виклику 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 Voices Generation API, щоб створити свій власний голосовий тон через підключення аудіо. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої технічної підтримки.