Get a voice

Fetch a single voice by id.

GET /flam-voice-svc/api/v1/public/voices/{id}

Get a voice

cURL

curl --request GET \
  --url https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/voices/{id} \
  --header 'X-API-Key: <api-key>'

200

{
  "data": {}
}

Returns a single Voice object. The voice must belong to the API key’s workspace, otherwise the request returns 404.

Authorization

X-API-Key · string · required

Your workspace API key (flv_…).

Path parameters

id · string · required

The voice id (a 24-character hex string).

Response

data · Voice

The Voice object.

cURL

curl "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/voices/665f1a2b3c4d5e6f7a8b9c0d" \
  -H "X-API-Key: $FLAM_API_KEY"

Response

{
  "status": 200,
  "data": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "name": "Studio Narrator",
    "status": "ready",
    "primary_language": "en",
    "visibility": "public",
    "clone_method": "instant",
    "labels": [{ "key": "accent", "value": "american" }]
  },
  "error": false
}

Prompt

Copy this into your coding agent (Claude Code, Cursor, Codex…) to implement this endpoint.

You are implementing a typed client for one Finesse Voice API endpoint: "Get a voice".
Everything you need is in this prompt. Do not invent anything that is not specified here.

WHAT TO BUILD
- A function getVoice(id) (name it per the project's conventions) that fetches one voice by id and
  returns it as a typed Voice object.
- Detect the stack first: look for package.json, tsconfig.json, pyproject.toml,
  requirements.txt, go.mod, Gemfile, composer.json and similar. Use the project's language, HTTP
  client, module layout, error-handling conventions and test runner. If there is no project yet or
  the stack is unclear, use TypeScript on Node 18+ with the built-in fetch and no new dependencies.
- If the project already has a Finesse API client module, add this to it (reuse its auth, base
  URL, error type and retry helper) instead of creating a parallel one.
- Keep the base URL (https://fi.production.flamapis.com) in one constant or config value.

ENDPOINT
- Method: GET
- URL: https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/voices/{id}

PARAMETERS
- id (path, string, required): the voice id, a 24-character hex string (for example
  "665f1a2b3c4d5e6f7a8b9c0d"). Validate it locally against /^[0-9a-f]{24}$/i and URL-encode it.
- No query or body parameters.

AUTHENTICATION
- Send the header  X-API-Key: <workspace API key>  on every request. Keys start with "flv_".
- Read the key from the environment variable FLAM_API_KEY (or the project's existing secrets or
  config mechanism). Fail fast with a clear error if it is missing, before making any request.
- Never hard-code, log or commit the key, and never ship it in browser/client-side code: call this
  from server-side code only. The key can synthesize with every voice in its workspace.
- A key is bound to one workspace. Referencing a voice or job from another workspace returns 404.

RESPONSE ENVELOPE
JSON responses use one envelope. On success "error" is false and the payload is in "data":

    {
      "status": 200,
      "data": { "...": "endpoint payload" },
      "error": false
    }

On failure "error" is true, "data" is omitted and "message" carries the detail:

    {
      "status": 404,
      "error": true,
      "message": "Voice not found"
    }

SUCCESS RESPONSE (200, application/json)
"data" is the Voice object itself:

    {
      "status": 200,
      "data": {
        "id": "665f1a2b3c4d5e6f7a8b9c0d",
        "name": "Studio Narrator",
        "status": "ready",
        "primary_language": "en",
        "visibility": "public",
        "clone_method": "instant",
        "labels": [{ "key": "accent", "value": "american" }]
      },
      "error": false
    }

VOICE OBJECT (define a type for it; timestamps are Unix epoch MILLISECONDS)
- id: string. Unique voice id, 24-character hex. Used by the synthesize endpoints.
- name: string. Display name.
- description: string, optional.
- status: string. Only "ready" voices can synthesize. A voice being created reports "processing",
  "failed" if creation did not succeed, and a newly created voice with no audio yet is "draft".
  Type it as a string union of these values but tolerate other strings (treat them as not usable).
- clone_method: "instant" | "professional" | "design" | "remix".
- visibility: "private" | "org" | "public".
- primary_language: string, BCP-47 (e.g. "en"). Used when a synthesis request omits language.
- labels: array of { key: string, value: string }, optional. Common keys: accent, gender, age,
  use_case. Example: [{ "key": "accent", "value": "american" }]
- settings: object, optional, present only when configured. Synthesis defaults: stability,
  similarity, style, speed, pitch, volume, use_speaker_boost, emotion, engine_params.
- sample_audio_url: string, optional. Public URL of a short preview clip.
- base_voice_id: string, optional. Present when derived from another voice (clone_method "remix").
- created_at, updated_at: integers (epoch ms).
Optional fields may be absent. Responses may contain extra fields: ignore them, never fail on them.

Example:

    {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "name": "Studio Narrator",
      "description": "Warm, neutral narration voice.",
      "status": "ready",
      "clone_method": "instant",
      "visibility": "public",
      "primary_language": "en",
      "labels": [
        { "key": "accent", "value": "american" },
        { "key": "gender", "value": "female" }
      ],
      "sample_audio_url": "https://storage.googleapis.com/.../sample.wav",
      "created_at": 1717939200000,
      "updated_at": 1717939260000
    }

ERRORS
- 401: X-API-Key missing, malformed, invalid or revoked. Do not retry.
- 404: the voice does not exist or belongs to another workspace. Throw a not-found error (or
  return null, if that is the project's convention for lookups); do not retry.
- 429: rate limited. Retry with backoff.
- 502: upstream temporarily unavailable. Retry with backoff.
- Surface failures as one typed error (for example FinesseApiError) carrying: HTTP status, message
  (the envelope "message" or the flat "error" string), optional feature / unit / limit / used, a
  retryable flag, and the raw body for debugging.
- Parse error bodies defensively: if a body is not valid JSON, keep the raw text in the error.

RETRIES
- Retry only 429 (rate limited), 502 (provider unavailable or warming up) and network errors or
  timeouts, with exponential backoff plus jitter (for example about 1s, 2s, 4s; at most 3 retries),
  then surface the error.
- Never retry 400, 401, 402, 403, 404 or 422: they fail the same way again.

ACCEPTANCE CRITERIA
- getVoice(id) validates the id locally, sends GET to the exact URL with the X-API-Key header, and
  returns the typed Voice from "data".
- 404 is distinguishable from other failures; 401 is never retried; 429/502 are retried.
- A missing FLAM_API_KEY fails before any network call. The key is never logged.

TEST PLAN
- Unit tests with mocked HTTP: 200 returns a Voice; 404 envelope becomes a not-found error; 401;
  429 then 200 (retry); an invalid id (for example "abc") is rejected without a network call.
- Smoke script: read FLAM_API_KEY and a voice id from FLAM_VOICE_ID (or take the first id returned
  by GET https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/voices, whose voices are in data.voices), call getVoice, print name,
  status and labels, exit non-zero on error.

RULES
- Implement only what this spec describes. Do not invent parameters, fields, headers, endpoints or
  error codes. If something is ambiguous, missing, or conflicts with the existing codebase, stop
  and ask me before guessing.
- Match the project's existing style and conventions; do not refactor unrelated code.