Service Tiers

AvalAI offers different service tiers to give you flexibility in balancing cost and performance for your API requests. This guide explains the available service tiers, their characteristics, and how to use them effectively.

For a broader playbook that combines service tiers with model selection, token budgets, prompt caching, and async jobs, see Cost Optimization.

Overview

Service tiers allow you to choose between standard processing at default prices or reduced costs with higher latency. By default, all requests use the default tier, which provides the best balance of speed and reliability.

default

Recommended

• LatencyLow
• PricingStandard rates
• Credit packages✅ Covered
• Best forProduction & interactive

flex

50% cheaper

• LatencyHigh (up to 15 min)
• Pricing50% reduced
• Credit packages❌ Not covered
• Best forBatch & cost optimization

Service Tier	Description	Latency	Pricing	Credit Package Coverage
default	Standard tier for production and interactive requests	Low	Standard rates	✅ Yes
flex	Cost-optimized tier with higher latency	High (up to 15 min)	50% reduced	❌ No

OpenAI compatibility note

OpenAI's public API docs also describe service_tier: "auto" and service_tier: "priority" modes. AvalAI currently documents default and flex as the generally available service-tier values. If you are porting OpenAI examples that use "priority" or project-level priority settings, use "default" on AvalAI unless your account has explicit priority-tier enablement. For retry fallback from flex, removing service_tier or setting "default" routes the request through AvalAI's standard processing path.

Porting OpenAI service_tier examples to AvalAI

OpenAI's Responses and Chat Completions references return the actual service_tier that served a request, which can differ from the requested value when a project-level setting, capacity fallback, or priority ramp limit applies. Treat AvalAI's returned service_tier the same way: log it with avalai-request-id, endpoint, model, latency, token usage, and final cost so support and billing reviews can explain whether a request used default or flex.

When adapting OpenAI service-tier examples:

• Replace OPENAI_API_KEY with AVALAI_API_KEY and https://api.openai.com/v1 with https://api.avalai.ir/v1.
• Keep service_tier: "flex" only for supported OpenAI-family models and workloads that can tolerate longer waits or resource-unavailable retries.
• Do not copy service_tier: "priority" into general AvalAI examples unless priority processing is explicitly enabled for the account.
• Increase SDK timeouts for flex jobs, and retry idempotent work with exponential backoff or a controlled fallback to default processing.

Default (Standard) Tier

The default service tier is the default for all API requests. It provides:

• Standard processing: Requests are processed on AvalAI's default production path
• Lower latency: Faster response times compared to flex tier
• Full model support: All models are available
• Credit package coverage: Costs are covered by your credit packages if applicable
• Recommended for: Production applications, time-sensitive requests, and interactive use cases

Using Default (Standard) Tier

You don't need to specify anything to use the default tier—it's the default. However, you can explicitly set it:

Bash

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

Python

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Hello!"}],
    service_tier="default",  # Optional, this is the default
)
print(response.choices[0].message.content)

JavaScript

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "gpt-5.4",
  messages: [{ role: "user", content: "Hello!" }],
  service_tier: "default"  // Optional, this is the default
});
console.log(response.choices[0].message.content);

Go

package main

import (
	"context"
	"fmt"
	"os"

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

func main() {
	config := openai.DefaultConfig(os.Getenv("AVALAI_API_KEY"))
	config.BaseURL = "https://api.avalai.ir/v1"
	client := openai.NewClientWithConfig(config)

	resp, err := client.CreateChatCompletion(
		context.Background(),
		openai.ChatCompletionRequest{
			Model: "gpt-5.4",
			Messages: []openai.ChatCompletionMessage{
				{Role: "user", Content: "Hello!"},
			},
			// service_tier defaults to "default"
		},
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}
	fmt.Println(resp.Choices[0].Message.Content)
}

PHP

<?php
$apiKey = getenv('AVALAI_API_KEY');
$apiUrl = 'https://api.avalai.ir/v1/chat/completions';

$data = [
    'model' => 'gpt-5.4',
    'messages' => [
        ['role' => 'user', 'content' => 'Hello!']
    ],
    'service_tier' => 'default'  // Optional, this is the default
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo $result['choices'][0]['message']['content'];
?>

Responses API equivalent

For new integrations, keep the same service_tier value and move the request to /v1/responses. messages becomes input, and final text is read from response.output_text.

Bash

curl https://api.avalai.ir/v1/responses \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "Hello!",
    "service_tier": "default"
  }'

Python

import os
from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5.4",
    input="Hello!",
    service_tier="default",
)
print(response.output_text)

