SDKs

The AIOZ AI SDKs are generated client libraries that wrap the HTTP API with idiomatic types and call signatures for each supported language. They handle authentication and request serialization for you, so most of your code can stay focused on what to do with model outputs rather than on the wire protocol.

This page covers what's available, how to install and configure each SDK, how the call shape works across languages, and how to handle errors and versioning. For the contract behind each individual call, see the API Reference.

For full version, please visit https://github.com/AIOZNetwork/aioz-ai-developer (opens in a new tab).

Available SDKs

There are three official SDKs today, one each for Python, Node.js / TypeScript, and Go. All three expose the same set of resources. The underlying concepts transfer across languages; you only translate naming conventions (snake_case ↔ camelCase ↔ PascalCase) and service-group names.

If you'd prefer not to use an SDK (for languages we don't yet support, or because you need finer control over transport), every endpoint is also callable directly over HTTP. See the API Reference for the raw contracts.

Install

npm install @aiozai/nodejs-client

Create a client

A client is the entry point to every call. Construct one with your API key; the same client instance is reusable across many calls, and is safe to share across an application's request handlers.

import { createAiozAIClient, type AiozAIClient } from "@aiozai/nodejs-client";
 
const { rawClient } = createAiozAIClient({
  apiKey: process.env.AIOZ_AI_API_KEY,
});
// the bare hey-api `Client` type isn't exported; derive it when you need to annotate
type Client = AiozAIClient["rawClient"];
const client: Client = rawClient;
// every call takes { client, ... }

Configuration options

The constructor accepts optional settings beyond the API key:

• timeout (Python, seconds) / timeout (Node, milliseconds) / WithTimeout (Go): request timeout. Defaults are sensible for most workloads; raise this if you call long-running model endpoints.
• WithHTTPClient (Go only): provide a custom *http.Client, e.g. one that wraps a corporate proxy or adds custom transport-level instrumentation.

const { rawClient: client } = createAiozAIClient({
  apiKey: process.env.AIOZ_AI_API_KEY,
  timeout: 60_000,
});

The resource map

The SDKs organize methods into service groups. Each service exposes the methods corresponding to that resource's HTTP endpoints.

Account / balance

Tasks

Every task operation, including create, lives on the tasks service group in all three languages.

Models

Python list call: RequestGetModelListRequest() is a typed request object whose fields mirror the API body parameters (limit, offset, filter_by, sort, etc.). Construct it with keyword arguments to apply filters: RequestGetModelListRequest(limit=20, offset=0).

Storage

What the SDKs do for you

Compared to calling the HTTP endpoints directly with curl or a generic HTTP library, the SDKs take care of a few mechanical things so you don't have to:

• Authentication. The x-api-key header is added to every request automatically once you've passed the key to the constructor.

• Envelope passthrough with manual unwrap. The raw HTTP responses are wrapped in { "status": ..., "message": ..., "data": ... }. The SDKs do not strip this wrapper automatically. You unwrap the payload yourself, and the access path differs by language: in Node, resp.data is the envelope and resp.data.data is the payload; in Python, resp is the envelope (resp.status, resp.message) and resp.data is the payload; in Go, read resp.Payload.Data. Task create nests the id one level deeper than other endpoints: resp.data.data.data in Node, resp.data.data in Python, resp.Payload.Data.Data in Go.

  resp = client.core.core.get_balance()
  print(resp.data)   # the unwrapped balance payload

• Typed responses. Responses are deserialized into typed objects in each language's idiomatic style: dataclasses in Python, typed objects in TypeScript, structs in Go.

• Typed errors. Failed requests raise a typed error (see Errors) carrying the HTTP status code and the server's message.

Errors

Every endpoint can fail, whether for network reasons, validation errors, or server-side issues. The SDKs surface failures as a single typed error per language, carrying the HTTP status code and the server's message verbatim.

import { createAiozAIClient, services, AiozApiError } from "@aiozai/nodejs-client";
 
const { rawClient: client } = createAiozAIClient({ apiKey: process.env.AIOZ_AI_API_KEY });
 
try {
  const resp = await services.tasks.getTaskByIdDetail({ client, path: { id: "does-not-exist" } });
} catch (e) {
  if (e instanceof AiozApiError) {
    console.log(e.statusCode, e.errorCode, e.message);
  }
}

For the meaning of HTTP status codes, retry guidance, and rate-limit-specific errors, see Errors, Rate Limits & Quotas.

Versioning and stability

All three SDKs are published, usable, and good enough to build against. Some refinements to the public interface may still happen as we work through real-world usage, so when you ship to production:

• Pin to an exact version in your dependency file (requirements.txt/pyproject.toml, package.json, go.mod) rather than tracking the latest. That way you opt into upgrades when you're ready, not the day a release goes out.

The HTTP API itself is more conservative: breaking changes to endpoint paths, request bodies, or response shapes don't happen casually. If you've built directly against the HTTP layer, you generally don't have to pin or track changes as closely.

When to use the SDK vs the HTTP API

For most use cases, the SDK is the right choice: it removes mechanical work, gives you typed responses, and keeps your integration close to the official conventions. Reach for the raw HTTP API in a few situations:

• Your language isn't supported. If you're building in Ruby, Rust, Java, or anything else without an SDK, call the API directly. The contracts are stable enough to wrap yourself if you want.
• You need finer control over the transport. Custom retry logic, request-level instrumentation, response streaming, and integration with a specific HTTP framework are all easier on the raw API.
• You're scripting in a shell. A one-off curl is faster to write and easier to share than a small script in Python or Node.

Even when using the raw HTTP API, the SDK source code is a useful reference for the conventions; see the source links above.