SDKs

The AIOZ AI SDKs are thin client libraries that wrap the HTTP API with idiomatic types and call signatures for each supported language. They handle authentication, request serialization, response unwrapping, and error mapping 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.

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 and the same call shape; once you've used one, you can move to another by translating naming conventions (snake_case ↔ camelCase ↔ PascalCase).

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

Python

pip install aiozai-sdk

Node

npm install @aioz-network/aiozai-sdk

Go

go get github.com/aioz-network/aiozai-sdk-go

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.

Python

import os
from aiozai_sdk import AiozAI
 
client = AiozAI(api_key=os.environ["AIOZ_AI_API_KEY"])

Node

import { AiozAI } from "@aioz-network/aiozai-sdk";
 
const client = new AiozAI({ apiKey: process.env.AIOZ_AI_API_KEY });

Go

import (
    "os"
    aiozai "github.com/aioz-network/aiozai-sdk-go"
)
 
c, err := aiozai.NewClient(aiozai.WithAPIKey(os.Getenv("AIOZ_AI_API_KEY")))
if err != nil {
    panic(err)
}

Configuration options

The constructor accepts optional settings beyond the API key:

• base_url / baseUrl / WithBaseURL: override the API base URL. Useful if AIOZ AI provides you with a staging endpoint.
• timeout / timeoutMs / WithTimeout: 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.

Python

client = AiozAI(
    api_key=os.environ["AIOZ_AI_API_KEY"],
    base_url="https://api.aiozai.network/api/v1",
    timeout=60.0,
)

Node

const client = new AiozAI({
  apiKey: process.env.AIOZ_AI_API_KEY,
  baseUrl: "https://api.aiozai.network/api/v1",
  timeoutMs: 60_000,
});

Go

c, err := aiozai.NewClient(
    aiozai.WithAPIKey(os.Getenv("AIOZ_AI_API_KEY")),
    aiozai.WithBaseURL("https://api.aiozai.network/api/v1"),
    aiozai.WithTimeout(60 * time.Second),
)

The resource map

All three SDKs are organized the same way: a root client exposes resource groups (account, tasks, models), and each resource exposes verbs (create, get, list, cancel, and resource-specific ones). The exact method shape mirrors the API Reference endpoint-for-endpoint.

The same naming maps onto each language with that language's casing conventions:

The point is that learning one resource teaches you the rest. Once you've used tasks.get, you know the shape of models.get. Once you've paginated tasks.list, you can paginate models.list the same way.

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 unwrapping. The raw HTTP responses are wrapped in { "status": ..., "message": ..., "data": ... }. The SDKs strip that wrapper and hand you the data payload directly, so your code calls client.tasks.get(id).status instead of response["data"]["status"].
• Typed responses. Responses are deserialized into typed objects (Task, Model, Balance, etc.) in each language's idiomatic style: dataclasses in Python, typed objects in TypeScript, structs in Go.
• Typed errors. Failed requests don't return { "status": "fail" } for you to inspect; they raise an APIError exception (or return a typed error in Go) carrying the HTTP status code and the server's message.
• Pagination helpers. List endpoints return a typed Page<T> with records and total, so you don't have to remember the envelope shape.

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.

Python: raises AiozAPIError.

from aiozai_sdk import AiozAI, AiozAPIError
 
try:
    task = client.tasks.get("does-not-exist")
except AiozAPIError as e:
    print(e.status_code, e.status, e.message)

Node: throws AiozApiError.

import { AiozAI, AiozApiError } from "@aioz-network/aiozai-sdk";
 
try {
  const task = await client.tasks.get("does-not-exist");
} catch (e) {
  if (e instanceof AiozApiError) {
    console.log(e.statusCode, e.status, e.message);
  }
}

Go: returns *aiozai.APIError.

task, err := c.Tasks().Get(ctx, "does-not-exist")
if err != nil {
    var apiErr *aiozai.APIError
    if errors.As(err, &apiErr) {
        fmt.Println(apiErr.StatusCode, apiErr.Status, apiErr.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 at v1: 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, 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.
• Watch your SDK's GitHub Releases page for any breaking changes before bumping versions: Python (opens in a new tab), Node (opens in a new tab), Go (opens in a new tab).
• Test in staging before rolling a version bump to production.

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.