Quickstart

This guide walks you through running your first inference on the AIOZ AI API, end to end: install an SDK (or set up curl), check that your API key works, find a model to run, submit a task, and read back the result.

You'll have a working integration in under five minutes.

Prerequisites

An AIOZ AI account.
An API key. If you don't have one yet, see Managing API Keys. Have the key value handy; you'll set it as an environment variable in the next step.
One of: Python 3.9+, Node.js 18+, Go 1.21+, or any HTTP client that can do curl.

Throughout this guide, your API key is referenced as the environment variable AIOZ_AI_API_KEY:

export AIOZ_AI_API_KEY="your-key-here"

1. Install and configure

Install the AIOZ AI SDK for your language, then create a client. The client reads your key from AIOZ_AI_API_KEY and points at the production API by default.

curl: nothing to install; just keep your key in the environment.

Python

pip install aiozai-sdk

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

Node

npm install @aioz-network/aiozai-sdk

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

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

package main
 
import (
    "context"
    "os"
    aiozai "github.com/aioz-network/aiozai-sdk-go"
)
 
func main() {
    c, err := aiozai.NewClient(aiozai.WithAPIKey(os.Getenv("AIOZ_AI_API_KEY")))
    if err != nil { panic(err) }
    ctx := context.Background()
    _ = ctx; _ = c
}

2. Verify your key works

Before doing real work, make a small call to confirm authentication is set up correctly. account.balance is a good choice: it's cheap, doesn't cost anything to run, and returns immediately.

curl

curl https://api.aiozai.network/api/v1/api-key/balance \
  -H "x-api-key: $AIOZ_AI_API_KEY"

Python

balance = client.account.balance()
print(balance.balance)

Node

const balance = await client.account.balance();
console.log(balance.balance);

balance, err := c.Account().Balance(ctx)
if err != nil { panic(err) }
fmt.Println(balance.Balance)

If you get back a balance value, you're authenticated. If you get a 401, double-check that AIOZ_AI_API_KEY is set in the same shell that's running your code.

3. Find a model to run

List a few available models to pick one to call. The list returns a page of models with their IDs, names, and pricing.

curl

curl https://api.aiozai.network/api/v1/api-key/model/list \
  -H "x-api-key: $AIOZ_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 5, "offset": 0}'

Python

page = client.models.list(limit=5)
for model in page.records:
    print(model.id, "-", model.name)

Node

const page = await client.models.list({ limit: 5 });
for (const model of page.records) {
  console.log(`${model.id} - ${model.name}`);
}

page, err := c.Models().List(ctx, aiozai.ModelListOptions{Limit: 5})
if err != nil { panic(err) }
for _, m := range page.Records {
    fmt.Printf("%s - %s\n", m.ID, m.Name)
}

Pick one of the model IDs from the response; the rest of this guide assumes you've assigned it to MODEL_ID. You can also browse models in the web UI and copy an ID from any model's page.

4. Create a task

Submit an inference task against your chosen model. Each model has its own input schema. The example below uses a typical image-input shape ({"input": "<image url>"}), which works for background-removal-style models. For other models, see the model's own page for its input schema.

curl

curl https://api.aiozai.network/api/v1/api-key/model/{model-id}/task \
  -H "x-api-key: $AIOZ_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{    
    "input": "https://example.com/your-image.jpg"  
  }'

The response includes a task_id you'll use to poll for the result.

Python

task_id = client.tasks.create(
    model_id="MODEL_ID",
    input_params={"input": "https://example.com/your-image.jpg"},
)
print("Created task:", task_id)

Node

const taskId = await client.tasks.create({
  modelId: "MODEL_ID",
  inputParams: { input: "https://example.com/your-image.jpg" },
});
console.log("Created task:", taskId);

taskID, err := c.Tasks().Create(ctx, aiozai.CreateTaskRequest{
    ModelID: "MODEL_ID",
    InputParams: map[string]any{
        "input": "https://example.com/your-image.jpg",
    },
})
if err != nil { panic(err) }
fmt.Println("Created task:", taskID)

5. Poll until the task is done

Tasks are asynchronous, so you read the result by polling the task until its status is terminal (success, failed, or cancelled). A 2-second interval is a reasonable starting point. For background on the lifecycle and statuses, see How Tasks Work.

curl

TASK_ID="paste-task-id-here"
 
while true; do
  RESPONSE=$(curl -s \
    -H "x-api-key: $AIOZ_AI_API_KEY" \
    "https://api.aiozai.network/api/v1/api-key/task/$TASK_ID/detail")
  STATUS=$(echo "$RESPONSE" | jq -r '.data.status')
  if [ "$STATUS" = "success" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ]; then
    echo "$RESPONSE" | jq .
    break
  fi
  sleep 2
done

Python

import time
 
TERMINAL = {"success", "failed", "cancelled"}
 
while True:
    task = client.tasks.get(task_id)
    if task.status in TERMINAL:
        break
    time.sleep(2)
 
print("Final status:", task.status)
print("Result:", task.result)

Node

const TERMINAL = new Set(["success", "failed", "cancelled"]);
 
let task;
while (true) {
  task = await client.tasks.get(taskId);
  if (TERMINAL.has(task.status)) break;
  await new Promise(r => setTimeout(r, 2000));
}
 
console.log("Final status:", task.status);
console.log("Result:", task.result);

terminal := map[aiozai.TaskStatus]bool{
    aiozai.StatusSuccess:   true,
    aiozai.StatusFailed:    true,
    aiozai.StatusCancelled: true,
}
 
var task *aiozai.Task
for {
    task, err = c.Tasks().Get(ctx, taskID)
    if err != nil { panic(err) }
    if terminal[task.Status] {
        break
    }
    time.Sleep(2 * time.Second)
}
 
fmt.Println("Final status:", task.Status)
fmt.Printf("Result: %+v\n", task.Result)

6. Read the result

If status is success, the task's result field contains the model's output. The exact shape depends on the model: an image model returns one or more URLs, a text model returns text, and a structured model returns a JSON object. Refer to the model's API Reference page for its output schema.

If status is failed, the message field describes the error. Inspect it, correct your input, and call tasks.create again to retry. Failed and cancelled tasks aren't billed; see How Billing Works.

You're done

You've just run an end-to-end inference: authenticated, picked a model, submitted a task, and read the result.

Next stops:

API Reference: every endpoint, parameter, and response shape.
SDKs: the cross-language SDK guide covering configuration, error handling, and the resource map.
How Tasks Work: the async lifecycle in depth, plus polling strategies for long-running tasks.
How Billing Works: when you're charged, how to quote a price, and how to check your balance.