Working with Models

The model catalog is the starting point for every inference task you run on the AIOZ AI API. A model encapsulates a trained neural network, its input/output schema, and the price per inference. This guide covers how to browse the catalog, narrow results with sort and filter options, inspect a specific model's schema and pricing, confirm it is live, and get a cost quote before you commit credits to a task.

Setup

Install an SDK and create a client as described in SDKs. Or, call the HTTP API directly.

Then, export your key in the AIOZ_AI_API_KEY environment variable:

export AIOZ_AI_API_KEY="your-key-here"

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

1. List and search models

Call the list endpoint with a limit and offset to page through the catalog. The response envelope has two fields: records (the current page of models) and total (the total count matching your query, useful for building pagination).

To narrow the catalog by name, add a search field to the same request body, as the second call in each example below does. A search that matches nothing returns total: 0 and a null/empty records array.

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}'
 
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": "stable-diffusion"}'

2. Sort and filter

The same list call accepts sort and filter_by fields to control ordering and scope.

Sort options

Value	Order
`created_oldest`	Oldest first (ascending `created_at`)
`created`	Newest first (descending `created_at`)
`modified`	Most-recently updated first
`likes`	Most-liked first
`downloads`	Most-downloaded first
`trending`	Trending score, most trending first

Filter options

Value	What it includes
`official`	Only models marked as official by AIOZ
`public`	Only models with public visibility
`community`	Only community (non-official) models
`author`	Only models owned by the authenticated user
`playground`	Models available in the playground
`permission`	Models the authenticated caller has access to, including private ones

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 '{"sort": "downloads", "filter_by": "official", "limit": 20, "offset": 0}'

3. Inspect a model

Once you have a model ID, fetch its full record to see its input/output schema and per-inference price. The payload is the model object; its exact fields depend on the model type, but it always includes the ID, name, description, and pricing information.

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

To read a model's exact input and output schema, the parameter names, types, and constraints you need to build a task body, call the versioning endpoint: GET /api-key/model/{id}/versioning. It returns input_format and output_format maps describing each parameter. See Get a model's input/output schema in the API Reference for the full response shape.

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

4. Check serving status

Before submitting a task, verify the model is currently serving requests. The serving field in the response is a boolean: true means the model is live and accepting tasks; false means it is offline or not currently available.

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

5. Quote the cost

Before you create a task, you can ask the API exactly what it will cost. The response includes a cost field (the credit amount per inference) and a unit field. Knowing the price upfront is worth the extra call when you're running many inferences or evaluating an unfamiliar model.

For the billing rules (when you are charged, how credits are deducted, and how to check your balance), see How Billing Works.

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

Where to next

Working with Tasks: submit inference tasks against a model, poll for results, and handle terminal states.
How Billing Works: when credits are deducted, how to check your balance, and what happens on failure or cancellation.