Create an access token

curl --request POST \
  --url https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "ttl_seconds": 123,
  "voice_ids": [
    "<string>"
  ]
}
'

import requests

url = "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens"

payload = {
    "ttl_seconds": 123,
    "voice_ids": ["<string>"]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({ttl_seconds: 123, voice_ids: ['<string>']})
};

fetch('https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ttl_seconds' => 123,
    'voice_ids' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens"

	payload := strings.NewReader("{\n  \"ttl_seconds\": 123,\n  \"voice_ids\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ttl_seconds\": 123,\n  \"voice_ids\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ttl_seconds\": 123,\n  \"voice_ids\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "status": 201,
  "data": {
    "token": "fin_tok_9Qx2kLmP4vR7sT1uW3yZ5aB8cD0eF6gH",
    "expires_at": 1717939500000,
    "ttl_seconds": 300
  },
  "error": false
}

POST

flam-voice-svc

api

public

tokens

Create an access token

curl --request POST \
  --url https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "ttl_seconds": 123,
  "voice_ids": [
    "<string>"
  ]
}
'

import requests

url = "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens"

payload = {
    "ttl_seconds": 123,
    "voice_ids": ["<string>"]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({ttl_seconds: 123, voice_ids: ['<string>']})
};

fetch('https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ttl_seconds' => 123,
    'voice_ids' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens"

	payload := strings.NewReader("{\n  \"ttl_seconds\": 123,\n  \"voice_ids\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ttl_seconds\": 123,\n  \"voice_ids\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ttl_seconds\": 123,\n  \"voice_ids\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "status": 201,
  "data": {
    "token": "fin_tok_9Qx2kLmP4vR7sT1uW3yZ5aB8cD0eF6gH",
    "expires_at": 1717939500000,
    "ttl_seconds": 300
  },
  "error": false
}

Exchanges your API key for a short-lived, single-use access token (fin_tok_…). Your server calls this endpoint, hands the token to the browser, and the browser uses it to open the Realtime WebSocket or call speak / stream directly. The API key itself never leaves your server.

Short-lived - expires after ttl_seconds (default 300, max 3600).
Single use - consumed on its first successful use: one WebSocket handshake, or one speak / stream request. A request refused before it runs (a 429 rate limit, a plan check) keeps the token, so you can retry with it. Mint a new token for each session or request.
Text-to-speech only - a token grants the tts scope and nothing else. It can’t list, create or clone voices.
Optionally voice-restricted - pass voice_ids to limit which voices the token can synthesize with.
Tied to its key - it uses the creating key’s workspace and stops working if that key is revoked or expires.

Authorization

string

required

Your workspace API key (flv_…). Required scope: tts.

Body

All fields are optional; an empty body (or {}) mints a 5-minute token for any voice.

integer

default:300

Token lifetime in seconds, 10–3600. Out of range returns 400.

string[]

Restrict the token to these voices. Each id must be a voice your key’s workspace can use, otherwise the request returns 400 naming the bad id. Omit to allow any voice in the workspace. Using the token with another voice returns voice_not_allowed.

Response

string

The access token (fin_tok_…). Shown only in this response - the server stores a hash.

integer

When the token expires, as Unix epoch milliseconds.

integer

The effective lifetime in seconds.

curl -X POST "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens" \
  -H "X-API-Key: $FINESSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds":300,"voice_ids":["665f1a2b3c4d5e6f7a8b9c0d"]}'

// e.g. a route your own frontend calls once the user is signed in to YOUR app.
export async function POST() {
  const res = await fetch(
    "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens",
    {
      method: "POST",
      headers: {
        "X-API-Key": process.env.FINESSE_API_KEY, // stays on the server
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ ttl_seconds: 300, voice_ids: ["665f1a2b3c4d5e6f7a8b9c0d"] }),
    },
  );
  if (!res.ok) return new Response("Could not mint token", { status: 502 });
  const { data } = await res.json();
  return Response.json({ token: data.token, expires_at: data.expires_at });
}

import os, requests

res = requests.post(
    "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/tokens",
    headers={"X-API-Key": os.environ["FINESSE_API_KEY"]},
    json={"ttl_seconds": 300, "voice_ids": ["665f1a2b3c4d5e6f7a8b9c0d"]},
)
res.raise_for_status()
token = res.json()["data"]["token"]  # hand this to the browser

Response

