Clariva logoClariva/ API
Sign in
DocsSDK

SDK

@clariva/sdk

The official TypeScript SDK wraps Clariva REST endpoints with typed resources, retry behavior, and ergonomic error handling.

Install

Runtime requirements: Node.js 18+ or Bun. Default timeout is 60 seconds with two retries.

bashnpm1 lines
npm install @clariva/sdk

Quickstart

tsCreate + generate18 lines
import { Clariva } from "@clariva/sdk";

const client = new Clariva({
  apiKey: process.env.CLARIVA_API_KEY!,
  baseUrl: "https://app.clariva.ai",
});

const voices = await client.voices.list();
const firstVoice = voices.data[0];
if (!firstVoice) throw new Error("No voices available");

const generation = await client.generations.create({
  text: "Welcome to Clariva.",
  voiceId: firstVoice.id,
});

const audio = await client.generations.getAudio(generation.id);
console.log("audio bytes", audio.byteLength);

SDK capabilities

  • - Typed resources for voices, generations, and usage
  • - Automatic retries for 429 and 5xx responses
  • - Timeout and custom fetch support
  • - Error classes for auth, validation, not-found, rate limit, and timeout

Production recommendation

Set `baseUrl` explicitly to your deployment host and wire `apiKey` from secure server environment variables.

Error handling

tsError classes31 lines
import {
  Clariva,
  AuthenticationError,
  ForbiddenError,
  NotFoundError,
  RateLimitError,
  TimeoutError,
  ValidationError,
} from "@clariva/sdk";

const client = new Clariva({ apiKey: process.env.CLARIVA_API_KEY! });

try {
  await client.generations.list();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof ValidationError) {
    console.error("Invalid request payload");
  } else if (error instanceof ForbiddenError) {
    console.error("Access forbidden");
  } else if (error instanceof NotFoundError) {
    console.error("Resource not found");
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof TimeoutError) {
    console.error("Request timed out");
  } else {
    throw error;
  }
}

Search documentation

Find pages, endpoints, and sections.