API Reference

The complete reference for every endpoint exposed by the AIOZ AI API today. Endpoints are organized into four resource groups: Account, Tasks, Models, and Storage.

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 task-create response nests the task id one level deeper, at data.data (see Submit an inference task).

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

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

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 Storage folder-listing endpoint uses a different pagination shape (files array with page/pageSize), documented in its own section.

Monetary fields. The account balance fields (balance, free_balance, debt, earnings) 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. The model price and the task cost fields (the cost quote and a task's cost) are the exception: they are returned as JSON numbers (0 for a free model).

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.

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.

Request

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

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

Every model inference runs as a task, and tasks are asynchronous. See Working with Tasks for the full lifecycle.

Submit an inference task

POST /api-key/model/{id}/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 Get a task by ID.

Path parameters.

Parameter	Type	Description
`id`	string	The ID of the model to run. List models with List available models.

Body. The model-specific input object directly (shape depends on the model; see the model's page). Example: {"input": "https://example.com/your-image.jpg"}.

Request

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"}'

Response. The raw API response is a doubly-wrapped envelope. The task ID is nested one level deeper than other endpoints.

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

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.

Path parameters.

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

Request

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

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": {
      "result": { "output_file": "https://s3.w3s.aioz.network/.../output.png" },
      "error": null
    },
    "created_at": "2026-05-28T09:44:53Z",
    "updated_at": "2026-05-28T09:45:01Z"
  }
}

List your task history

GET /api-key/task/histories

Returns a paginated list of every task you've created with this API key, oldest first.

Query parameters.

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

Request

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

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
  }
}

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 canceled and will run to completion. See Working with Tasks for cancellation semantics.

Path parameters.

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

Request

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

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.

List available models

POST /api-key/model/list

Returns a paginated list of models you can run. Optionally filter by search term, sort order, and category.

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.
`search`	string	no	Filter models whose name or description matches the search term.
`sort`	string	no	Sort order. One of: `created_oldest`, `created`, `modified`, `likes`, `downloads`, `trending`.
`filter_by`	string	no	Category filter. One of: `official`, `public`, `community`, `author`, `playground`, `permission` (returns models the caller has access to, including private ones).

Request

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, "search": "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 Get a model by ID 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,
        "visibility": "public",
        "price": 0.05
      }
    ],
    "total": 87
  }
}

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.

Request

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

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,
    "visibility": "public",
    "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"
  }
}

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. See How Billing Works.

Path parameters.

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

Request

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

Response. Returns a TaskCost object.

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

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.

Path parameters.

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

Request

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

Response. Returns a ServingStatus object.

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

Get a model's input/output schema

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

Returns the active model version's declared input and output schema: the exact parameter names, types, and constraints the model expects. Use this to build the body for Submit an inference task programmatically instead of hard-coding a model's inputs.

Path parameters.

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

Request

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

Response. Returns a ModelVersioning object. input_format and output_format each map a parameter name to a descriptor object. The example below is abbreviated; the exact parameters depend on the model.

{
  "status": "success",
  "message": "ok",
  "data": {
    "model_id": "MODEL_ID",
    "commit_hash": "252ef66f...",
    "is_active": true,
    "input_format": {
      "input_image": {
        "type": "file",
        "mime_type": ["image/*"],
        "required": true,
        "position": 0,
        "samples": ["https://.../sample.jpg"]
      },
      "angle": {
        "type": "int",
        "required": true,
        "position": 2,
        "num_config": { "min": 1, "max": 90, "step": 1 },
        "samples": ["45"]
      }
    },
    "output_format": {
      "output_image": { "type": "file", "mime_type": ["image/*"], "position": 0 }
    }
  }
}

Note on typing. Input values are submitted as the type the descriptor names, but several models declare numeric-looking parameters that must still be sent as strings (e.g. angle above has type: "int", yet its samples are ["45"] and the API rejects a bare 45). When in doubt, mirror the samples shape.

Storage

The Storage resource manages file uploads via presigned URLs: create a presigned upload target, list a folder's files, check usage statistics, and delete files. See Working with Storage for the full upload flow.

Create a presigned upload URL

POST /api-key/storage/upload/create-presigned-url

Creates a presigned S3 upload target for a single file. The response contains an endpoint, a download_url, and form fields. See Working with Storage for the full two-step upload flow.

Both this call and the subsequent file upload require a positive account balance and will fail otherwise. Storage is billed separately from inference; see the platform's payments documentation.

Body fields.

Field	Type	Required	Description
`folder`	string	yes	Destination folder. One of: `avatars`, `thumbnails`, `covers`, `samples`, `documents`.
`mime`	string	yes	MIME type of the file, e.g. `image/png`.
`name`	string	yes	Filename for the uploaded object.
`size`	integer	yes	File size in bytes. Must be greater than 0.
`org_username`	string	no	Personal-scope keys only: the username of an organization you belong to, to upload into that organization's storage. Has no effect with an organization-scope key.

Request