{
  "status": 201,
  "data": {
    "token": "fin_tok_9Qx2kLmP4vR7sT1uW3yZ5aB8cD0eF6gH",
    "expires_at": 1717939500000,
    "ttl_seconds": 300
  },
  "error": false
}

{
  "status": 201,
  "data": {
    "token": "fin_tok_9Qx2kLmP4vR7sT1uW3yZ5aB8cD0eF6gH",
    "expires_at": 1717939500000,
    "ttl_seconds": 300
  },
  "error": false
}

Browser flow

Your server mints a token

When a signed-in user needs audio, your backend calls POST /tokens with your API key (scope tts), optionally restricting voice_ids to what that user may use.

Hand the token to the browser

Return only the token (and expires_at) to your frontend. Never send the API key.

The browser uses it once

Open the WebSocket with the token as a subprotocol, or call speak / stream with Authorization: Bearer <token>. The token is consumed on that first successful use.

const { token } = await fetch("/api/finesse-token", { method: "POST" }).then((r) => r.json());

// Browsers can't set headers on a WebSocket handshake, so the token rides in the
// subprotocol list. The server selects "finesse.v1".
const ws = new WebSocket(
  "wss://fi.production.flamapis.com/flam-voice-svc/api/v1/public/stream",
  ["finesse.v1", token],
);
ws.binaryType = "arraybuffer";
ws.addEventListener("open", () => {
  ws.send(JSON.stringify({
    type: "task_start",
    context_id: "ctx-1",
    voice_id: "665f1a2b3c4d5e6f7a8b9c0d",
    text: "Hello from Finesse.",
    finalize: true,
    output_format: "s16le",
  }));
});

const { token } = await fetch("/api/finesse-token", { method: "POST" }).then((r) => r.json());

const res = await fetch(
  "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/voices/665f1a2b3c4d5e6f7a8b9c0d/speak",
  {
    method: "POST",
    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
    body: JSON.stringify({ text: "Hello from Finesse.", output_format: "wav" }),
  },
);
if (!res.ok) throw new Error(`Synthesis failed: ${res.status}`);
new Audio(URL.createObjectURL(await res.blob())).play();

If your WebSocket client can’t send subprotocols, pass the token as ?access_token=fin_tok_… on the stream URL instead. The older ?api_key= query parameter still works but is deprecated - it puts your long-lived key in URLs and browser history.

Errors

Status	Code	When
`400`	-	`ttl_seconds` out of range, or a `voice_ids` entry isn’t a voice in your workspace.
`401`	`key_expired`	The API key used to mint the token has expired.
`401`	-	`X-API-Key` missing, invalid or revoked.
`403`	`insufficient_scope`	The API key doesn’t have the `tts` scope.

When the browser uses the token: an unknown, expired or already-used token returns 401 token_invalid (on the WebSocket, the handshake fails with 401); a voice outside voice_ids returns 403 voice_not_allowed on HTTP, or a non-fatal voice_not_allowed error frame on the WebSocket. See Errors.

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

