Guía de integración de la API Fish Model Create

Esta API se basa en la API oficial de modelos de Fish Audio y se utiliza para crear un modelo de voz clonada reutilizable a largo plazo basado en una muestra de audio. La dirección es POST https://api.acedata.cloud/fish/model.

Cuando solo necesite usar temporalmente una voz de referencia, no es necesario crear un modelo; puede usar directamente la clonación instantánea única mediante references de la API Fish TTS. Para recuperar voces existentes mediante paginación, consulte la API Fish Model Query; para consultar los detalles de una sola voz por _id, consulte la API Fish Model Get.

Proceso de solicitud

Para utilizar la API Fish Model, primero obtenga su API Token en la consola de Ace Data Cloud y guárdelo como respaldo.

Si aún no ha iniciado sesión o no se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al completarlo, regresará automáticamente a la página actual. Un solo API Token puede invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio. La primera solicitud incluye una cuota gratuita para probar el servicio sin coste; cuando la cuota sea insuficiente, puede recargar saldo general en la consola.

📘 Documentación completa: Fish Model API →

Campos del cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`title`	string	Sí	Nombre de la voz, utilizado para identificarla en la lista de la consola.
`voices`	string	Sí	URL HTTP(S) de la muestra de audio (una sola cadena, no un array). Esta API no admite cargas multipart/binarias; primero coloque el audio en cualquier almacenamiento de objetos de acceso público.
`description`	string	No	Descripción de la voz.
`cover_image`	string	No	URL HTTP(S) de la imagen de portada.
`tags`	string[]	No	Etiquetas de búsqueda de la biblioteca pública, por ejemplo `["male","narration","zh"]`.
`texts`	string[]	No	Textos de referencia correspondientes a las muestras (para corregir la pronunciación).
`enhance_audio_quality`	boolean	No	Si se debe mejorar la calidad de audio de la muestra antes del entrenamiento.
`generate_sample`	boolean	No	Si se debe generar automáticamente un audio de ejemplo después de completar el entrenamiento.

Para obtener más información sobre los modelos de voz, consulte la documentación oficial de Fish.

Las voces creadas se guardarán públicamente a largo plazo, y otros usuarios podrán buscarlas y utilizarlas. No es necesario enviar visibility; incluso si se envía private o unlist, la API actual no cambiará el alcance público en función de ello.

Ejemplo: crear una voz clonada pública

curl -X POST 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "title": "我的克隆音色",
    "description": "用一段播客录音克隆的中文音色",
    "voices": "https://example.com/sample-voice.mp3",
    "cover_image": "https://cdn.acedata.cloud/e724d7f13d.png"
  }'

Nota: voices debe ser una cadena (una sola URL de audio), no un array. Si se envía como ["..."], el servicio ascendente lo rechazará. Se recomienda utilizar un enlace directo de descarga pública con extensión .mp3 o .wav.

La respuesta exitosa devuelve directamente el objeto ModelEntity de la plataforma Fish (el siguiente ejemplo es la voz mínima funcional que hemos probado; se han eliminado algunos campos largos para facilitar la lectura):

{
  "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
  "type": "tts",
  "title": "copilot-smoke-test",
  "description": "smoke test from api.acedata.cloud",
  "cover_image": "coverimage/e5c6db52c3ed417f9cb2e5a33fb04667",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [
    {
      "title": "Default Sample",
      "text": "师父，[语气坚定]我真的受够了这山上的清冷日子！...",
      "task_id": "6a1bf398dfae49dca0e23159214342a0",
      "audio": "https://platform.r2.fish.audio/task/6a1bf398dfae49dca0e23159214342a0.mp3"
    }
  ],
  "created_at": "2026-05-10T03:52:55.601000Z",
  "updated_at": "2026-05-10T03:52:55.601000Z",
  "languages": ["zh"],
  "visibility": "public",
  "default_text": "师父，[语气坚定]我真的受够了这山上的清冷日子！...",
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "author": {
    "_id": "780f2b2f862d41a08c0507bbbda77eb6",
    "nickname": "Penny Conrad",
    "avatar": "avatars/780f2b2f862d41a08c0507bbbda77eb6.jpg"
  }
}

