AvalAI API Reference

Welcome to the AvalAI API reference documentation. AvalAI provides a unified API that's compatible with OpenAI's API structure, allowing you to access models from multiple providers through a single, consistent interface.

Base URL

All API requests should be made to the following base URL:

https://api.avalai.ir/v1

Authentication

All API endpoints require authentication. You must include your API key in the Authorization header of each request. See the Authentication guide for more details.

Start Here: Choose the Right Surface

OpenAI's API overview recommends choosing the API surface before coding. For AvalAI, start with this routing checklist:

Need	AvalAI route	Notes
New text, reasoning, multimodal, or tool-using app	/v1/responses	Prefer this when the selected model route supports Responses, especially for state, tools, and richer output objects.
Existing chat integration or broad provider compatibility	/v1/chat/completions	Keep this for mature chat apps and providers that expose the Chat Completions schema.
Typed classification, yes/no judgments, or rubric scoring	/v1/decisions	Use the OpenAI Decisions schema with a supported decision model. This release introduces the jev-latest and jev-preview aliases.
Native Jev questions over shared state	/v1/systemone	Use TYPESAFE AI's named questions and native choice, score, and noul primitives.
Request-based speech or audio files	/v1/audio/*	Use for transcription, translation, and text-to-speech jobs with bounded files or generated speech.
Live voice or low-latency sessions	Realtime architecture guide	Treat OpenAI Realtime docs as architecture guidance until a matching AvalAI route is enabled for your account.
Usage, cost, and reseller reporting	user/v1	AvalAI-specific endpoints for transactions, usage summaries, and billing reconciliation.
Organization administration	AvalAI dashboard or support	Do not assume OpenAI Administration endpoints map directly to AvalAI account management.

API Endpoints

Responses

The Responses API is the recommended starting point for new OpenAI-family text, reasoning, multimodal, and tool-ready workflows when the selected model route supports it.

Learn more about Responses →

Chat Completions

The Chat Completions API remains supported for existing chat integrations and provider routes that expose the chat schema.

Learn more about Chat Completions →

Decisions

The Decisions API returns typed judgments for software workflows. Supply shared input and a question array with predicates, choices, or ordered scoring levels. It uses choices for Choice questions and has a different response structure from Chat Completions.

Learn more about Decisions →

System One

The native System One API evaluates named questions against shared state. Jev returns choices, fractional rubric scores, and yes/no probabilities. Combine these results in code and use evaluated thresholds to route uncertain answers for review.

Learn more about System One → · Decision-model guide and cookbooks →

Images

The Images API enables you to generate and edit images using AI models like DALL·E.

Learn more about Images →

Embeddings

The Embeddings API allows you to convert text into vector representations for use in search, clustering, and other machine learning tasks.

Learn more about Embeddings →

Audio

The Audio API provides transcription, translation, and generation capabilities for audio content.

Learn more about Audio →

Moderation

The Moderation API helps you identify potentially harmful content in text.

Learn more about Moderation →

User API

The User API provides precise cost tracking, transaction history, and usage analytics for your API calls. Perfect for resellers, enterprises, and production applications requiring accurate billing.

Key Features:

• 100% accurate cost tracking using avalai-request-id from response headers
• Transaction history with filtering capabilities
• Usage analytics and summaries
• Available within 30 seconds of API call

Learn more about User API →

Request and Response Formats

All API endpoints accept and return JSON data. Make sure to include the Content-Type: application/json header in your requests.

Example Request

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
 "model": "gpt-5.6-luna",
 "messages": [{"role": "user", "content": "Hello!"}]
}'

Responses API version

Use this version when the selected model supports /v1/responses. messages moves to input, and the final text is read from response.output_text.

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '
  {
    "model": "gpt-5.6-luna",
    "input": "Hello!",
    "instructions": "You are a helpful assistant."
  }'

• messages → input
• system message → instructions or a developer item
• choices[0].message.content → response.output_text
• for tools and multimodal output, inspect response.output by item type.

Example Response

{
  "id": "chatcmpl-123abc",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "gpt-5.6-luna",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hello! How can I assist you today?"
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  }
}

Error Handling

The AvalAI API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

• 2xx: Success
• 4xx: Client error (e.g., invalid request, authentication error)
• 5xx: Server error

For more information on handling errors, see the Error Handling guide.

Rate Limits

API requests are subject to rate limiting. When you exceed your rate limits, you'll receive a 429 Too Many Requests response. For more information, see the Rate Limits guide.

Debugging and Request IDs

OpenAI's overview emphasizes request IDs, response headers, and rate-limit headers for production debugging. Apply the same pattern with AvalAI:

• Send a unique X-Client-Request-Id on each retryable API attempt when the route accepts it.
• Log the returned avalai-request-id, endpoint, model, HTTP status, retry count, rate-limit headers, and your hashed safety_identifier when present.
• Use avalai-request-id to reconcile costs through the User API and to give support a precise trace.
• Keep raw prompts and files out of logs unless your retention policy explicitly allows them.

SDKs and Client Libraries

AvalAI is compatible with OpenAI's client libraries. You can use these libraries by specifying the AvalAI base URL:

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",  # AvalAI API endpoint
)

JavaScript/TypeScript

import { OpenAI } from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

Go

package main

import (
	"os"

	openai "github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("AVALAI_API_KEY")),
		option.WithBaseURL("https://api.avalai.ir/v1"),
	)
	_ = client
}

API Versioning

The AvalAI API is versioned to ensure backward compatibility as it evolves. The current version is v1.

Treat compatible API changes as normal: new endpoints, optional parameters, response fields, and streaming event types may appear without breaking existing integrations. Parse only the fields your application needs, ignore unknown response properties, and avoid brittle assumptions about JSON field order or opaque ID formats.

Model behavior can still change between aliases and snapshots even when the API schema is stable. For production workflows, pin model IDs where stability matters, run evals before changing model aliases, and keep rollback notes for prompts, tools, and response parsing.

Next Steps

Explore the detailed documentation for each API endpoint:

• Chat Completions
• Responses
• Images
• Embeddings
• Audio
• Moderation
• User API - Cost tracking and usage analytics
• Response Headers - Understanding API response headers