Fish Model Query API Integración

Esta interfaz se basa en la API Model de Fish Audio y se utiliza para buscar de forma paginada en la biblioteca de voces públicas de Fish o en las voces clonadas de la cuenta actual. La dirección es GET https://api.acedata.cloud/fish/model.

Para crear voces, consulte la API Fish Model Create; para consultar los detalles de una sola voz por _id, consulte la API Fish Model Get.

Proceso de Solicitud

Para usar la API Fish Model, primero dirígete a la consola de Ace Data Cloud para obtener tu API Token, que debes guardar como respaldo.

Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión; una vez completado, volverás automáticamente a la página actual. Un API Token es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio. La primera solicitud incluirá un crédito gratuito para que puedas probarlo; si el crédito es insuficiente, puedes recargar el saldo general en la consola.

📘 Documentación completa: API Fish Model →

Parámetros de Consulta

Parámetro	Tipo	Predeterminado	Descripción
`page_size`	integer	10	Número de elementos por página.
`page_number`	integer	1	Número de página comenzando desde 1.
`title`	string	—	Búsqueda difusa por título.
`tag`	string	—	Filtrar por una sola etiqueta.
`self`	boolean	—	Si es `true`, solo devuelve las voces creadas por la cuenta actual, sin condiciones adicionales.
`author_id`	string	—	Filtrar por el `_id` del usuario superior.
`language`	string	—	Filtrar por el idioma de la voz, como `en`, `zh`, `es`.
`title_language`	string	—	Filtrar por el idioma del título.
`sort_by`	string	—	Campo de ordenación, igual que en el superior, como `created_at`, `task_count`.

La nomenclatura de los parámetros es idéntica a la de GET https://api.fish.audio/model, consulte la documentación oficial de Fish.

Ejemplo 1: Paginación por defecto (por `page_size`)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=2'

Respuesta (prueba real, el total de la biblioteca pública es de aproximadamente 1.8 millones; se han omitido algunos campos largos para mayor legibilidad):