curl https://api.aiozai.network/api/v1/api-key/storage/upload/create-presigned-url \
  -H "x-api-key: $AIOZ_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folder": "documents", "mime": "image/png", "name": "photo.png", "size": 204800}'

Response. Returns a PresignedUpload object.

{
  "status": "success",
  "message": "ok",
  "data": {
    "endpoint": "https://...",
    "download_url": "https://...",
    "fields": "{...}"
  }
}

The fields value is a JSON-encoded string. Parse it, then include each key-value pair as a form field in the multipart POST to endpoint, with the file content last as the file field.

List a folder's files

GET /api-key/storage/upload/{folder}

Returns a paginated list of files in the specified storage folder.

Path parameters.

Parameter	Type	Description
`folder`	string	The folder name to list.

Query parameters.

Parameter	Type	Description
`page`	integer	Page number (1-based).
`pageSize`	integer	Files per page.
`type`	string	Optional MIME category filter. One of: `image`, `audio`, `video`, `application`, `text`.

Request

curl "https://api.aiozai.network/api/v1/api-key/storage/upload/$FOLDER?page=1&pageSize=10" \
  -H "x-api-key: $AIOZ_AI_API_KEY"

Response. Returns an object with a files array of StorageFile objects, plus pagination fields (total, total_pages).

{
  "status": "success",
  "message": "ok",
  "data": {
    "files": [
      {
        "id": "file-abc123",
        "download_url": "https://...",
        "folder": "documents",
        "key": "documents/photo.png",
        "mime": "image/png",
        "size": 204800,
        "status": true,
        "is_expired": false,
        "created_at": "2026-05-28T09:44:53Z"
      }
    ],
    "total": 42,
    "total_pages": 5
  }
}

Get storage statistics

GET /api-key/storage/upload/statistics

Returns aggregate statistics for your storage usage.

Parameters. None.

Request

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

Response. Returns a StorageStatistics object.

{
  "status": "success",
  "message": "ok",
  "data": {
    "total_files": 7,
    "total_size": 2048576
  }
}

Delete a file

DELETE /api-key/storage/w3s/url

Deletes a previously uploaded file identified by its download_url. Pass the download_url received from the presign response (or from the folder listing).

Body fields.

Field	Type	Required	Description
`url`	string	yes	The `download_url` of the file to delete.

Request

curl -X DELETE https://api.aiozai.network/api/v1/api-key/storage/w3s/url \
  -H "x-api-key: $AIOZ_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://..."}'

Response.

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

Types

The shapes returned (and accepted) by the endpoints above. The field names below are the JSON wire names.

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`	number	Charge for this task, as a JSON number. 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	Inference result envelope: `{ "result": <model output>, "error": <error detail> }`. On `success`, the model output is nested at `result.result` (shape depends on the model); on `failed`, `result.error` holds the error detail.
`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.
`canceled`	Yes	The task was canceled 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.
`visibility`	string	Listing visibility: `public` or `private`.
`price`	number	Price per inference, as a JSON number (`0` for a free model).
`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.

ModelVersioning

The active version's declared input/output schema, returned by Get a model's input/output schema.

Field	Type	Description
`model_id`	string	The model this versioning describes.
`commit_hash`	string	Identifier of the active model version.
`is_active`	bool	Whether this version is the one currently serving.
`input_format`	object	Map of input parameter name → descriptor. Each descriptor carries at least `type` and `required`, and may include `mime_type`, `position`, `samples`, `options` (for enum params), and `num_config` (`min`/`max`/`step` for numeric params).
`output_format`	object	Map of output name → descriptor (`type`, `mime_type`, `position`).

TaskCost

A price quote for a single inference.

Field	Type	Description
`cost`	number	The quoted cost, as a JSON number.
`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<T>

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.

PresignedUpload

The response from Create a presigned upload URL.

Field	Type	Description
`endpoint`	string	The S3 URL to POST the file to.
`download_url`	string	The permanent download URL for the file once uploaded.
`fields`	string	JSON-encoded string of form fields to include in the multipart POST to `endpoint`.

StorageFile

A single file entry returned by the folder-listing endpoint.

Field	Type	Description
`id`	string	File identifier.
`download_url`	string	Permanent download URL for the file.
`folder`	string	The folder the file belongs to.
`key`	string	Storage path key for the object.
`mime`	string	MIME type of the file.
`size`	integer	File size in bytes.
`status`	bool	Whether the file is active.
`is_expired`	bool	Whether the file's storage has expired.
`created_at`	string (ISO 8601)	When the file was uploaded.

StorageStatistics

Aggregate storage usage for the account.

Field	Type	Description
`total_files`	integer	Number of files you've uploaded.
`total_size`	integer	Aggregate size of those files, in bytes.
`folders`	object	Optional. Per-folder breakdown mapping folder name → `{ total_files, total_size }`.

APIError

The body returned on a non-success response.

Field	Type	Description
`status`	string	Always `"fail"` on error.
`message`	string	Human-readable error description.