Instrucciones de integración de Fish Model Query API

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

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

Proceso de solicitud

Para usar Fish Model API, primero vaya a la consola de Ace Data Cloud para obtener su API Token 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, volverá automáticamente a la página actual. Un solo API Token puede invocar todos los servicios de la plataforma, sin necesidad de solicitarlo por separado para cada servicio. La primera solicitud incluirá crédito gratuito, permitiendo una experiencia gratuita; cuando el crédito sea insuficiente, puede recargar saldo general en la consola.

📘 Documentación completa: Fish Model API →

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 a partir de 1.
`title`	string	—	Búsqueda difusa por título.
`tag`	string	—	Filtrar por una sola etiqueta.
`self`	boolean	—	Cuando es `true`, solo devuelve las voces creadas y guardadas a través de esta plataforma por la cuenta de invocación actual.
`author_id`	string	—	Filtrar por el ID del autor de la voz.
`language`	string	—	Filtrar por idioma de la voz, como `en`, `zh`, `es`.
`title_language`	string	—	Filtrar por idioma del título en la biblioteca pública de voces.
`sort_by`	string	—	Campo de ordenación; cuando `self=true`, admite `created_at`, `task_count`.

Los nombres de los parámetros son completamente consistentes con el upstream GET https://api.fish.audio/model; consulte la documentación oficial de Fish para más detalles.

Ejemplo 1: paginación predeterminada (por `page_size`)

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

Respuesta (probado; el total de la biblioteca pública es de aproximadamente 1,8 millones de elementos; para facilitar la lectura, se omiten algunos campos largos en el siguiente ejemplo):

{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "A mature and authoritative male voice with a calm, spiritual tone...",
      "cover_image": "coverimage/8d2c17a9b26d4d83888ea67a1ee565b2",
      "train_mode": "fast",
      "state": "trained",
      "tags": ["male", "old", "narration", "calm", "Spanish"],
      "samples": [
        {
          "title": "Default Sample",
          "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 (probado):

{
  "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
}

Tenga en cuenta que title es una «coincidencia difusa global» y coincidirá simultáneamente con todas las voces de 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'

Ejemplo de respuesta:

{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "smoke test from api.acedata.cloud",
      "state": "trained",
      "languages": ["zh"],
      "visibility": "public",
      "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",
      "author": {
        "_id": "780f2b2f862d41a08c0507bbbda77eb6",
        "nickname": "Penny Conrad"
      }
    }
  ],
  "has_more": false
}

self=true enumera, según la cuenta de llamada real, las voces creadas y guardadas a través de esta plataforma; las voces creadas por la misma cuenta usando diferentes API Token también se enumerarán juntas. Los resultados se paginan en orden descendente por hora de creación, y author_id puede filtrar adicionalmente el ID del autor de estas voces. Este parámetro solo filtra la lista; las voces siguen estando disponibles públicamente. self=true no admite title_language; si necesita buscar por idioma del título, consulte la biblioteca pública 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é en el diccionario de etiquetas, pero la coincidencia será relativamente flexible; si el número de coincidencias es 0, se recomienda usar la coincidencia difusa de title.

Campos de respuesta

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

Campo	Tipo	Descripción
`_id`	string	ID de voz, como valor de `reference_id` en `/fish/tts`.
`type`	string	Tipo de modelo, normalmente `tts`.
`title`	string	Nombre de la voz.
`description`	string	Descripción de la voz.
`state`	string	Estado de entrenamiento: `trained` indica que está disponible.
`tags`	string[]	Etiquetas de la biblioteca pública.
`languages`	string[]	Idiomas en los que la voz destaca.
`visibility`	string	`public` o `private`.
`samples`	object[]	Muestras preestablecidas (incluyen enlace directo 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 de la voz: `_id` / `nickname` / `avatar`.
`total`（nivel superior）	integer	Número total de elementos que cumplen las condiciones.
`has_more`	boolean?	Es un valor booleano cuando `self=true`; las consultas de la biblioteca pública de voces pueden ser `null`.

Descripción de facturación

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

Manejo de errores

400 token_mismatched: faltan parámetros de la solicitud o no son válidos.
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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusión

Para seleccionar una voz de la biblioteca pública de Fish y proporcionarla como reference_id de /fish/tts, primero use esta interfaz junto con title / tag / language para buscar, ubique el _id objetivo y luego use Fish Model Get para obtener muestras y escucharlas. Para enumerar las voces que creó usted mismo, simplemente pase self=true.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Coding

Más guías

Instrucciones de integración de Fish Model Query API

Proceso de solicitud

Parámetros de consulta

Ejemplo 1: paginación predeterminada (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 predeterminada (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 predeterminada (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