Skip to main content

​
API keys

POST /v1/tts is authenticated with a bearer token:
Create and manage keys in the Geko console. A key is shown once at creation — store it then; the server only keeps a hash. (Keys look like sk-tokay- followed by 48 hex characters.) The catalog endpoints — /v1/models, /v1/voices, /health — are open and need no key, so docs, playgrounds, and voice pickers can render without one.

​
With the SDK

Pass the key explicitly, or let the SDK read it from the environment (GEKO_API_KEY, falling back to TOKAY_API_KEY):

​
Keep keys server-side

Your API key grants billable usage. Never ship it to a browser or mobile app. Anything in client-side code is public.
  • Call Geko from your backend (API route, server, worker, function).
  • Expose your own thin endpoint to your frontend; keep the Geko key on the server.
  • Don’t put the key in client-side JS, a public repo, or a mobile bundle.
The API now sends permissive CORS headers, so a browser can call it cross-origin — but that does not make it safe to expose your key. Keep synthesis behind your own server. See Use it in your app for a Next.js route example.

​
Quotas & billing

Keys are metered per organization. If you run out of credits, POST /v1/tts returns HTTP 429 with a detail explaining you’re out of credits — top up in the console. The SDK surfaces this as a GekoError (status === 429) and does not retry it (a retry can’t create credits). See Errors & retries.

​
Rotating a key

Revoke a key in the console and issue a new one. Revocation takes effect within a short caching window (the API caches key lookups for about 30 seconds).

​
Next steps

Quickstart

Make your first authenticated request in minutes.

TypeScript SDK

The typed client that reads your key from the environment.

Errors & retries

Handle 401, 429, and transient failures cleanly.

Billing & credits

How usage is metered and what running out looks like.