JavaScript

import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "gpt-5.4",
  input: "Hello!",
  service_tier: "default"
});
console.log(response.output_text);

Flex Tier

The flex service tier offers 50% reduced costs for select OpenAI models, in exchange for higher latency and potential request delays.

⚠️ Important Considerations

The flex service tier has significantly higher latency compared to the default tier:

• Processing time: Requests may take much longer to complete
• Server timeout: Requests can take up to 900 seconds (15 minutes) to complete
• Potential failures: Requests may time out or fail during processing
• No credit package coverage: Flex tier costs are not covered by credit packages

Recommended for: Batch processing, non-time-sensitive tasks, cost optimization for high-volume usage

Supported Models

The flex tier is only available for select OpenAI models. Attempting to use flex tier with unsupported models will result in an error.

Model	Model Aliases
gpt-5.5	-
gpt-5.4-pro	-
gpt-5.4	-
gpt-5.4-mini	-
gpt-5.4-nano	-
gpt-5.2-chat	-
gpt-5.2	gpt-5.2-2025-12-11
gpt-5.1	gpt-5.1-2025-11-13
gpt-5	gpt-5-2025-08-07
gpt-5-mini	gpt-5-mini-2025-08-07
gpt-5-nano	gpt-5-nano-2025-08-07
o3	-
o4-mini	-

Flex Tier Pricing

Prices are per 1 million tokens and represent 50% savings compared to default tier pricing.

Model	Input	Cached Input	Output
gpt-5.5	$2.50	$0.25	$15.00
gpt-5.4-pro	$15.00	N/A	$90.00
gpt-5.4	$1.25	$0.13	$7.50
gpt-5.4-mini	$0.375	$0.0375	$2.25
gpt-5.4-nano	$0.10	$0.01	$0.625
gpt-5.2-chat	$0.875	$0.0875	$7.00
gpt-5.2	$0.875	$0.0875	$7.00
gpt-5.1	$0.625	$0.0625	$5.00
gpt-5	$0.625	$0.0625	$5.00
gpt-5-mini	$0.125	$0.0125	$1.00
gpt-5-nano	$0.025	$0.0025	$0.20
o3	$1.00	$0.25	$4.00
o4-mini	$0.55	$0.138	$2.20

For complete pricing information, see the Pricing page.

Using Flex Tier

To use the flex tier, include "service_tier": "flex" in your API request:

Bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [{"role": "user", "content": "Summarize this document..."}],
    "service_tier": "flex"
  }'

Python

import os
from openai import OpenAI

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

# Use flex tier for cost savings on non-time-sensitive tasks
response = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": "Summarize this document..."}],
    service_tier="flex",
)
print(response.choices[0].message.content)
print(f"Service tier used: {response.service_tier}")

JavaScript

import OpenAI from "openai";

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

// Use flex tier for cost savings on non-time-sensitive tasks
const response = await client.chat.completions.create({
  model: "gpt-5-mini",
  messages: [{ role: "user", content: "Summarize this document..." }],
  service_tier: "flex"
});
console.log(response.choices[0].message.content);
console.log(`Service tier used: ${response.service_tier}`);

Go

package main

