Configuration
Configure the SDK globally or per-instance.
Getting Started
Quick setup guide.
Error Handling
Retry policies and error types.
Zaby client
The Zaby constructor accepts:
api_key
str | () → str | () → Awaitable[str]
required
API key for x-zaby-api-key header. Can be a static string, sync callable, or async callable.
access_token
str | () → str | () → Awaitable[str]
JWT for Authorization: Bearer header. Optional for most provisioning endpoints.
Custom transport. Use MockTransport for testing.
Per-instance configuration overrides.
Global configuration
Set defaults shared across all client instances:
from zaby import configure_zaby, ZabyGlobalConfig
configure_zaby(ZabyGlobalConfig(
api_origin="https://custom.io",
timeout_ms=60_000,
retries=3,
user_agent="my-app/1.0",
))
import { configureZaby } from "@zaby-ai/sdk";
configureZaby({
apiOrigin: "https://custom.io",
timeoutMs: 60_000,
retries: 3,
userAgent: "my-app/1.0",
});
zaby = Zaby(
api_key="zaby_pk_...",
config=ZabyGlobalConfig(timeout_ms=120_000),
)
import { Zaby } from "@zaby-ai/sdk";
const zaby = new Zaby({
apiKey: "zaby_pk_...",
config: { timeoutMs: 120_000 },
});
Instance config merges over globals — only specify the fields you want to override.
Config fields
type
string
default:"https://genapi.zaby.io"
Base URL for all API requests. Override for local development or custom deployments.
ZabyGlobalConfig(api_origin="http://localhost:9080")
configureZaby({ apiOrigin: "http://localhost:9080" });
timeout_ms — Request timeout
Maximum time to wait for a response, in milliseconds.
ZabyGlobalConfig(timeout_ms=60_000)
configureZaby({ timeoutMs: 60_000 });
retries — Retry configuration
Configure which requests are retried and how.from zaby import RetryPolicy
ZabyGlobalConfig(retries=RetryPolicy(
attempts=3,
retry_methods=["GET", "HEAD", "OPTIONS"],
retry_statuses=[408, 429, 500, 502, 503, 504],
backoff_ms=lambda attempt: min(100 * 2 ** attempt, 1000),
))
# Integer shorthand
ZabyGlobalConfig(retries=3)
configureZaby({
retries: {
attempts: 3,
retryMethods: ["GET", "HEAD", "OPTIONS"],
retryStatuses: [408, 429, 500, 502, 503, 504],
backoffMs: (attempt) => Math.min(100 * 2 ** attempt, 1000),
},
});
// Integer shorthand
configureZaby({ retries: 3 });
user_agent — Custom User-Agent
ZabyGlobalConfig(user_agent="my-app/1.0")
configureZaby({ userAgent: "my-app/1.0" });
environment — Environment preset
type
string
default:"production"
Retry policy
retry_methods
string[]
default:"[\"GET\", \"HEAD\", \"OPTIONS\"]"
HTTP methods eligible for retry
retry_statuses
int[]
default:"[408, 429, 500, 502, 503, 504]"
Status codes that trigger a retry
backoff_ms
callable
default:"exponential 100ms–1s"
Delay function: lambda attempt: min(100 * 2**attempt, 1000)
Only idempotent methods (GET, HEAD, OPTIONS) are retried by default. POST and other mutating methods are not retried to prevent duplicate operations.
Authentication providers
Credentials can be static strings, lazy callables, or async callables:
# Static string
zaby = Zaby(api_key="zaby_pk_static_key")
# Lazy — called on every request
zaby = Zaby(api_key=lambda: get_current_key())
# Async
async def key_provider() -> str:
return await fetch_key_from_vault()
zaby = Zaby(api_key=key_provider)
import { Zaby } from "@zaby-ai/sdk";
// Static string
const zaby = new Zaby({ apiKey: "zaby_pk_static_key" });
// Lazy — called on every request
const lazy = new Zaby({ apiKey: () => getCurrentKey() });
// Async provider
const asyncClient = new Zaby({
apiKey: async () => fetchKeyFromVault(),
});
Environment variables
# .env or shell
export ZABY_API_ORIGIN=http://192.168.68.61:9080
export ZABY_ENVIRONMENT=local
Explicit api_origin always takes precedence over environment presets.
ZabyRuntime options
token
str | () → str | () → Awaitable[str]
required
JWT runtime token for Authorization: Bearer
Custom transport for testing.
Runtime-specific config overrides.
from zaby import ZabyRuntime
runtime = ZabyRuntime(token="eyJhbGciOi...")
import { ZabyRuntime } from "@zaby-ai/sdk/runtime";
const runtime = new ZabyRuntime({ token: "eyJhbGciOi..." });
