API Reference

The complete reference for every endpoint exposed by the AIOZ AI API today. Endpoints are organized into three resource groups (Account, Tasks, and Models), matching the structure of the SDKs.

For an introduction to the API and where things sit, see the Overview. For a runnable walkthrough, see the Quickstart. For the cross-language SDK install and configuration steps, see SDKs.

Conventions

Base URL:

https://api.aiozai.network/api/v1

All endpoint paths in this reference are relative to that base URL.

Authentication. Every endpoint requires the x-api-key request header. See Authentication for how to send it.

x-api-key: $AIOZ_AI_API_KEY

Response envelope. Every successful response is wrapped in a JSON object of the shape:

{
  "status": "success",
  "message": "...",
  "data": { ... }
}

The data field contains the actual payload. The SDKs unwrap this envelope automatically: when you call client.tasks.get(id), you get the Task object directly, not the wrapper. The raw envelope only matters when you're calling the API directly with curl or another HTTP client.

Errors. Failed requests return a non-2xx status code with a body of:

{
  "status": "fail",
  "message": "human-readable error description"
}

In the SDKs, failed requests raise an APIError (AiozAPIError in Python, AiozApiError in Node) carrying status_code, status, and message. See Errors, Rate Limits & Quotas for the full error model.

Pagination. List endpoints return a page object:

{
  "records": [ ... ],
  "total": 42
}

records is the slice for the current page; total is the count across all pages. Pages are controlled by limit (page size) and offset (records to skip). The SDKs return a typed Page<T> with the same two fields.

Monetary fields. Balance, cost, and price fields are returned as decimal strings rather than numbers, to preserve precision across the wire. Don't parse them as floats if you need exact arithmetic; use your language's decimal type instead.

Timestamps. All timestamps are ISO 8601 in UTC, e.g. 2026-05-28T09:44:53.583612Z.

Account

The Account resource exposes information about the user or organization that owns the API key making the call.

account.balance: Get account balance

GET /api-key/balance

Returns the current balance, free credits, debt, and total earnings for the account that owns the API key. See How Billing Works for what each field means and how billing is applied to tasks.

Parameters. None.

curl

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

Python

balance = client.account.balance()

Node

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

balance, err := c.Account().Balance(ctx)

Response. Returns a Balance object.

{
  "status": "success",
  "message": "ok",
  "data": {
    "balance": "12.34",
    "free_balance": "0",
    "debt": "0",
    "earnings": "0.50",
    "wallet_address": "0x9f3a..."
  }
}

Tasks

The Tasks resource is the core of the API: every model inference runs as a task. Tasks are asynchronous; submit one with create, then poll with get until it reaches a terminal status. See How Tasks Work for the full lifecycle.

tasks.create: Submit an inference task

POST /api-key/task

Creates a new inference task on the specified model and returns the task's ID. The task runs asynchronously on the AIOZ network; read the result back with tasks.get.

Body fields.

Field	Type	Required	Description
`model_id`	string	yes	The ID of the model to run. List models with `models.list`.
`input_params`	object	no	Model-specific input parameters. Shape depends on the model.
`files`	array of `TaskFile`	no	File inputs, keyed by the input slot the model expects.

TaskFile is {"key": "input_slot_name", "data": "https://... or inline data"}.

curl

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

Python

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

Node

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

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

Response. The raw API response is a doubly-wrapped envelope; the SDKs return the bare task ID as a string.

{
  "status": "success",
  "message": "ok",
  "data": {
    "data": "task-4c2396b0-4a69-420a-a3aa-f17683c31461"
  }
}

tasks.get: Get a task by ID

GET /api-key/task/{id}/detail

Returns the current state of a task: its status, and (if completed) its result. Use this to poll a task until it reaches a terminal status (success, failed, or cancelled).

Path parameters.

Parameter	Type	Description
`id`	string	The task ID to fetch.

curl

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

Python

task = client.tasks.get(task_id)

Node

const task = await client.tasks.get(taskId);

task, err := c.Tasks().Get(ctx, taskID)

Response. Returns a Task object.

{
  "status": "success",
  "message": "ok",
  "data": {
    "id": "task-4c2396b0-4a69-420a-a3aa-f17683c31461",
    "task_id": "task-4c2396b0-4a69-420a-a3aa-f17683c31461",
    "status": "success",
    "cost": "0.05",
    "message": "",
    "input_data": { "input": "https://example.com/your-image.jpg" },
    "input_format": { "input": { "type": "file", "mime_type": ["image/*"] } },
    "output_format": { "output_file": { "type": "file", "mime_type": ["image/*"] } },
    "result": { "output_file": "https://s3.w3s.aioz.network/.../output.png" },
    "created_at": "2026-05-28T09:44:53Z",
    "updated_at": "2026-05-28T09:45:01Z"
  }
}

tasks.list: List your task history

GET /api-key/task/histories

Returns a paginated list of every task you've created with this API key, newest first. Useful for building dashboards, debugging, or auditing usage.

