Working with Tasks

Every time you run a model on the AIOZ AI API, the API creates a task: an asynchronous job that moves through a lifecycle from queued to terminal. This guide assumes you already have a model ID (see Working with Models). Running a model costs credits, so the guide starts with how to check your balance, then walks through creating a task, polling it to completion, reviewing history, and cancelling when needed.

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. Check your balance before you run

Each inference deducts credits, so confirm you have enough before submitting. The balance and free_balance fields are returned as decimal strings; see How Billing Works for the billing rules.

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

2. Create a task

Submit a task by passing a model ID and an input payload. The input shape is model-specific, so check the model's page for the exact fields. The example below uses a generic image URL input; replace it with the shape your model expects.

The create call returns a task ID which you use for all subsequent operations.

MODEL_ID="your-model-id-here"
 
curl -X POST "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"}'

3. The task lifecycle

Tasks move through the following statuses in order. Poll the detail endpoint until you reach a terminal status.

Polling guidance: check status every 2–5 seconds for fast models; back off to 10–30 seconds for long-running jobs. Stop as soon as the status is terminal; further polling is unnecessary.

For the full set of fields available on a task object (output, error message, timestamps, cost, etc.) see Endpoints Reference.

4. Poll to completion

Call getTaskByIdDetail in a loop until the status is terminal.

TASK_ID="your-task-id-here"
 
while true; do
  STATUS=$(curl -s "https://api.aiozai.network/api/v1/api-key/task/$TASK_ID/detail" \
    -H "x-api-key: $AIOZ_AI_API_KEY" \
    | jq -r '.data.status')
  echo "Status: $STATUS"
  case "$STATUS" in
    success|failed|canceled) break ;;
  esac
  sleep 3
done

5. When a task fails on balance

If you have insufficient credits, the API can refuse a create call outright with an error response, or the task can be created but immediately transition to failed with a message indicating the balance problem. In either case:

1. Re-check your balance with getBalance (see section 1).
2. Top up your credits; see How Billing Works for instructions.
3. Retry postModelByIdTask once your balance covers the model's cost.

You can get the model's per-inference cost before submitting by calling getModelByIdTaskCost; see Working with Models.

6. List your task history

getTaskHistories returns a paginated list of past tasks. Results are ordered oldest-first, so the most recent tasks appear on later pages. Use limit and offset to page through them.

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

7. Cancel a task

Send a cancel request to stop a task that is still in_queue. Once a task reaches computing, the node is already running the model and the cancel request cannot interrupt it. A successful cancel returns a status of "success".

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

Where to next

• How Billing Works: when credits are deducted, how free credits are consumed, and what happens on failure or cancellation.
• Working with Models: browse the model catalog, inspect input/output schemas, and quote inference cost before you submit.