Voices — Finn docs

Beta. Every endpoint on this page is live and documented as shipped. Shapes can still change before general availability.

Overview

The Voices API is a read-only catalog of every voice your organization can give a Finn. Use it to find a voice_id, then pass it as voice when you create or update a Finn. See api-finns.

Base URL: https://api.hirefinn.ai/api/v1. Auth: Authorization: Bearer finn_live_.... See authentication.

GET /voices returns the voices of every voice provider your plan includes, merged into one list: the same voices as the voice picker in the dashboard. You never choose a provider: setting a Finn's voice is enough, and Finn sets everything else up for that voice.

Your organization may be limited to one voice provider. Then only that provider's voices are listed and accepted.

Endpoints

Method	Path	Rate limit (per API key)
`GET`	`/voices`	60 per minute, shared with `GET /voices/{voice_id}`
`GET`	`/voices/{voice_id}`	Same bucket

Catalog lookups call the providers, so this limit is lower than other reads. Cache the results on your side.

The voice object

Field	Type	Notes
`voice_id`	string	Pass this as `voice` on a Finn.
`name`	string or null	Display name.
`description`	string	Empty string when the provider has none.
`preview_url`	string or null	Audio sample URL, when the provider offers one.
`category`	string or null	Provider category, for example `premade`.
`labels`	object	Provider tags such as accent, gender or age. Empty object when there are none.
`languages`	string[]	Languages the provider has verified for the voice. Often empty for providers that do not report them.

List voices

GET /voices

Query parameter	Type	Default	Notes
`search`	string	none	Up to 100 characters. Filters every provider's voices by name, voice ID or description.

curl "https://api.hirefinn.ai/api/v1/voices?search=rachel" \
  -H "Authorization: Bearer $FINN_API_KEY"

{
  "success": true,
  "data": [
    {
      "voice_id": "21m00Tcm4TlvDq8ikWAM",
      "name": "Rachel",
      "description": "Calm, young American female voice.",
      "preview_url": "https://example.com/voices/rachel-preview.mp3",
      "category": "premade",
      "labels": { "accent": "american", "gender": "female", "age": "young" },
      "languages": ["en"]
    }
  ]
}

The list is not paginated: the whole result comes back in one response. Narrow it with search. A voice ID offered by more than one provider appears once.

If one provider's catalog can't be loaded, the request still succeeds with the voices of the others, so a voice can be missing from one response and back in the next. If no catalog can be loaded, the request returns 502 voices_unavailable.

Retrieve a voice

GET /voices/{voice_id}

Parameter	In	Notes
`voice_id`	path	1 to 128 characters of letters, digits, `_`, `:`, `.` and `-`.

curl "https://api.hirefinn.ai/api/v1/voices/21m00Tcm4TlvDq8ikWAM" \
  -H "Authorization: Bearer $FINN_API_KEY"

Returns { "success": true, "data": { ... } } with one voice object, from whichever provider has it. Some providers have more voices than their list shows, so this can find a voice that GET /voices didn't return.

Finn writes check voice the same way: a voice this endpoint finds is accepted on POST /finns and PATCH /finns/{finn_id}; a voice it can't find returns 400 invalid_request (voice is not one of the voices from GET /voices).

Errors

Status	`error`	When
400	`invalid_request`	`search` is longer than 100 characters, or `voice_id` has invalid characters.
401	`api_key_required`	No `Bearer finn_live_...` key.
401	`invalid_api_key`	Key unknown or revoked.
403	`feature_not_allowed`	Your plan includes no voice provider. Upgrade at `action_url`.
404	`voice_not_found`	`GET /voices/{voice_id}` only: none of your organization's voice providers has a voice with that ID.
429	`rate_limited`	More than 60 voice lookups per minute on this key.
500	`internal_error`	Unexpected server error.
502	`voices_unavailable`	No voice catalog could be loaded, or, for `GET /voices/{voice_id}`, the voice wasn't found while a catalog was unavailable. Retry later. Also returned when your organization is limited to a voice provider whose voices can't be listed through the API; retrying doesn't help then, and a Finn's `voice` is saved without being checked.

Error bodies have the shape { "error": "...", "message": "..." }; internal_error has no message. See api-errors.