Перейти к основному содержанию
В этой статье будет представлено руководство по интеграции 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, 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 на указанный выше URL Webhook, одновременно заполнив соответствующие параметры, конкретное содержание показано на изображении:

Нажмите «Запустить», и вы сразу получите результат, как показано ниже: 
{
  "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": "тест",
        "description": "тест",
        "cover_image": "coverimage/fa75e7c3f02f42e79a6aa622b6cf075e",
        "train_mode": "быстрый",
        "state": "обучен",
        "tags": [],
        "samples": [
            {
                "title": "Стандартный образец",
                "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": "публичный",
        "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": "Мэттью Гарсия",
            "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": "не удалось получить"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Заключение

通过本文档，您已经了解了如何使用 Fish Voices Generation API 可通过输入音色的音频连接来创建自己的音色。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。