Query parameters.

Parameter	Type	Default	Description
`limit`	integer	10	Page size: number of tasks to return.
`offset`	integer	0	Number of tasks to skip before returning the page.

curl

curl "https://api.aiozai.network/api/v1/api-key/task/histories?limit=20&offset=0" \
  -H "x-api-key: $AIOZ_AI_API_KEY"

Python

page = client.tasks.list(limit=20, offset=0)
for task in page.records:
    print(task.task_id, task.status)

Node

const page = await client.tasks.list({ limit: 20, offset: 0 });
for (const task of page.records) {
  console.log(task.taskId, task.status);
}

page, err := c.Tasks().List(ctx, aiozai.ListOptions{Limit: 20, Offset: 0})
for _, t := range page.Records {
    fmt.Println(t.TaskID, t.Status)
}

Response. Returns a Page<Task>.

{
  "status": "success",
  "message": "ok",
  "data": {
    "records": [
      {
        "task_id": "task-4c2396b0-4a69-420a-a3aa-f17683c31461",
        "status": "success",
        "model_id": "MODEL_ID",
        "cost": "0.05",
        "created_at": "2026-05-28T09:44:53Z",
        "updated_at": "2026-05-28T09:45:01Z"
      }
    ],
    "total": 137
  }
}

tasks.cancel: Cancel a queued task

DELETE /api-key/task/{id}/cancel

Cancels a task that's still in_queue. Once a task has moved to computing, it can no longer be cancelled and will run to completion. See How Tasks Work for cancellation semantics.

Path parameters.

Parameter	Type	Description
`id`	string	The task ID to cancel.

curl

curl -X DELETE \
  https://api.aiozai.network/api/v1/api-key/task/$TASK_ID/cancel \
  -H "x-api-key: $AIOZ_AI_API_KEY"

Python

client.tasks.cancel(task_id)

Node

await client.tasks.cancel(taskId);

err := c.Tasks().Cancel(ctx, taskID)

Response. Returns no payload on success.

{
  "status": "success",
  "message": "ok"
}

Models

The Models resource exposes the catalog of runnable models: listing, fetching details, quoting the cost of a task, and checking whether a model is currently serving.

models.list: List available models

POST /api-key/model/list

Returns a paginated list of models you can run. Optionally filter by keyword.

Body fields.

Field	Type	Required	Description
`limit`	integer	no	Page size. Defaults to 10.
`offset`	integer	no	Records to skip before returning the page. Defaults to 0.
`keyword`	string	no	Filter models whose name or description matches the keyword.

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": 10, "offset": 0, "keyword": "image"}'

Python

page = client.models.list(limit=10, offset=0, keyword="image")
for model in page.records:
    print(model.id, model.name)

Node

const page = await client.models.list({ limit: 10, offset: 0, keyword: "image" });
for (const model of page.records) {
  console.log(model.id, model.name);
}

page, err := c.Models().List(ctx, aiozai.ModelListOptions{
    Limit: 10, Offset: 0, Keyword: "image",
})

Response. Returns a Page<Model>. Model objects in the list view carry the headline fields (id, name, description, price, flags); fetch a single model with models.get for the full record.

{
  "status": "success",
  "message": "ok",
  "data": {
    "records": [
      {
        "id": "MODEL_ID",
        "name": "Background_Removal",
        "username": "AIOZAI",
        "description": "Remove the background from an image.",
        "is_official": true,
        "is_verified": true,
        "is_released": true,
        "price": "0.05"
      }
    ],
    "total": 87
  }
}

models.get: Get a model by ID

GET /api-key/model/{id}

Returns the full record for a single model, including its metadata, supported inputs and outputs, license, and tags.

Path parameters.

Parameter	Type	Description
`id`	string	The model ID to fetch.

curl

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

Python

model = client.models.get(model_id)

Node

const model = await client.models.get(modelId);

model, err := c.Models().Get(ctx, modelID)

Response. Returns a Model object.

{
  "status": "success",
  "message": "ok",
  "data": {
    "id": "MODEL_ID",
    "name": "Background_Removal",
    "username": "AIOZAI",
    "description": "Remove the background from an image.",
    "is_official": true,
    "is_verified": true,
    "is_released": true,
    "price": "0.05",
    "model_metadata": {
      "id": "...",
      "model_id": "MODEL_ID",
      "pretty_name": "Background Removal",
      "task": "image-segmentation",
      "license": "apache-2.0",
      "library": ["onnx"],
      "language": "en"
    },
    "created_at": "2026-04-01T00:00:00Z",
    "updated_at": "2026-05-12T12:00:00Z"
  }
}

models.task_cost: Quote the cost of running a task

GET /api-key/model/{id}/task/cost

Returns a price quote for running a single inference on the specified model, in your account's billing currency. Useful for budgeting before submitting a task. See How Billing Works.

Path parameters.

Parameter	Type	Description
`id`	string	The model ID to quote.

curl