import (
	"context"
	"fmt"
	"os"

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

func main() {
	config := openai.DefaultConfig(os.Getenv("AVALAI_API_KEY"))
	config.BaseURL = "https://api.avalai.ir/v1"
	client := openai.NewClientWithConfig(config)

	// Use flex tier for cost savings on non-time-sensitive tasks
	resp, err := client.CreateChatCompletion(
		context.Background(),
		openai.ChatCompletionRequest{
			Model: "gpt-5-mini",
			Messages: []openai.ChatCompletionMessage{
				{Role: "user", Content: "Summarize this document..."},
			},
			// Set service_tier to "flex" for reduced pricing
		},
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}
	fmt.Println(resp.Choices[0].Message.Content)
}

PHP

<?php
$apiKey = getenv('AVALAI_API_KEY');
$apiUrl = 'https://api.avalai.ir/v1/chat/completions';

// Use flex tier for cost savings on non-time-sensitive tasks
$data = [
    'model' => 'gpt-5-mini',
    'messages' => [
        ['role' => 'user', 'content' => 'Summarize this document...']
    ],
    'service_tier' => 'flex'
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo $result['choices'][0]['message']['content'] . "\n";
echo "Service tier used: " . $result['service_tier'] . "\n";
?>

Responses API equivalent

Bash

curl https://api.avalai.ir/v1/responses \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "input": "Summarize this document...",
    "service_tier": "flex"
  }'

Python

import os
from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5-mini",
    input="Summarize this document...",
    service_tier="flex",
)
print(response.output_text)
print(f"Service tier used: {response.service_tier}")

JavaScript

import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "gpt-5-mini",
  input: "Summarize this document...",
  service_tier: "flex"
});
console.log(response.output_text);
console.log(`Service tier used: ${response.service_tier}`);

Response Format

All API responses include a service_tier field indicating which tier was used:

{
  "id": "chatcmpl-123",
  "created": 1765789075,
  "model": "gpt-5-mini-2025-08-07",
  "object": "chat.completion",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "Here is the summary...",
        "role": "assistant"
      }
    }
  ],
  "usage": {
    "completion_tokens": 150,
    "prompt_tokens": 50,
    "total_tokens": 200
  },
  "service_tier": "flex",
  "estimated_cost": {
    "unit": "0.0001875000",
    "irt": 24.63,
    "exchange_rate": 131350
  }
}

Error Handling

Unsupported Model Error

If you attempt to use the flex tier with an unsupported model, you will receive an error:

curl -i https://api.avalai.ir/v1/chat/completions \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "hi"}],
    "service_tier": "flex"
  }'

Error Response:

{
  "error": {
    "message": "Model 'claude-sonnet-4-6' does not support service_tier='flex'. Flex tier is only available for supported OpenAI models such as gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5, gpt-5-mini, gpt-5-nano, o3, and o4-mini. See https://docs.avalai.ir/en/service-tiers for more information.",

    "type": "invalid_request",
    "param": null,
    "code": "invalid_request",
    "request_id": "019b214f-4f5d-7321-8a3a-59f89d473c7c"
  }
}

Implementing Retry Logic

For production applications using flex tier, we recommend implementing retry logic with fallback to default tier:

Python

import os
from openai import OpenAI
import time

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


def make_request_with_fallback(messages, model="gpt-5-mini", max_retries=3):
    """
    Attempt flex tier first, fall back to default if it fails.
    """
    # First, try with flex tier for cost savings
    try:
        response = client.chat.completions.create(
            model=model,
            messages=messages,
            service_tier="flex",
            timeout=900,  # 15 minute timeout for flex
        )
        return response, "flex"
    except Exception as e:
        print(f"Flex tier failed: {e}. Falling back to default tier...")

    # Fall back to default tier
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=model, messages=messages, service_tier="default"
            )
            return response, "default"
        except Exception as e:
            if attempt < max_retries - 1:
                time.sleep(2**attempt)  # Exponential backoff
            else:
                raise e


# Usage
messages = [{"role": "user", "content": "Hello!"}]
response, tier_used = make_request_with_fallback(messages)
print(f"Response received using {tier_used} tier")

JavaScript

import OpenAI from "openai";

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

async function makeRequestWithFallback(messages, model = "gpt-5-mini", maxRetries = 3) {
  // First, try with flex tier for cost savings
  try {
    const response = await client.chat.completions.create({
      model: model,
      messages: messages,
      service_tier: "flex"
    }, { timeout: 900000 }); // 15 minute timeout for flex
    return { response, tierUsed: "flex" };
  } catch (error) {
    console.log(`Flex tier failed: ${error.message}. Falling back to default tier...`);
  }

  // Fall back to default tier with retry logic
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await client.chat.completions.create({
        model: model,
        messages: messages,
        service_tier: "default"
      });
      return { response, tierUsed: "default" };
    } catch (error) {
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
      } else {
        throw error;
      }
    }
  }
}

