Synthesize speech

Turn text into a single audio file using a cloned voice.

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

Synthesize speech

cURL

curl --request POST \
  --url https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/voices/{id}/speak \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "text": "<string>",
  "language": "<string>",
  "output_format": "<string>",
  "sample_rate": 123,
  "num_step": 123,
  "expressiveness": 123
}
'

200

{
  "Content-Type": "<string>",
  "X-Sample-Rate": "<string>",
  "X-Audio-URL": "<string>",
  "X-Billing-Remaining": "<string>"
}

Synthesizes text with the given voice and returns the raw audio bytes in the response body. The voice must be enrolled (status ready).

Unlike the JSON endpoints, a successful response is the audio file itself - not a JSON envelope. Errors still return the standard envelope.

Authorization

X-API-Key · string · required

Your workspace API key (flv_…).

Path parameters

id · string · required

The voice id.

Body

text · string · required

The text to synthesize. Maximum 10,000 characters. Billed per character against your plan’s monthly allowance; repeating an identical request (same voice, text, and parameters) is served from cache and not billed again.

language · string

BCP-47 language code (for example en, hi). Defaults to the voice’s primary language.

output_format · string · default: "wav"

Output encoding. One of wav, s16le, s24le, s32le, f32le, f64le. wav is a self-contained file; the s*/f* formats are raw, headerless PCM.

sample_rate · integer · default: 24000

Output sample rate in Hz. Defaults to the provider’s native rate (24000); values above it are upsampled.

num_step · integer · default: 32

Number of inference steps, 1–32 (a quality/latency trade-off). Provider default (32) if omitted.

expressiveness · number

Style/expressiveness control, 0.0–1.0. Provider default if omitted.

Response headers

Content-Type · string

The audio MIME type, e.g. audio/wav for output_format: wav.

X-Sample-Rate · string

The sample rate of the returned audio, in Hz (when reported by the provider).

X-Audio-URL · string

A public URL to the stored audio file, when object storage is enabled. Useful for download/share.

X-Billing-Remaining · string

Your remaining character allowance for the month (present when billing is active). An exhausted allowance returns 402 when enforcement is on - see Errors.

cURL

curl -X POST \
  "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/voices/665f1a2b3c4d5e6f7a8b9c0d/speak" \
  -H "X-API-Key: $FLAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from Finesse.","language":"en","output_format":"wav"}' \
  --output speech.wav

See Synthesize parameters for the full field reference.

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: "Synthesize speech".
Everything you need is in this prompt. Do not invent anything that is not specified here.

