Working with Storage

The AIOZ AI Storage service lets you upload files into named folders, browse them, and delete them. Files are stored in an S3-compatible object store and referenced by a stable download_url you can pass to a model as input. Uploading and storing files to AIOZ AI draws on your account balance and is billed per the platform's payments documentation.

Uploading uses a two-step presigned flow: you ask the SDK for a presigned target (step 1), then upload the file bytes directly to that target (not through the SDK) (step 2). This keeps your API key off the upload path and lets you stream files straight to object storage. The upload method (multipart form POST vs raw PUT) is chosen by the backend based on the declared file size.

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. Upload a file

Uploading is two steps: first get a presigned target from the SDK, then POST the file bytes directly to that target.

Both steps require a positive balance. Creating the presigned URL and uploading the file both draw on the balance attached to your API key; an insufficient balance causes them to fail.

Step 1: Get a presigned URL

Size limit: 100 MiB. The size field must be ≤ 104,857,600 bytes. Declaring a larger value causes the presign call to fail.

Call the presign endpoint with the target folder, MIME type, file name, and size in bytes. With a personal-scope API key you can also pass an optional org_username to upload into an organization's storage; it has no effect with an organization-scope key. The response gives you an endpoint (the S3-style POST URL), a download_url (the file's permanent URL once uploaded, so save this), and fields (a JSON string of form fields to include in the upload POST).

curl -X POST "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
  }'

The response envelope looks like:

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

Save data.endpoint, data.download_url, and data.fields from the response; you need all three for step 2.

Step 2: Upload the file to the presigned target

This step is plain HTTP, not an SDK call. The upload method depends on the declared file size:

Declared `size`	`endpoint` shape	`fields` content	Method
≤ 5 MiB (5,242,880 bytes)	Bucket root URL	Full S3 form policy (`key`, `policy`, `x-amz-*`, `Content-Type`, …)	`POST` multipart/form-data — spread all `fields` entries as form fields, then add the file as field `file`
> 5 MiB, ≤ 100 MiB	Pre-signed object URL with `X-Amz-*` query params	`{"Content-Type": "<mime>"}` only	`PUT` with raw binary body; set `Content-Type` header from `fields`

Detect the tier by inspecting endpoint: if it contains X-Amz-Algorithm it is the PUT tier; otherwise it is the form-POST tier.

ENDPOINT="<data.endpoint from step 1>"
FIELDS_JSON='<the data.fields value from the presign response>'
 
if echo "$ENDPOINT" | grep -q "X-Amz-Algorithm"; then
  # PUT tier (> 5 MiB): send raw binary, Content-Type from fields
  CONTENT_TYPE=$(echo "$FIELDS_JSON" | jq -r '.["Content-Type"]')
  curl -X PUT "$ENDPOINT" \
    -H "Content-Type: $CONTENT_TYPE" \
    --data-binary "@/path/to/photo.png"
else
  # Form-POST tier (≤ 5 MiB): spread fields into -F flags, add file last
  FORM_ARGS=()
  while IFS='=' read -r k v; do FORM_ARGS+=(-F "$k=$v"); done \
    < <(echo "$FIELDS_JSON" | jq -r 'to_entries[] | "\(.key)=\(.value)"')
  curl -X POST "$ENDPOINT" "${FORM_ARGS[@]}" -F "file=@/path/to/photo.png"
fi

2. List your files

The folder listing endpoint returns the files in a given folder. Use it to browse uploads, paginate through large collections, or confirm that a specific file appeared after upload.

Each file object contains: id, download_url, key, mime, size.

Pagination uses page (1-based) and pageSize / page_size. An optional type filter accepts image, audio, video, application, or text.

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

Add &type=image to filter by MIME category.

3. Check storage statistics

The statistics endpoint returns aggregate totals across your uploaded files.

The statistics model exposes total_files (the number of files you've uploaded) and total_size (their aggregate size in bytes). Both reflect files uploaded through the presigned-URL flow.

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

4. Delete a file

Pass the file's download_url (returned by the presign call in section 1, or from a folder listing in section 2) to the delete endpoint. The file is removed from object storage.

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://your-download-url-here"}'

Where to next

SDKs: install an SDK and construct a client.
Working with Tasks: use a file's download_url as model input to start an inference task.
Working with Models: discover available models and quote inference cost.