// Usage
const messages = [{ role: "user", content: "Hello!" }];
const { response, tierUsed } = await makeRequestWithFallback(messages);
console.log(`Response received using ${tierUsed} tier`);

Responses API fallback version

Python

def make_response_with_fallback(prompt, model="gpt-5-mini", max_retries=3):
    try:
        response = client.responses.create(
            model=model,
            input=prompt,
            service_tier="flex",
            timeout=900,
        )
        return response, "flex"
    except Exception as error:
        print(f"Flex tier failed: {error}. Falling back to default tier...")

    for attempt in range(max_retries):
        try:
            response = client.responses.create(
                model=model,
                input=prompt,
                service_tier="default",
            )
            return response, "default"
        except Exception:
            if attempt < max_retries - 1:
                time.sleep(2**attempt)
            else:
                raise


response, tier_used = make_response_with_fallback("Hello!")
print(response.output_text)
print(f"Response received using {tier_used} tier")

JavaScript

async function makeResponseWithFallback(prompt, model = "gpt-5-mini", maxRetries = 3) {
  try {
    const response = await client.responses.create({
      model,
      input: prompt,
      service_tier: "flex"
    }, { timeout: 900000 });
    return { response, tierUsed: "flex" };
  } catch (error) {
    console.log(`Flex tier failed: ${error.message}. Falling back to default tier...`);
  }

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await client.responses.create({
        model,
        input: prompt,
        service_tier: "default"
      });
      return { response, tierUsed: "default" };
    } catch (error) {
      if (attempt < maxRetries - 1) {
        await new Promise((resolve) => setTimeout(resolve, Math.pow(2, attempt) * 1000));
      } else {
        throw error;
      }
    }
  }
}

const { response, tierUsed } = await makeResponseWithFallback("Hello!");
console.log(response.output_text);
console.log(`Response received using ${tierUsed} tier`);

Best Practices

When to Use default (Standard) Tier

• Interactive applications: Chatbots, real-time assistants, user-facing interfaces
• Time-sensitive tasks: When quick responses are required
• Production workflows: Where reliability is critical
• Credit package optimization: When you want costs covered by credit packages
• OpenAI Priority migrations: Use this tier when an upstream OpenAI example sets service_tier: "priority" and AvalAI priority-tier access has not been enabled for your account

When to Use Flex Tier

• Batch processing: Processing large amounts of data where time is not critical
• Background tasks: Scheduled jobs, data analysis, content generation
• Cost optimization: When you need to reduce costs and can tolerate delays
• Non-production workloads: Testing, development, experimentation

Hybrid Approach

Consider using a hybrid approach for optimal cost-performance balance:

1. Use default tier for user-facing, time-sensitive requests
2. Use flex tier for background tasks, batch processing, and cost-sensitive operations
3. Implement fallback logic to switch from flex to default when flex fails or times out

About Priority Processing

OpenAI's Priority processing is designed for high-value, user-facing traffic that needs lower and more consistent latency than standard processing. It is not a replacement for offline data processing, evals, or erratic batch workloads. In AvalAI docs and examples, do not send service_tier: "priority" unless your account and route explicitly support it; use default for latency-sensitive production calls and flex only for cost-sensitive work that can tolerate slower or unavailable capacity.

Credit Packages and Service Tiers

Important

Credit packages only cover default tier usage. When using service_tier: "flex", costs are deducted from your default account balance, not from credit package allocations.

For more information about credit packages, see Credit Packages.

API Reference

The service_tier parameter is supported in the following API endpoints:

• Chat Completions API
• Responses API

Related Resources

• Pricing - Complete pricing information including flex tier rates
• Credit Packages - Learn about credit packages and their limitations
• Production Best Practices - Plan service-tier observability and fallback behavior
• Chat Completions API - API reference for chat completions
• Responses API - API reference for the Responses API
• Error Handling - Best practices for handling API errors