WHAT TO BUILD
- A function synthesizeSpeech(voiceId, params) (name it per the project's conventions) that turns
  text into ONE audio file with the given voice and returns:
    { audio: bytes, contentType: string, sampleRate?: number, audioUrl?: string,
      billingRemaining?: number }
  Use the stack's natural byte type (Buffer/Uint8Array, bytes, []byte).
- Optionally a thin wrapper that writes the audio to a file path, if the project needs it.
- 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: POST
- URL: https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/voices/{id}/speak
- Request Content-Type: application/json
- The voice must be enrolled (status "ready"), and must belong to the key's workspace.

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.

REQUEST BODY
- text (string, required): the text to synthesize. Maximum 10,000 characters; over the limit
  returns 400 "text too long (max 10000 chars)". Check locally: reject empty text and count
  characters (Unicode code points, not bytes), e.g. [...text].length in JavaScript.
- language (string, optional): BCP-47 code (e.g. "en", "hi", "es"). Defaults to the voice's
  primary_language.
- output_format (string, optional, default "wav"): one of
    wav    - self-contained WAV file (recommended for playback/download)
    s16le  - signed 16-bit little-endian PCM (headerless)
    s24le  - signed 24-bit little-endian PCM (headerless)
    s32le  - signed 32-bit little-endian PCM (headerless)
    f32le  - 32-bit float little-endian PCM (headerless)
    f64le  - 64-bit float little-endian PCM (headerless)
  The headerless PCM formats need a known sample rate and channel count to play.
- sample_rate (integer, optional, default 24000): output rate in Hz. Defaults to the provider's
  native rate (24000); values above it are upsampled.
- num_step (integer, optional, default 32): inference steps, 1-32; a quality vs latency trade-off.
- expressiveness (number, optional): style/expressiveness control, 0.0-1.0. Provider default when
  omitted.
- Validate the enums and ranges locally and omit optional fields the caller did not set.

    {
      "text": "The quick brown fox jumps over the lazy dog.",
      "language": "en",
      "output_format": "wav",
      "sample_rate": 24000,
      "expressiveness": 0.5
    }

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.

SUCCESS RESPONSE (200): RAW AUDIO BYTES, NOT JSON
- The body is the audio file itself. Do not parse it as JSON; read it as binary
  (e.g. await res.arrayBuffer()).
- Check the status BEFORE reading the body: only a 2xx body is audio.
- Response headers to capture:
    Content-Type         the audio MIME type, e.g. audio/wav for output_format "wav"
    X-Sample-Rate        sample rate of the returned audio in Hz (when reported); parse to a number
    X-Audio-URL          public URL of the stored audio file, when object storage is enabled
    X-Billing-Remaining  remaining monthly character allowance, when billing is active
  All of these except Content-Type may be absent: type them as optional.

ERROR RESPONSES (JSON, even though success is binary)
Errors use the standard envelope:

    {
      "status": 400,
      "error": true,
      "message": "Voice is not enrolled yet"
    }

Billing and plan denials do NOT use the envelope. They return a flat JSON body whose "error"
field is a string, not a boolean:

    { "error": "plan limit reached", "feature": "max_voices", "limit": 10 }
    { "error": "quota_exhausted", "unit": "character", "limit": 100000, "used": 100000 }

The "error" string is the denial reason (for example quota_exhausted, insufficient_credits,
limit_reached, feature_disabled, or one of the messages above). Tell the two shapes apart by
checking whether "error" is a boolean (envelope) or a string (flat denial), and expose
feature / unit / limit / used on your error type when present.

- 400: invalid request: missing or invalid field, text over 10,000 characters, or the voice is not
  ready yet ("Voice is not enrolled yet"). Do not retry.
- 401: X-API-Key missing, malformed, invalid or revoked. Do not retry.
- 402: monthly character allowance exhausted (flat body, e.g. quota_exhausted with unit, limit,
  used). Do not retry; surface it so the app can prompt a top-up/upgrade.
- 403: not permitted, plan limit reached, or feature disabled for the plan (flat body). Do not
  retry.
- 404: voice not found, including voices owned by another workspace. Do not retry.
- 422: the voice provider rejected the input. Do not retry.
- 429: rate limited. Retry with backoff.
- 502: the voice provider is warming up or 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 AND TIMEOUTS
- Retry 429, 502 and network errors/timeouts with exponential backoff plus jitter (about 1s, 2s,
  4s; at most 3 retries). Retrying is safe here: an identical request (same voice, text and
  parameters) is served from cache and not billed again.
- The first request after a long idle period can be slow while the engine warms up; use a generous
  request timeout (configurable) rather than a short default.
- Never retry 400, 401, 402, 403, 404 or 422.

BILLING
- Billed per character of text against the plan's monthly allowance.
- Repeating an identical request is served from cache and not billed again.
- Expose billingRemaining (from X-Billing-Remaining) so callers can warn before running out; an
  exhausted allowance returns 402 when enforcement is on.

ACCEPTANCE CRITERIA
- synthesizeSpeech validates id, text length and parameter ranges locally, sends only documented
  fields, and returns the audio bytes plus the parsed headers.
- A non-2xx response is never treated as audio; both the envelope and the flat billing body are
  parsed into the typed error.
- 429/502 are retried with backoff; other 4xx are not.
- The key is never logged or sent from client-side code.

TEST PLAN
- Unit tests with mocked HTTP: 200 with audio/wav bytes and all four headers; 200 with only
  Content-Type; 400 "Voice is not enrolled yet"; 402 quota_exhausted flat body; 404; 429 then 200;
  502 then 200; 10,001-character text rejected locally; num_step 0 and 33 rejected locally.
- Smoke script:
- Get a ready voice id from FLAM_VOICE_ID, or by calling GET https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/voices (same
  X-API-Key header; voices are in data.voices) and picking the first one whose status is "ready".
  - Synthesize "Hello from Finesse." with output_format "wav", write speech.wav, and assert the
    file starts with the ASCII bytes "RIFF" and Content-Type is audio/wav. Print the byte count,
    X-Sample-Rate, X-Audio-URL and X-Billing-Remaining. 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.