TypeScript SDK

Install and configure the official TypeScript client.

On this page

Installation
Initialization
caedral.chat.completions.create(params)
Streaming
caedral.models.list()
caedral.usage.get()
caedral.embeddings.create(params)
caedral.images.generate(params)
caedral.audio.generate(params)
caedral.rerank.create(params)
Exported types
Errors

The official caedral npm package is a TypeScript/JavaScript client for the API gateway. Authenticate with apiKey (cd_live_…). Chat completions may include an optional notre field (mode off|auto, telemetry). Notre Runtime is included on every plan and applied on eligible POST /v1/chat/completions when the platform runs Notre — it does not run on embeddings, rerank, voice, or images. Install with npm install caedral — repository: github.com/trycaedral/caedral (directory sdk).

#Installation

shell

1npm install caedral

#Initialization

client.tstypescript

1import { Caedral } from "caedral";2 3const caedral = new Caedral({4  apiKey: process.env.CAEDRAL_API_KEY!, // cd_live_...5// baseURL: "http://localhost:5001", // local gateway6});

Option	Default	Description
apiKey	—	Required. Your cd_live_... API key
baseURL	https://api.caedral.com	API gateway base URL
maxRetries	3	Retries for idempotent GET requests only
timeout	120000	Request timeout in milliseconds
fetch	global fetch	Custom fetch implementation

#caedral.chat.completions.create(params)

Create a chat completion. Pass stream: true to receive AsyncIterable<ChatCompletionChunk>.

chat.tstypescript

1const completion = await caedral.chat.completions.create({2  model: "anthropic/claude-sonnet-4.5",3  messages: [4    { role: "system", content: "You are a helpful assistant." },5    { role: "user", content: "Explain quantum computing briefly." },6  ],7  temperature: 0.7,8  max_tokens: 500,9});10 11console.log(completion.choices[0]?.message.content);12console.log(completion.usage?.total_tokens);

#Streaming

typescript

1const stream = await caedral.chat.completions.create({2  model: "anthropic/claude-haiku-4.5",3  messages: [{ role: "user", content: "Write a haiku about code." }],4  stream: true,5});6 7for await (const chunk of stream) {8  const text = chunk.choices[0]?.delta?.content;9  if (text) process.stdout.write(text);10}

#caedral.models.list()

typescript

1const { data: models } = await caedral.models.list();2for (const model of models) {3  console.log(model.id, model.name, model.is_free ? "free tier" : "paid");4}

#caedral.usage.get()

typescript

1const usage = await caedral.usage.get();2console.log("Account status:", usage.accountStatus);3console.log("External pool used:", usage.pools.external.percentUsed, "%");

#caedral.embeddings.create(params)

typescript

1const result = await caedral.embeddings.create({2  model: "caedral-embed",3  input: ["Caedral routes frontier models through one API"],4});5console.log(result.data[0]?.embedding.length);

#caedral.images.generate(params)

typescript

1const result = await caedral.images.generate({2  model: "caedral-vision",3  prompt: "A minimalist logo for an AI company",4  n: 1,5});6console.log(result.data[0]?.url);

#caedral.audio.generate(params)

typescript

1const result = await caedral.audio.generate({2  model: "caedral-voice",3  input: "Welcome to Caedral.",4  voice: "alloy",5});6console.log(result.choices?.[0]?.message);

#caedral.rerank.create(params)

typescript

1const result = await caedral.rerank.create({2  model: "caedral-rerank",3  query: "How does billing work?",4  documents: ["Subscription pools power the API.", "Usage draws from included monthly quota."],5  top_n: 2,6});7console.log(result.results);

#Exported types

typescript

1import type {2  ChatCompletion,3  ChatCompletionChunk,4  ChatCompletionCreateParams,5  EmbeddingCreateParams,6  ImageGenerateParams,7  AudioGenerateParams,8  RerankCreateParams,9  ModelListResponse,10  UsageSummary,11} from "caedral";

#Errors

The SDK throws CaedralAPIError with type, statusCode, and message matching the gateway error envelope. Network failures throw CaedralNetworkError.

#Initialization

client.tstypescript

1import { Caedral } from "caedral";2 3const caedral = new Caedral({4  apiKey: process.env.CAEDRAL_API_KEY!, // cd_live_...5// baseURL: "http://localhost:5001", // local gateway6});

Option	Default	Description
apiKey	—	Required. Your cd_live_... API key
baseURL	https://api.caedral.com	API gateway base URL
maxRetries	3	Retries for idempotent GET requests only
timeout	120000	Request timeout in milliseconds
fetch	global fetch	Custom fetch implementation

#caedral.chat.completions.create(params)

Create a chat completion. Pass stream: true to receive AsyncIterable<ChatCompletionChunk>.

chat.tstypescript

1const completion = await caedral.chat.completions.create({2  model: "anthropic/claude-sonnet-4.5",3  messages: [4    { role: "system", content: "You are a helpful assistant." },5    { role: "user", content: "Explain quantum computing briefly." },6  ],7  temperature: 0.7,8  max_tokens: 500,9});10 11console.log(completion.choices[0]?.message.content);12console.log(completion.usage?.total_tokens);

#Streaming

typescript

1const stream = await caedral.chat.completions.create({2  model: "anthropic/claude-haiku-4.5",3  messages: [{ role: "user", content: "Write a haiku about code." }],4  stream: true,5});6 7for await (const chunk of stream) {8  const text = chunk.choices[0]?.delta?.content;9  if (text) process.stdout.write(text);10}

1const result = await caedral.rerank.create({2 model: "caedral-rerank",3 query: "How does billing work?",4 documents: ["Subscription pools power the API.", "Usage draws from included monthly quota."],5 top_n: 2,6});7console.log(result.results);

1import type {2 ChatCompletion,3 ChatCompletionChunk,4 ChatCompletionCreateParams,5 EmbeddingCreateParams,6 ImageGenerateParams,7 AudioGenerateParams,8 RerankCreateParams,9 ModelListResponse,10 UsageSummary,11} from "caedral";