{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "Una voz masculina madura y autoritaria con un tono calmado y espiritual...",
      "cover_image": "coverimage/8d2c17a9b26d4d83888ea67a1ee565b2",
      "train_mode": "fast",
      "state": "trained",
      "tags": ["male", "old", "narration", "calm", "Spanish"],
      "samples": [
        {
          "title": "Muestra por Defecto",
          "text": "Hermanos míos, recordemos las palabras del Señor...",
          "task_id": "59ce7df6935c42249759327ddf70f37b",
          "audio": "https://platform.r2.fish.audio/task/59ce7df6935c42249759327ddf70f37b.mp3"
        }
      ],
      "languages": ["es"],
      "visibility": "public",
      "like_count": 4344,
      "task_count": 708461,
      "author": {
        "_id": "1b82fb6a329c4462b67aa9ee0a42046f",
        "nickname": "Fernando Caicedo"
      }
    },
    {
      "_id": "90e65eaaf50e4470b8e6d43ee6afd7d5",
      "type": "tts",
      "title": "Super Smash Bros. 4/Ultimate Announcer",
      "tags": ["male", "old", "announcer", "gaming", "cinematic"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

Ejemplo 2: Búsqueda difusa por título (`title`)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'title=narration' \
  --data-urlencode 'page_size=2'

Respuesta (prueba real):

{
  "total": 161,
  "items": [
    {
      "_id": "fb8fe4a94658429d9be70efd4eec35a2",
      "type": "tts",
      "title": "Miles Morales ( Narration Paw )",
      "tags": ["male", "middle-aged", "entertainment", "storytelling", "Children's Content"],
      "languages": ["en"],
      "visibility": "public",
      "task_count": 770
    },
    {
      "_id": "76b55591c758444cb95253708696dfad",
      "type": "tts",
      "title": "Joe NARRATION",
      "tags": ["male", "middle-aged", "narration", "deep", "raspy"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

Nota: title es una “coincidencia difusa global”, que capturará todas las voces en la biblioteca pública de Fish (no solo las propias).

Ejemplo 3: Listar solo las voces creadas por uno mismo (`self=true`)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'self=true' \
  --data-urlencode 'page_size=5'

Respuesta (prueba real, actualmente solo hay 1 voz en la cuenta):

{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "prueba de humo desde api.acedata.cloud",
      "state": "trained",
      "languages": ["zh"],
      "visibility": "public",
      "samples": [
        {
          "title": "Muestra por Defecto",
          "text": "师父，[语气坚定]我真的受够了这山上的清冷日子！...",
          "task_id": "6a1bf398dfae49dca0e23159214342a0",
          "audio": "https://platform.r2.fish.audio/task/6a1bf398dfae49dca0e23159214342a0.mp3"
        }
      ],
      "created_at": "2026-05-10T03:52:55.601000Z",
      "author": {
        "_id": "780f2b2f862d41a08c0507bbbda77eb6",
        "nickname": "Penny Conrad"
      }
    }
  ],
  "has_more": null
}

self=true es equivalente a filtrar author_id == ID superior de la cuenta actual, es una entrada común para “mi lista de voces”.

Ejemplo 4: Filtrar por idioma + etiqueta

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'language=zh' \
  --data-urlencode 'tag=narration' \
  --data-urlencode 'page_size=5'

El upstream también devolverá resultados para tag que no están en el diccionario de etiquetas, pero la coincidencia es relativamente laxa; si el número de coincidencias es 0, se sugiere usar coincidencias difusas con title.

Campos de respuesta

Cada elemento en items[] es un objeto completo ModelEntity, campos comunes:

Campo	Tipo	Descripción
`_id`	string	ID de tono, como valor de `reference_id` en `/fish/tts`.
`type`	string	Tipo de modelo, generalmente `tts`.
`title`	string	Nombre del tono.
`description`	string	Descripción del tono.
`state`	string	Estado de entrenamiento: `trained` indica que está disponible.
`tags`	string[]	Etiquetas de la biblioteca pública.
`languages`	string[]	Idiomas en los que el tono es experto.
`visibility`	string	`public` o `private`.
`samples`	object[]	Muestras preestablecidas (incluye enlaces directos de `audio`).
`like_count`	integer	Número de “me gusta” en la biblioteca pública.
`task_count`	integer	Número de síntesis históricas.
`author`	object	Información del autor upstream: `_id` / `nickname` / `avatar`.
`total` (nivel superior)	integer	Número total de elementos que cumplen con los criterios.
`has_more`	boolean?	Indicador de paginación upstream, puede ser `null`. Se sugiere calcular el número total de páginas usando `total / page_size`.

Descripción de facturación

Esta interfaz no tiene costo: la consulta paginada de la lista de tonos es una operación gratuita. La creación de tonos (Fish Model Create) también es gratuita, los costos solo se generan al llamar a Fish TTS para sintetizar voz según el uso.

Manejo de errores

400 token_mismatched: Falta o es inválido un parámetro de solicitud.
401 invalid_token: El token de autenticación no existe o es inválido.
429 too_many_requests: Se ha activado 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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusión

Para seleccionar un tono de la biblioteca pública de Fish para alimentar el reference_id de /fish/tts, primero use esta interfaz junto con title / tag / language para buscar, localizar el _id objetivo, y luego use Fish Model Get para obtener muestras de audio. Para listar los tonos que ha creado, simplemente pase self=true.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Proxy

Avanzado

Coding

Fish Model Query API Integración

Proceso de Solicitud

Parámetros de Consulta

Ejemplo 1: Paginación por defecto (por `page_size`)

Ejemplo 2: Búsqueda difusa por título (`title`)

Ejemplo 3: Listar solo las voces creadas por uno mismo (`self=true`)

Ejemplo 4: Filtrar por idioma + etiqueta

Campos de respuesta

Descripción de facturación

Manejo de errores

Conclusión

​Proceso de Solicitud

​Parámetros de Consulta

​Ejemplo 1: Paginación por defecto (por page_size)

​Ejemplo 2: Búsqueda difusa por título (title)

​Ejemplo 3: Listar solo las voces creadas por uno mismo (self=true)

​Ejemplo 4: Filtrar por idioma + etiqueta

​Campos de respuesta

​Descripción de facturación

​Manejo de errores

​Conclusión

Proceso de Solicitud

Parámetros de Consulta

Ejemplo 1: Paginación por defecto (por `page_size`)

Ejemplo 2: Búsqueda difusa por título (`title`)

Ejemplo 3: Listar solo las voces creadas por uno mismo (`self=true`)

Ejemplo 4: Filtrar por idioma + etiqueta

Campos de respuesta

Descripción de facturación

Manejo de errores

Conclusión