Client Configuration

Creating and configuring the SkytellsClient — options, edge runtime, lazy sub-APIs, and best practices.

The SkytellsClient is the single entry point to the entire Skytells platform. One client gives you access to predictions, chat completions, responses, embeddings, safety, webhooks, and Orchestrator workflows — all through a unified, type-safe interface.

At Skytells, we've designed the SDK so that every sub-API is lazily instantiated. You only pay for what you use — if your application only calls client.chat, no other sub-API is allocated.

Import & Instantiation

Three ways to create a client

The SDK exports a default factory Skytells(), a named class SkytellsClient, and a deprecated createClient() alias. All produce the same object.

The Skytells() factory is the recommended approach. The SDK does not read environment variables automatically — you must pass your API key explicitly.

Creating a Client

Factory (recommended)

import Skytells from 'skytells';

const client = Skytells('sk-your-api-key');

ClientOptions

All options are optional. Pass as the second argument to Skytells() or new SkytellsClient().

baseUrlstring

Override the Inference API base URL. Useful for proxies, staging, or self-hosted instances.

timeoutnumber

Request timeout in milliseconds. Automatically set to 25000 in edge mode when not explicitly provided.

headersRecord<string, string>

Custom headers merged into every request.

retryRetryOptions

Retry configuration for non-streaming requests. See Reliability.

fetchtypeof fetch

Custom fetch implementation. Useful for disabling Next.js caching or adding request logging.

runtimeSkytellsRuntime

'default' | 'edge' | 'node' | 'browser'. Use 'edge' for Cloudflare Workers and Vercel Edge.

orchestratorApiKeystring

Orchestrator API key (wfb_…). Required to use client.orchestrator. See Orchestrator SDK and managing Orchestrator keys.

orchestratorBaseUrlstring

Override the Orchestrator base URL.

RetryOptions

retriesnumber

Number of retry attempts after the first failure.

retryDelaynumber

Base delay in ms. Uses linear backoff: delay × (attempt + 1).

retryOnnumber[]

HTTP status codes that trigger a retry.

Retries apply only to non-streaming requests. Streaming calls are never auto-retried. See Reliability for full retry documentation.

Client Options

Full options

import Skytells from 'skytells';

const client = Skytells('sk-your-api-key', {
baseUrl: 'https://api.skytells.ai/v1',
timeout: 30_000,
headers: { 'X-App-Version': '1.0.0' },
retry: {
  retries: 3,
  retryDelay: 1000,
  retryOn: [429, 500, 502, 503, 504],
},
// Custom fetch (e.g. Next.js no-cache)
fetch: (url, opts) =>
  fetch(url, { ...opts, cache: 'no-store' }),
});

Sub-APIs (Lazy Singletons)

All sub-resource accessors are lazy singletons — the instance is created on first access and cached for the client's lifetime. No overhead for APIs you don't use.

Property	Type	Description
`client.predictions`	`PredictionsAPI`	Create, fetch, list predictions — maps to POST /v1/predictions
`client.prediction`	`PredictionsAPI`	Alias of `predictions`
`client.models`	`ModelsAPI`	Browse the model catalog — see Models
`client.chat`	`Chat`	Chat completions + Responses — maps to POST /v1/chat/completions
`client.responses`	`Responses`	Responses API — maps to POST /v1/responses
`client.embeddings`	`Embeddings`	Text embeddings — maps to POST /v1/embeddings
`client.safety`	`Safety`	Content moderation — see Responsible AI
`client.orchestrator`	`Orchestrator`	Workflow automation (requires `orchestratorApiKey`) — see Orchestrator product

Accessing client.orchestrator without providing orchestratorApiKey throws a SkytellsError with errorId: 'SDK_ERROR'.

// First access — allocates PredictionsAPI
client.predictions.create(...)

// Second access — returns cached instance
client.predictions.list()

// Orchestrator — requires separate key
const client = Skytells('sk-...', {
orchestratorApiKey: 'wfb_...',
});
client.orchestrator.workflows.list();

