Developer documentation

Build speech into your product with a small, predictable API.

API keys, speech generation, webhooks, SDK examples, stable errors, and rate limits. This page documents what developers can use today.

Base URLhttps://api.resonyx.rudraix.com

Use API keys for server-side integrations. Firebase sessions are only for the RESONYX web app.

Quickstart

Create speech

Send text and voice settings to `POST /v1/speech`. The response includes a signed playback URL when generation completes.

cURL

curl -X POST https://api.resonyx.rudraix.com/v1/speech \
  -H "Authorization: Bearer rx_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Create a calm welcome message for our product.",
    "voice": "maya-realtime",
    "mode": "natural",
    "emotion": "warm",
    "format": "mp3"
  }'

Authentication

Use API keys from your backend

Send the key as a bearer token. Full keys are shown once during creation and are never shown again.

Header

Authorization: Bearer rx_live_xxxxxxxxxxxxxxxxxxxxxxxxx

speech:writeCreate speech

Allows `POST /v1/speech` generation calls. This is required for external API audio creation.

speech:readRead speech metadata

Reserved for future generation lookup and signed playback metadata endpoints.

usage:readRead usage

Allows future usage and request-log read APIs without exposing billing authority.

realtime:writeRealtime sessions

Reserved for future external realtime speech sessions and websocket authentication.

Speech API

Request and response

Request body

{
  "text": "Create a calm welcome message for our product.",
  "voice": "maya-realtime",
  "mode": "natural",
  "emotion": "warm",
  "format": "mp3",
  "realism": {
    "level": 2,
    "pauseNaturalness": 0.6,
    "vocalTexture": 0.5
  }
}

Response body

{
  "id": "gen_xxxxx",
  "status": "completed",
  "audio_url": "https://...",
  "duration_seconds": 8,
  "credits_used": 1
}

Realism fields are optional. RESONYX validates values server-side and ignores unsupported combinations instead of trusting browser input.

SDKs

Production examples

Use retries, timeouts, and idempotency keys in production workloads.

TypeScript

import { Resonyx, ResonyxApiError } from "@resonyx/sdk";

const resonyx = new Resonyx({
  apiKey: process.env.RESONYX_API_KEY!,
  baseUrl: process.env.RESONYX_API_URL,
  timeoutMs: 90_000,
  maxRetries: 2,
});

try {
  const audio = await resonyx.speech.create({
    text: "This should feel human, not generated.",
    voice: "maya-realtime",
    mode: "natural",
    emotion: "warm",
    format: "mp3",
  });

  console.log(audio.audio_url);
} catch (error) {
  if (error instanceof ResonyxApiError) {
    console.error(error.code, error.status);
  }
  throw error;
}

Python

from resonyx_sdk import Resonyx, ResonyxAPIError

client = Resonyx(
    api_key="rx_live_your_key",
    base_url="https://api.resonyx.rudraix.com",
    timeout=90,
    max_retries=2,
)

try:
    audio = client.speech.create(
        text="This should feel human, not generated.",
        voice="maya-realtime",
        mode="natural",
        emotion="warm",
        format="mp3",
    )
    print(audio["audio_url"])
except ResonyxAPIError as error:
    print(error.code, error.status)
    raise

cURL

curl -X POST https://api.resonyx.rudraix.com/v1/speech \
  -H "Authorization: Bearer rx_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gen-2026-05-20-001" \
  -d '{
    "text": "This should feel human, not generated.",
    "voice": "maya-realtime",
    "mode": "natural",
    "emotion": "warm",
    "format": "mp3"
  }'

Webhooks

Signed event delivery

Webhook delivery is verified with signatures and destination ownership checks before production activation.

Signature format

X-Resonyx-Timestamp: 1779138046
X-Resonyx-Signature: t=1779138046,v1=<signature>

signed_payload = timestamp + "." + raw_body

generation.completedlive

Notify a backend when an audio generation has completed and a signed playback URL is available.

generation.failedlive

Notify a backend when generation fails after validation or engine processing.

realtime.session.endedbeta gated

Summarize realtime duration, credits, first-chunk latency, and interruption count.

credits.lowlive

Warn production integrators before generation requests begin failing for credit exhaustion.

api_key.revokedlive

Confirm key revocation to internal security workflows.

webhook.testlive

Send a signed test event to verify endpoint security, parsing, and delivery logs.

Errors

Stable error format

Errors return a machine-readable code and a short message. Do not parse message text for control flow.

invalid_api_key401

Check the bearer token, environment prefix, and key copy process.

revoked_api_key401

Create a new key and rotate the integration secret.

insufficient_scope403

Create or rotate a key with the needed scope.

rate_limit_exceeded429

Back off with jitter. Do not retry aggressively.

insufficient_credits402

Wait for billing activation, add credits, or reduce usage.

invalid_request400

Fix text length, voice, mode, emotion, format, or realism values.

generation_failed500

Retry with backoff or inspect the request log and generation record.

internal_error500

Retry safely; escalate if repeated.

Rate limits

Limits and usage

Test keys start with low request limits. Live keys increase by plan. Realtime and premium speech remain capped to keep quality and reliability predictable.

Test keys10 requests / minuteStarter live keys60 requests / minuteHigher plansReviewed per workspace