Developer portal

Shunya AI platform docs

These docs describe the routes that exist in this Next.js platform slice. They do not expose the internal Voice Engine hostname.

Base URL

Use the same origin that serves this app. For local review, use the port printed by your local server.

Authentication

Public routes below require an API key (Authorization: Bearer <key>) created at /app/api-keys. Better Auth session cookies authorize the browser workspace only, never these routes.

STT

POST /v1/stt with multipart audio, languageCode, and projectId.

TTS

POST /v1/tts with text, languageCode, voiceId, and projectId.

Quickstart

Create or receive a real Better Auth account with a tenant Membership row.
Sign in at /login and open /app/dashboard.
Use /app/apis to confirm which capabilities are operational.
Use /app/stt and /app/tts to try requests interactively in the browser (session-authenticated, not for external integration).
Create a development API key at /app/api-keys - the full secret is shown once. Use it as a Bearer token against the external /v1/* routes below for real integration.

Capability and language status

GET /v1/capabilities and GET /v1/health are the runtime-facing contracts for an authenticated integration. They report the current provider boundary without exposing internal hosts. The public language programme is described at /language-intelligence; it must not be read as ten fully installed speech stacks.

Text transformation

Language detection and normalization foundations are separate from translation and transliteration. The current local runtime does not claim an installed translation or transliteration artifact, so an unavailable response is expected rather than a silent unchanged-text success. No public integration route is documented here until the contract is approved for external use.

Speech to Text

Route: POST /v1/stt. Auth: Authorization: Bearer <api-key> (scope stt:transcribe required). Body: multipart form data with audio, projectId (required unless the key is already scoped to one project), and languageCode set to auto, en, or hi.

curl -X POST $SHUNYA_API_BASE_URL/v1/stt \
  -H "Authorization: Bearer $SHUNYA_API_KEY" \
  -F "audio=@sample.wav" \
  -F "languageCode=auto" \
  -F "projectId=<your-project-id>"

const form = new FormData();
form.append("audio", file);
form.append("languageCode", "auto");
form.append("projectId", projectId);

const response = await fetch("$SHUNYA_API_BASE_URL/v1/stt", {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
  body: form,
});
const result = await response.json();

import requests

api_key = "<your-api-key>"
with open("sample.wav", "rb") as audio:
    response = requests.post(
        "$SHUNYA_API_BASE_URL/v1/stt",
        headers={"Authorization": f"Bearer {api_key}"},
        files={"audio": audio},
        data={"languageCode": "auto", "projectId": "<your-project-id>"},
        timeout=60,
    )
print(response.json())

Text to Speech

Route: POST /v1/tts. Auth: Authorization: Bearer <api-key> (scope tts:synthesize required). Voices come from GET /v1/voices (scope voices:read). English defaults to the accepted slower pacing; Hindi keeps backend default pacing unless a speaking rate is explicitly sent.

curl -X POST $SHUNYA_API_BASE_URL/v1/tts \
  -H "Authorization: Bearer $SHUNYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from Shunya AI","languageCode":"en","voiceId":"<voice-id>","projectId":"<your-project-id>"}'

Health and capabilities

GET /v1/health returns a sanitized platform status (no internal hostnames, ports, or upstream error detail). GET /v1/capabilities lists operational and planned capabilities. Health requires capabilities:read; capabilities uses the same scope.

Errors, request IDs, and quotas

Gateway responses include request IDs when upstream calls complete. When a real per-key rate limit is configured, responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Quota and usage values are read from persisted records only.

Canonical developer paths

Use /v1/* for external API integration. Authenticated browser platform calls use the app's platform routes. Internal Next.js route paths, provider routes, and internal hostnames are not developer contracts.

Loading Shunya AI

Preparing the current workspace.