Properties

`client.config`

Read-only resolved settings. Useful for debugging.

runtimeSkytellsRuntime

'default' | 'edge' | 'node' | 'browser'

requestTimeoutMsnumber

Resolved timeout: 60000 (default) or 25000 (edge mode).

prefetchMaxSlugsnumber

Model compatibility cache size: 64 (default) or 16 (edge mode).

`client.runtime`

Returns the runtime from ClientOptions.runtime. Defaults to 'default'.

console.log(client.config.runtime);          // 'default'
console.log(client.config.requestTimeoutMs); // 60000
console.log(client.config.prefetchMaxSlugs); // 64

console.log(client.runtime); // 'default'

Core Methods

These are top-level methods on the client. Each is documented in detail in its own page.

Method	Returns	Description
`client.run(model, options, onProgress?, sdk?)`	`Promise<Prediction>`	Submit + wait. See Predictions
`client.predict(payload, sdk?)`	`Promise<PredictionResponse>`	Low-level submit. See Predictions
`client.wait(prediction, options?, onProgress?)`	`Promise<PredictionResponse>`	Poll until terminal. See Predictions
`client.queue(payload, sdk?)`	`void`	Queue a prediction. See Predictions
`client.dispatch()`	`Promise<PredictionResponse[]>`	Fire all queued. See Predictions
`client.webhookListener(options?)`	`WebhookListener`	Create webhook handler. See Webhooks
`client.listen(options?)`	`WebhookListener`	Alias of `webhookListener()`
`client.purgePrefetchedModelCache(slug?)`	`void`	Clear model metadata cache

Core Methods

run()

const prediction = await client.run('flux-pro', {
input: { prompt: 'An astronaut on Mars' },
});
console.log(prediction.outputs());

Two Products, Two Transports

The SDK wraps two independent Skytells products that share a single SkytellsClient but use entirely separate HTTP stacks. This is a core design principle — Skytells is committed to providing the best developer experience by combining its product APIs under one unified SDK while maintaining strict security isolation between them.

Product	Key prefix	Base URL	Auth headers
Inference API	`sk-…`	`api.skytells.ai/v1`	`x-api-key` + `Authorization: Bearer`
Orchestrator	`wfb_…`	`orchestrator.skytells.ai`	`Authorization: Bearer` only

The SDK enforces this separation automatically:

The Orchestrator key is never sent to api.skytells.ai
The platform key is never sent to orchestrator.skytells.ai
Any x-api-key in shared headers is stripped from Orchestrator requests

// Both products from one client
const client = Skytells('sk-platform-key', {
orchestratorApiKey: 'wfb_orchestrator-key',
});

// Inference → api.skytells.ai (uses sk- key)
await client.run('flux-pro', { input: { prompt: '...' } });

// Orchestrator → orchestrator.skytells.ai (uses wfb_ key)
await client.orchestrator.workflows.list();

Best Practices

Reuse one client per application. Sub-APIs are lazily allocated singletons — creating a new client per request wastes memory.

// module-level singleton
export const skytells = Skytells(process.env.SKYTELLS_API_KEY);

Use AbortSignal in serverless/edge. Bound wait() and run() polling with maxWait or an AbortSignal to prevent the runtime from hanging.
Use runtime: 'edge' for Cloudflare Workers and Vercel Edge — it auto-tunes timeouts and cache sizes.
Use separate clients when you need different retry policies for different APIs (e.g. no retry for predictions, 3 retries for embeddings).
Clean up after yourself. Delete predictions and assets when no longer needed:

const prediction = await client.run('flux-pro', { input: { prompt: '...' } });
// ... use prediction.output ...
await prediction.delete();

For error handling details, see Errors. For timeout/retry configuration, see Reliability. For authentication setup, see API Keys.

How is this guide?

Three ways to create a client

Creating a Client

Client Options

Core Methods

On this page