Saltar al contenido principal
Este documento presentará una descripción de la integración de la API de Generación de Voces de Pescado, que permite crear su propio tono a través de un enlace de audio de entrada.

​
Proceso de Solicitud

Para utilizar la API, primero debe ir a la página correspondiente de API de Generación de Voces de Pescado para solicitar el servicio correspondiente. Una vez en la página, haga clic en el botón “Acquire”, como se muestra en la imagen: Si aún no ha iniciado sesión o registrado, será redirigido automáticamente a la página de inicio de sesión que lo invita a registrarse e iniciar sesión. Después de iniciar sesión o registrarse, será redirigido automáticamente a la página actual. En la primera solicitud, se otorgará un límite gratuito que permite usar la API de forma gratuita.

​
Uso Básico

Primero, comprenda la forma básica de uso, que consiste en ingresar el enlace de audio del tono voice_url, y podrá obtener el resultado procesado. El contenido específico es el siguiente:

Aquí podemos ver que hemos configurado los Encabezados de Solicitud, que incluyen:
  • accept: el formato de respuesta que desea recibir, aquí se llena como application/json, es decir, en formato JSON.
  • authorization: la clave para llamar a la API, que se puede seleccionar directamente después de la solicitud.
Además, se configuró el Cuerpo de Solicitud, que incluye:
  • voice_url: el enlace de audio del tono subido.
  • title: la información del título de este tono.
  • image_urls: la imagen de portada de este tono.
  • description: la información de descripción de este tono.
  • callback_url: la URL donde se necesita el resultado de la llamada.
Después de seleccionar, se puede observar que también se generó el código correspondiente a la derecha, como se muestra en la imagen:

Haga clic en el botón “Try” para realizar la prueba, como se muestra en la imagen anterior, y aquí obtuvimos el siguiente resultado: 
{
  "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": "A través de una observación a largo plazo, se ha descubierto que los peces en el ecosistema de los arrecifes de coral tienen patrones de comportamiento social complejos. Utilizan cambios de color y posturas de nado específicas para transmitir información, y este sistema de comunicación no verbal preciso muestra la sabiduría adaptativa de los organismos marinos.",
        "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": "A través de una observación a largo plazo, se ha descubierto que los peces en el ecosistema de los arrecifes de coral tienen patrones de comportamiento social complejos. Utilizan cambios de color y posturas de nado específicas para transmitir información, y este sistema de comunicación no verbal preciso muestra la sabiduría adaptativa de los organismos marinos.",
    "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"
    }
  }
}
El resultado devuelto tiene varios campos, que se describen a continuación:
  • success, el estado de la tarea de creación del tono en este momento.
    • data, el resultado de la tarea musical
      • _id, el ID de la tarea de generación de tono en este momento, que se utilizará posteriormente para clonar la creación de sonido.
      • title, el título del tono.
      • image_url, la información de la portada del tono.
      • description, la información de descripción del tono.
      • train_mode, el modo utilizado para la tarea de generación de tono en este momento.
      • tags, el estilo del tono.
      • default_text, la información del texto de sonido de la tarea de generación de tono en este momento.
Podemos ver que hemos obtenido información de tono satisfactoria, y solo necesitamos realizar la tarea de clonación de sonido según el id de data en el resultado. Además, si desea generar el código de integración correspondiente, puede copiarlo directamente, por ejemplo, el código de CURL es el siguiente: 
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"
}'

​
Callback Asíncrono

Dado que el tiempo de generación de la API de Generación de Voces de Pescado es relativamente largo, aproximadamente de 1 a 2 minutos, si la API no responde durante mucho tiempo, la solicitud HTTP mantendrá la conexión, lo que provocará un consumo adicional de recursos del sistema. Por lo tanto, esta API también ofrece soporte para callbacks asíncronos. El proceso general es: cuando el cliente inicia la solicitud, debe especificar un campo callback_url adicional. Después de que el cliente inicie la solicitud a la API, la API devolverá inmediatamente un resultado que incluye un campo de información task_id, que representa el ID de la tarea actual. Cuando la tarea se complete, el resultado de la tarea generada se enviará a la callback_url especificada por el cliente en formato JSON POST, que también incluirá el campo task_id, de modo que el resultado de la tarea se pueda asociar mediante el ID. A continuación, utilizaremos un ejemplo para comprender cómo operar específicamente. Primero, el callback de Webhook es un servicio que puede recibir solicitudes HTTP, y el desarrollador debe reemplazarlo con la URL de su propio servidor HTTP. Aquí, para facilitar la demostración, utilizamos un sitio web de ejemplo de Webhook público https://webhook.site/, al abrir este sitio se obtiene una URL de Webhook, como se muestra en la imagen: Copie esta URL y podrá usarla como Webhook, el ejemplo aquí es https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34. A continuación, podemos establecer el campo callback_url como la URL de Webhook mencionada anteriormente, al mismo tiempo que ingresamos los parámetros correspondientes, el contenido específico es como se muestra en la imagen:

Haga clic en ejecutar, y podrá ver que se obtiene inmediatamente un resultado, como el siguiente: 
{
  "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": "Los delfines navegan en el océano a través de un sistema de ecolocalización, esta precisa tecnología de ondas sonoras les permite detectar su entorno, buscar comida y evitar peligros. Esto no solo muestra la capacidad de adaptación de la vida marina, sino que también revela el maravilloso diseño de la naturaleza.",
                "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": "Los delfines navegan en el océano a través de un sistema de ecolocalización, esta precisa tecnología de ondas sonoras les permite detectar su entorno, buscar comida y evitar peligros. Esto no solo muestra la capacidad de adaptación de la vida marina, sino que también revela el maravilloso diseño de la naturaleza.",
        "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：Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 400 api_not_implemented：Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 401 invalid_token：No autorizado, token de autorización inválido o faltante.
  • 429 too_many_requests：Demasiadas solicitudes, ha superado el límite de tasa.
  • 500 api_error：Error interno del servidor, algo salió mal en el servidor.

​
错误响应示例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
结论

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