WHAT TO BUILD
- A SERVER-SIDE function createAccessToken(options) (name it per the project's conventions) that
  exchanges the workspace API key for a short-lived, single-use access token and returns:
    { token: string, expiresAt: number, ttlSeconds: number }
- A server route (in the project's web framework) that your own signed-in frontend calls to get a
  token, returning only { token, expires_at } to the browser. Protect it with the app's existing
  user authentication; never expose an unauthenticated token minting route.
- On the browser side, a helper that uses the token for ONE realtime session or ONE speak/stream
  request (see USING THE TOKEN).
- 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/tokens
- Request Content-Type: application/json

REQUEST BODY (all optional; {} is valid)
- ttl_seconds (integer, optional, default 300): token lifetime, 10-3600. Out of range returns 400.
  Validate locally.
- voice_ids (string[], optional): restrict the token to these voice ids (24-character hex). Each
  must be a voice the key's workspace can use, otherwise 400 naming the bad id. Omit to allow any
  voice in the workspace.

    { "ttl_seconds": 300, "voice_ids": ["665f1a2b3c4d5e6f7a8b9c0d"] }

AUTHENTICATION
- Send the header  X-API-Key: <workspace API key>  on every request. Keys start with "flv_".
- Required scope: tts. Keys carry one or more scopes (voices:read, voices:write, clone,
  tts); a key without this scope gets 403 with code "insufficient_scope". Keys created before
  scopes existed have all four.
- Read the key from the environment variable FINESSE_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.
- This call is SERVER-SIDE ONLY. Never hard-code, log or commit the key, and never ship it in
  browser/client-side code. The whole point of this endpoint is that only the token reaches the
  browser.
- Keys can expire: an expired key returns 401 with code "key_expired". Do not retry; surface it so
  an operator can rotate the key.

SUCCESS RESPONSE (201)
    {
      "status": 201,
      "data": {
        "token": "fin_tok_9Qx2kLmP4vR7sT1uW3yZ5aB8cD0eF6gH",
        "expires_at": 1717939500000,
        "ttl_seconds": 300
      },
      "error": false
    }
- token starts with "fin_tok_". Treat it as a secret: do not log it.
- expires_at is Unix epoch MILLISECONDS.

TOKEN RULES
- Single use: consumed atomically on its first successful use (one WebSocket handshake, or one
  speak/stream request). A request refused before it runs (429 rate_limited / concurrency_limited,
  402/403 plan check) keeps the token, so retry that request with the same token after
  Retry-After. Mint a new token per session or request; never cache or reuse a spent one.
- Grants the tts scope only.
- Inherits the creating key's workspace, and becomes invalid if that key is revoked or expires.

USING THE TOKEN (browser)
- WebSocket: new WebSocket("wss://fi.production.flamapis.com/flam-voice-svc/api/v1/public/stream",
  ["finesse.v1", token]). The server selects the "finesse.v1" subprotocol. If the client cannot
  send subprotocols, use ...?access_token=<token> instead (URL-encode it, never log the URL).
  Do NOT use ?api_key=: it is deprecated (responses carry a Deprecation header) and exposes the
  long-lived key.
- HTTP: POST .../voices/{id}/speak or .../voices/{id}/stream with  Authorization: Bearer <token>
  instead of X-API-Key.
- Unknown, expired or already-used token: 401 with code "token_invalid" (WebSocket: the handshake
  fails with 401). Fetch a fresh token from your server and retry once.
- Voice not in the token's voice_ids: 403 with code "voice_not_allowed" over HTTP; on the
  WebSocket a non-fatal error frame with code "voice_not_allowed" for that task_start.

ERROR RESPONSES
Errors use the standard envelope, plus a machine-readable "code" on auth/scope errors:

    {
      "status": 403,
      "error": true,
      "code": "insufficient_scope",
      "message": "This API key is missing the required scope: tts"
    }

- 400: ttl_seconds out of range, or a voice_ids entry is not usable by the workspace. Do not retry.
- 401: X-API-Key missing, malformed, invalid or revoked, or code "key_expired". Do not retry.
- 403: code "insufficient_scope" (the key lacks tts). Do not retry.
- 429 with code "rate_limited" (over the plan's requests per second): wait the number of seconds in the Retry-After header, then retry with backoff.
  See /guides/rate-limits.
- Surface failures as one typed error (for example FinesseApiError) carrying: HTTP status, code
  (when present), message, a retryable flag, the request id (the X-Request-Id response header; error bodies also carry it as
  request_id), and the raw body for debugging. Log the request id with every failure.

ACCEPTANCE CRITERIA
- The API key is only ever read and sent on the server; the browser receives only the token.
- ttl_seconds is validated locally (10-3600) and voice_ids is passed through when set.
- The browser helper opens the WebSocket with subprotocols ["finesse.v1", token], or sends
  Authorization: Bearer <token> for speak/stream, and requests a fresh token on token_invalid.
- A new token is minted for every session/request.

TEST PLAN
- Unit tests with mocked HTTP: 201 parses token/expires_at/ttl_seconds; {} body works; ttl 5 and
  4000 rejected locally; 400 bad voice id; 401 key_expired; 403 insufficient_scope.
- Smoke script (server-side): mint a token with ttl_seconds 60, then call POST .../voices/{id}/speak
  with Authorization: Bearer <token> and a ready voice id from FLAM_VOICE_ID; assert audio comes
  back. Call it again with the same token and assert 401 token_invalid (single use).

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.

Authentication

Voices

Speech

Compatibility

Reference

Create an access token

Authorization

Body

Response

Browser flow

Errors

Prompt

​Authorization

​Body

​Response

​Browser flow

​Errors

​Prompt

Authorization

Body

Response

Browser flow

Errors

Prompt