TypeScript / JavaScript SDK

@gekoai/sdk is a thin, typed client for the Geko API. Zero runtime dependencies (built on the global fetch), dual ESM + CommonJS, bundled type declarations. Runs on Node 20+, Deno, Bun, and browsers (via a server-side proxy).

Install

npm install @gekoai/sdk

The client

import { Geko } from "@gekoai/sdk";

const geko = new Geko({ apiKey: process.env.GEKO_API_KEY });

The client is namespaced by service. Text-to-speech lives under geko.tts; platform-level calls (models, health) sit on the client. Future services (speech-to-text, …) will appear as sibling namespaces — see the roadmap.

Options

new Geko(options?)

Option	Type	Default	Notes
`apiKey`	`string`	`process.env.GEKO_API_KEY`	Falls back to `TOKAY_API_KEY`. Required (directly or via env).
`baseUrl`	`string`	`https://geko--tokay-serve-web.modal.run`	Override for self-hosting / proxying.
`fetch`	`typeof fetch`	global `fetch`	Inject a custom fetch (proxy, instrumentation, test double).
`timeout`	`number` (ms)	`120000`	Per-request. `0` disables. Generous because of cold starts.
`maxRetries`	`number`	`2`	Retries on transient failures. `0` disables.
`headers`	`Record<string, string>`	`{}`	Extra headers on every request.

`geko.tts.create(params)`

Synthesize speech. Returns a Promise<ArrayBuffer> of raw WAV bytes (24 kHz, PCM16, mono).

const audio = await geko.tts.create({
  text: "Сәлеметсіз бе! Тапсырыс нөмірі 152.",
  voice: "Aigerim",
  nfe: 32,
});

Param	Type	Default	Notes
`text`	`string`	— (required)	Text to synthesize (up to ~5000 chars).
`model`	`string`	`tokay-kk-v1`	Model id.
`voice`	`string`	model default (`Aigerim`)	Name from `geko.tts.voices()`.
`speed`	`number`	`1.0`	Speed multiplier (0.5–2).
`nfe`	`number`	`32`	Diffusion steps: `16` fast, `32` quality. See latency.
`normalize`	`boolean`	`true`	Expand numbers/currency/dates → spoken form. See normalization.
`signal`	`AbortSignal`	—	Cancel the request.
`timeout`	`number` (ms)	client default	Per-call timeout override.

Turn the bytes into a file or a playable blob — see Playing & saving audio.

`geko.tts.stream(params)`

Stream synthesis sentence-by-sentence to start playback sooner on long text. Returns an async iterable of WAV ArrayBuffers — one per chunk, each independently playable. Same params as create().

for await (const wav of geko.tts.stream({ text: longText, voice: "Aigerim" })) {
  // each `wav` is a standalone WAV chunk — play or buffer it as it arrives
  console.log(`chunk: ${wav.byteLength} bytes`);
}

Streams aren’t retried (a partial stream can’t be replayed); use signal to cancel and a per-call timeout to bound the whole stream. Under the hood it consumes the framed wav-frames-v1 protocol from POST /v1/tts/stream.

`geko.tts.voices(model?, options?)`

List the voices for a model. Returns { model, voices: Voice[] }.

const { voices } = await geko.tts.voices("tokay-kk-v1");
// [{ name: "Aigerim", gender: "female", style: "Warm, professional", best_for: "Reception, customer support" }, ...]

`geko.models(options?)`

List every model on the platform and its voices. Returns { data: Model[] }.

const { data } = await geko.models();
// [{ name: "tokay-kk-v1", lang: "kk", sample_rate: 24000, voices: [...], default_voice: "Aigerim" }]

`geko.health(options?)`

Service probe. Returns { status, models: string[] }.

const { status, models } = await geko.health(); // { status: "ok", models: ["tokay-kk-v1"] }

The read methods accept an options object of { signal?, timeout? }.

Types

import type { Voice, Model, TtsParams, GekoOptions } from "@gekoai/sdk";

interface Voice {
  name: string;
  gender?: string | null;
  style?: string | null;
  best_for?: string | null;
}

interface Model {
  name: string;
  lang?: string | null;
  sample_rate?: number | null;
  voices?: string[];
  default_voice?: string | null;
}

Response types describe the server contract; like most thin SDKs, JSON bodies are not re-validated at runtime.

Timeouts, cancellation & retries

Covered in depth in Errors & retries. In short: transient failures (network, timeout, 5xx) retry with backoff; 429 never does; pass an AbortSignal or a per-call timeout to control individual requests.

Bring your own fetch

const geko = new Geko({
  apiKey: process.env.GEKO_API_KEY,
  fetch: (input, init) => myInstrumentedFetch(input, init),
});

Useful for proxies, logging, or tests. The SDK always calls fetch as a free function, so undici’s global keeps its binding and your custom fetch keeps its own.

Next steps

Playing & saving audio

Turn the WAV bytes into files, playback, or other formats.

Errors & retries

Typed errors, automatic retries, timeouts, and cancellation.

Latency & quality

Tune the nfe dial and understand cold starts.

CLI

Synthesize and browse the catalog from your terminal.

get started

guides

sdk

reference

TypeScript / JavaScript SDK

Install

The client

Options

`geko.tts.create(params)`

`geko.tts.stream(params)`

`geko.tts.voices(model?, options?)`

`geko.models(options?)`

`geko.health(options?)`

Types

Timeouts, cancellation & retries

Bring your own fetch

Next steps

Playing & saving audio

Errors & retries

Latency & quality

CLI

​Install

​The client

​Options

​geko.tts.create(params)

​geko.tts.stream(params)

​geko.tts.voices(model?, options?)

​geko.models(options?)

​geko.health(options?)

​Types

​Timeouts, cancellation & retries

​Bring your own fetch

​Next steps

Playing & saving audio

Errors & retries

Latency & quality

CLI

Install

The client

Options

`geko.tts.create(params)`

`geko.tts.stream(params)`

`geko.tts.voices(model?, options?)`

`geko.models(options?)`

`geko.health(options?)`

Types

Timeouts, cancellation & retries

Bring your own fetch

Next steps