_id puede utilizarse como el valor del campo reference_id en la posterior API Fish TTS, para realizar síntesis de voz utilizando esta voz clonada: Las voces creadas con éxito se guardarán públicamente y se pueden consultar mediante self=true de la API Fish Model Query para obtener las voces creadas por el usuario actual mediante esta plataforma. self=true solo filtra la lista y no restringe que otros usuarios utilicen esta voz.

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "你好，这是一段使用我刚创建的克隆音色合成的语音。",
    "reference_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
    "format": "mp3"
  }'

Requisitos de las muestras

Valores empíricos (coincidentes con el servicio ascendente; puede consultar la documentación oficial de Fish):

Se recomienda una duración de más de 30 segundos, y menos de 5 minutos ofrece los mejores resultados; más de 10 minutos aporta un beneficio marginal reducido.
Frecuencia de muestreo de 16 kHz o superior; puede ser mono o estéreo.
El contenido debe estar lo más limpio posible: sin música de fondo, eco ni ruido ambiental evidente; el mismo hablante.
Se recomiendan los formatos mp3 / wav.

Si no está seguro de la calidad de la muestra, puede enviar simultáneamente enhance_audio_quality: true para que el servicio ascendente realice primero una mejora de calidad de audio.

Información de facturación

Crear un modelo de clonación de voz (POST /fish/model) es gratuito y no se cobra ninguna tarifa; las interfaces de consulta de voz (Fish Model Query, Fish Model Get) tampoco tienen costo. Los cargos solo se generan por uso al llamar posteriormente a Fish TTS para sintetizar voz.

Manejo de errores

400 token_mismatched: los parámetros de la solicitud faltan o no son válidos (lo más común es que voices no sea una URL, o que se haya pasado como un arreglo).
400: cuando el audio de referencia no se puede descargar, la duración es demasiado corta o el formato no se puede reconocer, revise la URL del audio y el formato del archivo.
401 invalid_token: el token de autenticación no existe o no es válido.
429 too_many_requests: se activó el límite de velocidad de la cuenta.
500 api_error: error interno del servidor.

Ejemplo de respuesta de error:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "voices is required and must be an HTTP(S) URL pointing to an audio file"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusión

Para llamar a esta interfaz, solo necesita preparar una URL de audio de muestra accesible públicamente, colocarla en el campo voices para obtener el _id, y luego pasarlo a reference_id de /fish/tts para completar el proceso de extremo a extremo de «clonación → síntesis». Un error común es que voices debe ser una cadena y no puede ser un arreglo.

Crear y reutilizar voces mediante MCP

En Fish MCP, llame a fish_create_model(title="Mi voz", voices="https://example.com/authorized-voice.wav"). voices es una única URL de audio HTTP(S); también se pueden pasar description, cover_image, tags, texts, enhance_audio_quality, generate_sample. Esta herramienta guardará voces públicas a largo plazo, y otros usuarios podrían descubrirlas y utilizarlas; use únicamente materiales de audio cuyo procesamiento y publicación estén autorizados. La herramienta no tiene opciones privadas ni no públicas. El _id devuelto tras una creación exitosa se utiliza para el reference_id de fish_generate_audio, y fish_list_models(self=true) permite consultar las voces guardadas por uno mismo. Cuando solo necesite una voz de referencia de forma puntual, use references de fish_generate_audio, sin necesidad de crear una voz a largo plazo.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Coding

Más guías

Guía de integración de la API Fish Model Create

Proceso de solicitud

Campos del cuerpo de la solicitud

Ejemplo: crear una voz clonada pública

Requisitos de las muestras

Información de facturación

Manejo de errores

Conclusión

Crear y reutilizar voces mediante MCP

​Proceso de solicitud

​Campos del cuerpo de la solicitud

​Ejemplo: crear una voz clonada pública

​Requisitos de las muestras

​Información de facturación

​Manejo de errores

​Conclusión

​Crear y reutilizar voces mediante MCP

Proceso de solicitud

Campos del cuerpo de la solicitud

Ejemplo: crear una voz clonada pública

Requisitos de las muestras

Información de facturación

Manejo de errores

Conclusión

Crear y reutilizar voces mediante MCP