Skip to content
Lumean API
GET/voices/fishaudio

Fish Audio Voices

The voice catalogue of the Fish Audio text-to-speech service: active voices, filterable by language (ru, en, es), gender (male/female) and a search string. Put the voice_id from the response (a 32-character hex string, not a UUID) into tts_settings.voice_id of a template with service_key: fishaudio; the voice_id parameter finds one voice by its exact id — the name of a voice already chosen in a template.

voices.read

Your own cloned voice does not show up in the catalogue — its voice_id comes from GET /voices/fishaudio/clones (only once the clone is ready).

If the service is closed to the key owner (closed testing), the answer is 404 with reason: service_not_found.

Required key permission: voices.read.

On this page(3)

Parameters

The inputs live inside the request line: fill in a value and you get a ready URL. Below are the type, whether it is required and the allowed values of every parameter.

GEThttps://api.lumean.app/api/public/voices/fishaudio
  • stringin queryoptional≤ 16 chars

    Catalogue language: ru, en or es.

  • stringin queryoptional≤ 32 chars

    Voice gender: male or female.

  • stringin queryoptional≤ 255 chars

    Search by voice name and description.

  • stringin queryoptional≤ 255 chars

    Exact voice voice_id — look up the name and preview of a voice already chosen in a template without paging through the catalogue. A voice withdrawn from the catalogue is not returned: the list is empty.

  • integerin queryoptional≥ 1

    Page number, starting at 1.

  • integerin queryoptional1..200

    How many records to return per page. Pagination metadata sits next to items: current_page, last_page, per_page, total.

Possible responses

200

Success. The payload is in data.

Body example
{
  "success": true,
  "message": "Success",
  "data": {
    "items": [
      {
        "id": 31,
        "voice_id": "8ef4a238714b45718ce04243307c57a7",
        "name": "Russian Narrator",
        "description": "Calm male narrator.",
        "language": "ru",
        "languages": [
          "ru"
        ],
        "gender": "male",
        "tags": [
          "male",
          "narration"
        ],
        "author_name": "Fish",
        "task_count": 120450,
        "like_count": 380,
        "preview_url": "https://s3.example.com/fishaudio/voice-previews/8ef4a238714b45718ce04243307c57a7.mp3?X-Amz-Expires=3600"
      },
      {
        "id": 32,
        "voice_id": "5c3a9e1b7d2f4086a1b4e0c9d8f72a63",
        "name": "Warm Storyteller",
        "description": null,
        "language": "en",
        "languages": [
          "en",
          "es"
        ],
        "gender": "female",
        "tags": [
          "female"
        ],
        "author_name": null,
        "task_count": 8120,
        "like_count": 54,
        "preview_url": null
      }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 50,
    "total": 2
  }
}
Response fields
successrequired

Success flag. Branch on the HTTP status code instead: any 2xx response carries true here, while an error comes back in a different shape that need not contain this field at all.

boolean
messagerequired

A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code.

string
datarequired

The response payload.

object
itemsrequired

Fish Audio catalogue voices on this page.

array<FishAudioVoice>FishAudioVoice
array item
idrequired

Internal id of the catalogue entry. Not needed for narration — voice_id goes into the template.

string
voice_idrequired

The Fish Audio voice id (a 32-character hex string, not a UUID) — the value for tts_settings.voice_id of a template with service_key: fishaudio.

string
namerequired

Voice name.

string
descriptionrequired

Voice description from Fish Audio, or null.

string
languagerequired

Catalogue language the voice was imported under (ru, en, es), or null.

string
languagesrequired

All languages of the voice according to Fish Audio.

string | array<string>
genderrequired

Voice gender: male, female, or null.

string
tagsrequired

Voice tags at Fish Audio.

string | array<string>
author_namerequired

Voice author at Fish Audio, or null.

string
task_countrequired

How many times the voice has been used at Fish Audio — a popularity measure; the catalogue is sorted by it.

integer
like_countrequired

Number of likes of the voice at Fish Audio.

integer
preview_urlrequired

A temporary link (60 minutes) to an MP3 sample of the voice, or null while the preview has not been downloaded yet.

string
current_pagerequired

Current page number, starting from one.

integer
last_pagerequired

Number of the last page.

integer
per_pagerequired

Page size the server applied.

integer
totalrequired

Total number of records matching the filter.

integer
401

The key is missing, unknown, disabled or expired.

Analyse this response
Body example
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

Error text in the key's language (set through the X-Locale header).

string
datarequired

Always null when the request is rejected before processing.

nullable
null
403

The key lacks the voices.read permission.

Analyse this response
Body example
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

Error text in the key's language (set through the X-Locale header).

string
404

The Fish Audio service is closed to the key owner (reason: service_not_found).

Analyse this response
Body example
{
  "success": false,
  "message": "Service not found.",
  "reason": "service_not_found",
  "error_code": "service_not_found"
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.

string
reasonrequired

Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.

string
error_coderequired

The same machine-readable code as in reason — a second name for the field. The values always match.

string
422

Validation error, for example per_page above 200. Offending fields are listed in errors.

Analyse this response
Body example
{
  "message": "string",
  "errors": {}
}
Response fields
messagerequired

Errors overview.

string
errorsrequired

A detailed description of each field that failed validation.

object
*optional
arbitrary keys
array<string>

Nearby

Neighbouring operations

Feed this page to an AI

Open .mdllm.md

spec 0.0.1