API documentation

Your first watermarked clip

Create a Project in the Console, create a Project API Key, and prepare wallet credits and a sufficient Key budget. Keep the Key in your server environment.

1. Set up accessCreate a Project Key and configure TIMBRELAY_API_KEY on your server.
2. Choose a model & voiceRead the live catalogs, then set TIMBRELAY_MODEL and TIMBRELAY_VOICE to compatible IDs.
3. Send a stable operation IDSave the request and its idempotency ID before sending. The same business action must reuse both on recovery.

For the Node.js example, download and install the SDK first. cURL and Python use the HTTP API directly.

import { writeFile } from "node:fs/promises";
import { Timbrelay } from "@timbrelay/sdk";

const client = new Timbrelay({
  apiKey: process.env.TIMBRELAY_API_KEY!,
  baseURL: "https://api.timbrelay.com",
});

const [models, voices] = await Promise.all([
  client.models.list(),
  client.speakers.list(),
]);
// Choose IDs from the live catalog, not an assumed default.
const model = models.data.find(
  (m) => m.available && m.id === process.env.TIMBRELAY_MODEL,
);
const voice = voices.data.find(
  (v) => v.id === process.env.TIMBRELAY_VOICE && v.models.includes(model?.id ?? ""),
);
if (!model || !voice) throw new Error("Choose a compatible model and voice.");

// Persist this action ID and exact input before sending.
const result = await client.audio.speech.create(
  { model: model.id, voice: voice.id, input: "Welcome to our application. Your announcement is ready." },
  { idempotencyKey: "announcement-123-action-456" },
);
await writeFile("speech.wav", result.audio);
// result.watermarkApplied is true for every resolved call.

Examples do not run in this page. A generation you send from your application may spend credits. Very short audio may not meet the configured watermark minimum.

Authentication & API origin

Program requests use a Project API Key as a bearer token. Your Key selects the Project; do not supply a Project ID in the speech request.

Authorization: Bearer <YOUR_PROJECT_API_KEY>

Examples on this build use https://api.timbrelay.com. Append the endpoint path for HTTP calls; pass only the origin to the SDK.

Node.js & TypeScript SDK

The preview package includes prebuilt ESM JavaScript, TypeScript declarations, examples and integration documentation. It requires Node.js 20+ and has zero runtime dependencies.

Save the download in your application directory, then install it from the file. The package has not been published to npm.

npm install ./timbrelay-sdk-0.1.0-preview.1.tgz

SHA-256 checksumOpenAPI snapshotChinese integration guide

Verify the download with shasum -a 256 -c SHA256SUMS in the same directory as timbrelay-sdk-0.1.0-preview.1.tgz.

Every method sends one HTTP request. The SDK has no automatic retries, new operation IDs or fallback providers. Encoding is handled by Timbrelay; customers do not install the OfSpectrum SDK. CommonJS applications can use await import("@timbrelay/sdk") inside an async function.

Find models & compatible voices

Returns { "object": "list", "data": [...] }. Select a model with available: true. Model fields include id, name, sample_rate_hz, languages, capabilities, response_formats, price_per_generation_micros and price_version.

Returns the same list envelope. Each voice provides id, name, language and compatible model IDs in models. Both endpoints require a Project Key and do not generate audio.

curl --fail-with-body "https://api.timbrelay.com/v1/models" \
  -H "Authorization: Bearer $TIMBRELAY_API_KEY"

curl --fail-with-body "https://api.timbrelay.com/v1/speakers" \
  -H "Authorization: Bearer $TIMBRELAY_API_KEY"

Catalog metadata can change. Do not assume that an example model, voice, price or internal upstream format will always be available.

Generate speech

Send JSON with Content-Type: application/json and a required Idempotency-Key header. The server completes synthesis, watermark encoding and persistence before returning the deliverable audio.

Unknown fields are rejected, including project_id or free. The idempotency header accepts 1–128 ASCII letters, digits, underscores or hyphens. Output is a complete WAV; streaming is not supported.

Read the audio response & charge

A successful HTTP response is 200 with complete audio/wav bytes. It is not JSON, a stream, or an asset URL. Check status, watermark confirmation and WAV integrity before exposing direct HTTP results to users.

The SDK exposes audio as a Uint8Array, plus generationId, watermarkApplied, chargedMicros, replayed, idempotencyKey, sampleRateHz and durationSeconds.

Model prices come from the current catalog. Check the selected model price and project spending limit before generating. On replay, the charge header reports the original settlement amount; it does not mean another charge. Successful replay audio expires after 24 hours, so save the WAV in your own application.

Detect a watermark

Timbrelay uses OfSpectrum Neo for watermark detection. Authenticate with your Project Key; no separate OfSpectrum Key is needed.

Upload raw WAV bytes with a Project Key and Content-Type: audio/wav. Use standard PCM16 WAV, mono or stereo, 8–48 kHz, up to 180 seconds and 6,356,992 bytes. This is a separate, explicit call.

curl --fail-with-body "https://api.timbrelay.com/v1/audio/watermark/decode" \
  -H "Authorization: Bearer $TIMBRELAY_API_KEY" \
  -H "Content-Type: audio/wav" \
  --data-binary @speech.wav

{
  "watermarked": true,
  "matches_service_token": true,
  "attribution_scope": "service"
}

import { readFile } from "node:fs/promises";

const result = await client.watermark.decode(await readFile("speech.wav"));
// { watermarked, matchesServiceToken, attributionScope: "service" }
// Explicit detection; generation never calls decode automatically.

A match identifies only the current service token, not a Project, user, generation or ownership. A negative result does not prove the absence of all watermarks. Detection failures are errors, never fabricated negative results. Uploaded audio is not persisted by Timbrelay.

Idempotency & safe recovery

One business action gets one stable ID. Persist it with the exact request before sending, then reuse the same Project Key, ID and input on uncertain-result retries—even after your application restarts.

The hosted edge waits up to 120 seconds without response bytes; the backend task lease is 300 seconds. The SDK defaults to a 130-second request timeout. A timeout, connection loss or client cancellation can leave the backend running or already settled.

Do not automatically create a new ID after a timeout. An in-progress operation returns 409 generation_in_progress; wait before recovering. A terminal failed request remains failed under its ID without charge; a deliberate new attempt needs a new ID. Changing the Project Key changes the idempotency scope.

A response rejected by the SDK may already have been settled by the server. Investigate repeated invalid responses and recover under the original ID; SDK rejection alone does not establish billing failure.

Errors & current limits

{
  "detail": {
    "code": "generation_in_progress",
    "message": "This request is still running; retry the same request ID later"
  }
}
// Other failures may use a string detail or a validation-error array.
// A gateway can return HTML. Check HTTP status before parsing audio.

SDK failures extend TimbrelayError. APIError includes HTTP status and a safe error code; TimeoutError, ConnectionError and RequestAbortedError describe uncertain outcomes. WatermarkError and InvalidResponseError expose no audio.