Quickstart

This guide walks you through running your first inference on the AIOZ AI API, end to end: call the HTTP API directly or install an SDK, 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 language with an HTTP client.

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.

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

2. Verify your key works

Before doing real work, make a small call to confirm authentication is set up correctly. Fetching your account balance is a good choice:

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

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

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.

If your input is a local file rather than a URL, upload it to AIOZ AI first and pass the returned download_url; see Working with Storage.

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

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 canceled). A 2-second interval is a reasonable starting point. For background on the lifecycle and statuses, see Working with Tasks.

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" = "canceled" ]; then
    echo "$RESPONSE" | jq .
    break
  fi
  sleep 2
done

6. Read the result

If status is success, the model's output is nested at result.result. The task's result field is an envelope of the form { "result": <output>, "error": <error detail> }, so reach one level in for the output. The shape of result.result 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.

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

If status is failed, the message field describes the error. Inspect it, correct your input, and call post_model_by_id_task / postModelByIdTask / PostModelByIDTask again to retry. Failed and canceled 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.
• Working with Tasks: 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.