curl https://api.aiozai.network/api/v1/api-key/model/$MODEL_ID/task/cost \
  -H "x-api-key: $AIOZ_AI_API_KEY"

Python

quote = client.models.task_cost(model_id)

Node

const quote = await client.models.taskCost(modelId);

quote, err := c.Models().TaskCost(ctx, modelID)

Response. Returns a TaskCost object.

{
  "status": "success",
  "message": "ok",
  "data": {
    "cost": "0.05",
    "symbol": "$",
    "unit": "USD"
  }
}

models.serving: Check whether a model is currently serving

GET /api-key/model/{id}/serving

Returns whether the model has at least one serving node available right now, along with how many consumers are currently using it. Useful for pre-flight checks before submitting a task: a model with no serving nodes can still accept tasks (they queue in in_queue), but may take significantly longer to start.

Path parameters.

Parameter	Type	Description
`id`	string	The model ID to check.

curl

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

Python

status = client.models.serving(model_id)
print(status.serving, status.consumers)

Node

const status = await client.models.serving(modelId);
console.log(status.serving, status.consumers);

status, err := c.Models().Serving(ctx, modelID)

Response. Returns a ServingStatus object.

{
  "status": "success",
  "message": "ok",
  "data": {
    "serving": true,
    "consumers": 3
  }
}

Types

The shapes returned (and accepted) by the endpoints above. SDK types follow each language's naming conventions: snake_case in Python, camelCase in Node/TypeScript, PascalCase in Go.

Balance

The current state of an account's credit.

Field	Type	Description
`balance`	string	Available balance, as a decimal string.
`free_balance`	string	Free credits, as a decimal string.
`debt`	string	Accrued debt, if any, as a decimal string.
`earnings`	string	Total earnings from models you've published.
`wallet_address`	string	The wallet address the account is associated with.

Task

A single inference run.

Field	Type	Description
`id`	string	Task identifier. Same value as `task_id`; both are kept for compatibility.
`task_id`	string	Task identifier.
`status`	`TaskStatus`	Current lifecycle status.
`cost`	string	Charge for this task, as a decimal string. Meaningful only on `success`.
`message`	string	Failure description; present on `failed`.
`input_data`	object	The inputs originally submitted.
`input_format`	object	The model's declared input schema at the time the task ran.
`output_format`	object	The model's declared output schema at the time the task ran.
`result`	object	Model output; present on `success`. Shape depends on the model.
`created_at`	string (ISO 8601)	When the task was created.
`updated_at`	string (ISO 8601)	When the task's status last changed.

TaskStatus

A string enumeration of the lifecycle states a task can be in.

Value	Terminal?	Meaning
`in_queue`	No	Accepted, waiting for a serving node to pick it up.
`computing`	No	A node is actively running the model.
`success`	Yes	The model finished and produced a result.
`failed`	Yes	The model errored.
`cancelled`	Yes	The task was cancelled before it could complete.

Model

The catalog entry for a single model.

Field	Type	Description
`id`	string	Model identifier.
`name`	string	Model name (technical identifier).
`username`	string	Owner's account name.
`description`	string	Short description.
`is_official`	bool	Whether the model is published by AIOZ AI.
`is_verified`	bool	Whether the model has been verified to run on the network.
`is_released`	bool	Whether the model is publicly listed.
`price`	string	Price per inference, as a decimal string.
`model_metadata`	object	Additional metadata: pretty name, task type, license, libraries.
`created_at`	string (ISO 8601)	When the model was first published.
`updated_at`	string (ISO 8601)	When the model was last updated.

TaskCost

A price quote for a single inference.

Field	Type	Description
`cost`	string	The quoted cost, as a decimal string.
`symbol`	string	Currency symbol, e.g. `$`.
`unit`	string	Currency code, e.g. `USD`.

ServingStatus

A model's current serving health.

Field	Type	Description
`serving`	bool	Whether at least one node is serving the model now.
`consumers`	integer	Number of clients currently using the model.

Page

A page of records from a list endpoint.

Field	Type	Description
`records`	array of T	The records in this page.
`total`	integer	Total number of records across all pages.

CreateTaskRequest

The input shape accepted by tasks.create.

Field	Type	Required	Description
`model_id`	string	yes	The ID of the model to run.
`input_params`	object	no	Model-specific input parameters.
`files`	array of `TaskFile`	no	File inputs, keyed by the input slot the model expects.

TaskFile

A single file input to a task.

Field	Type	Description
`key`	string	The model's input slot name (e.g. `"input"`).
`data`	string	A URL pointing to the file, or inline data.

APIError

The error type raised by the SDKs on a non-success response. The exact class name varies (AiozAPIError in Python, AiozApiError in Node, *aiozai.APIError in Go), but the shape is the same.

Field	Type	Description
`status_code`	integer	The HTTP status code.
`status`	string	The API `status` field from the response body (e.g. `"fail"`).
`message`	string	The API `message` field, a human-readable error description.