Ask AI

Chat Completions API

The Chat Completions API is the core of the AvalAI platform, allowing you to generate conversational responses from various AI models, including OpenAI's GPT-6.1 Sol and GPT-6 family (Astra, Sol, and Luna), the GPT-5.6 family (GPT-5.6 Sol, Terra, and Luna), Anthropic Claude Haiku 5.5, Claude Sonnet 5.5, Claude Opus 5.5, Claude Fable 5.1, and Claude Opus 5, xAI Grok 4.7, Grok 4.6, Grok 4.5, and Grok 4.3, Z.AI GLM-5.3-Flash and GLM-5.3, Moonshot Kimi K3, Google Gemini 4 Argon, Gemini 3.8 Flash, Gemini 3.7 Flash, Gemini 3.6 Flash, Gemini 3.5 Flash-Lite, Gemma 4, Alibaba Qwen3.8-Max, Qwen3.8-Flash, Qwen3.8-27B, and Qwen3.7-Plus, DeepSeek V4.1 Flash through deepseek-v4.1-flash and deepseek-flash, Cloudflare Nemotron-3-120B, Fireworks.ai Muse Glimmer 30B, Nemotron 3.5 Lightning and Nemotron-3-Ultra, and MiniMax M3 models.

Gemini 4 Argon: Use gemini-4-argon for Google's new flagship in long-horizon reasoning, software engineering, knowledge work, and multimodal analysis. The catalog lists separate input and output maxima of 1,048,576 tokens each, not additive guaranteed request capacity. Argon supports /v1/chat/completions, native /v1beta/models, /v1/messages, and /v1/responses. USD input/cached-input/output rates per million tokens are $2.00/$0.10/$10.00 through November 30, 2026 inclusive, then $4.00/$0.20/$20.00 from December 1. Start without unconfirmed effort or thinking-budget overrides. See the Google provider guide, reasoning guidance, and four-format examples and complete illustrative responses.

Claude Haiku 5.5: Use claude-haiku-5-5 for high-volume summaries, classification, quick queries, live support, and coding subagents. It supports v1/chat/completions, v1/messages, and v1/responses, with adjustable effort. Start without optional controls and verify native output_config.effort or compatibility mappings separately; do not inherit another model's defaults or thinking budgets. USD input/cached-input/cache-creation/output rates per million tokens are $0.10/$0.01/$0.20/$0.50 through 100K request input tokens and $0.50/$0.05/$1.00/$2.50 above 100K. This is a pricing threshold, not a context limit. See the Anthropic guide, reasoning guide, and request/response examples.

GPT-6.1 Sol: Use gpt-6.1-sol for coding and professional-document reasoning, with 922,000 maximum input tokens and 128,000 maximum output tokens. Support is full on v1/chat/completions, v1/messages, and v1/responses, from Tier 1. Standard input/cached-input/output rates are $2.00/$0.10/$10.00 per million tokens; input above 272K uses a higher tier. Start without effort overrides; none and minimal are not supported in the local metadata. See the OpenAI guide and release pricing.

Claude Sonnet 5.5: Use claude-sonnet-5-5 for scoped coding and document work, with 1,000,000 maximum input tokens and 128,000 maximum output tokens. Support is full on v1/chat/completions and v1/messages, and partial on v1/responses, from Tier 1. Omit unsupported sampling controls, assistant prefill, and forced tool use. Existing thinking-off workflows must migrate to between_tools; the Claude Platform effort default is high, not the medium default in Claude apps/Claude Code. See the Anthropic guide and migration notes.

Claude Opus 5.5: Use claude-opus-5-5 for long-running coding agents and knowledge work with a 1,000,000-token input window, up to 128,000 output tokens, vision, PDF input, tools, structured output, and prompt caching. Support is full on v1/chat/completions, v1/messages, and v1/responses; access requires Tier 1 or higher. Thinking is always on with default medium effort. Forced tool use is not supported. See the Anthropic provider guide and migration notes.

GPT-6 Sol and GPT-6 Luna: Use gpt-6-sol for cost-conscious coding and professional work, or gpt-6-luna for lower-cost high-volume workflows. Both support reasoning, image understanding, tools, structured output, PDF input, and prompt caching, with 922,000 maximum input tokens and 128,000 maximum output tokens. Support is full on v1/chat/completions, v1/messages, and v1/responses. See the OpenAI provider guide.

Grok 4.7: Use xAI's grok-4.7 for long-running coding agents, verification, and knowledge work. It supports vision, reasoning, tools, structured output, and caching, with separate catalog input and output limits of 500,000 tokens each. Support is full on v1/chat/completions and v1/messages and partial on v1/responses; do not assume full hosted-tool or stateful-workflow parity. Start without reasoning_effort overrides unless confirmed for your route. See the xAI provider guide and release pricing.

GPT-6 Astra: Use gpt-6-astra for demanding computer-use, software-engineering, professional, scientific, mathematical, cybersecurity, and long-context workloads. It supports reasoning controls and has full support on v1/chat/completions, v1/messages, and v1/responses. See the OpenAI models documentation.

Claude Fable 5.1: Use claude-fable-5-1 for advanced coding, root-cause analysis, knowledge work, scientific research, computer use, and long-running agents. It supports a 1M-token input window, up to 128K output tokens, always-on adaptive thinking with configurable effort, structured output, vision, PDF input, prompt caching, and tools. Support is full on v1/chat/completions and v1/messages and partial on v1/responses; access requires Tier 2 or higher. See the Anthropic models documentation.

GLM-5.3-Flash: Use glm-5.3-flash for efficient multimodal coding, visual understanding, tool use, and agent workflows with 320B total and 18B active parameters. It supports 991,000 input tokens and up to 128,000 output tokens. Support is full on v1/chat/completions and v1/messages and partial on v1/responses; see the Z.AI models documentation.

GLM-5.3: Use glm-5.3 for Z.AI's flagship coding, long-horizon agent, and authorized security-analysis workloads. Thinking is mandatory: send thinking.type: "enabled" and choose reasoning_effort: "low", "high", or "max"; requests that disable thinking fail. It supports v1/chat/completions and v1/messages, with partial v1/responses support; see the Z.AI models documentation.

New Fireworks.ai models: Use muse-glimmer-30b for Meta's multimodal, multilingual agentic model with controllable reasoning, or nemotron-3.5-lightning for NVIDIA's efficient 30B-total/3B-active reasoning and coding model. Both have full v1/chat/completions and v1/messages support and partial v1/responses support; see the Fireworks.ai provider documentation.

Claude Opus 5: Use claude-opus-5 for difficult software engineering, root-cause analysis, knowledge work, computer use, scientific analysis, and long-running agents. It supports a 1M-token input window, up to 128K output tokens, adaptive thinking, structured output, vision, PDF input, prompt caching, and tools. Support is full on v1/chat/completions and v1/messages and partial on v1/responses; see the Anthropic models documentation.

Gemini 3.8 Flash: Use gemini-3.8-flash for long-horizon coding, autonomous agents, multi-step reasoning, iterative tool use, and specialized professional work. It supports v1/chat/completions, native Gemini v1beta/, and v1/messages, with partial v1/responses support. Promotional pricing through December 31, 2026 is $0.75 input, $0.075 cached input, and $3.75 output per 1 million tokens. The gemini-flash-latest alias now points to gemini-3.8-flash; see the Google models documentation.

Kimi K3: Use kimi-k3 for Moonshot AI's 1M-context flagship with native vision and always-on reasoning. It supports v1/chat/completions and v1/messages fully and v1/responses partially. The kimi-latest alias now resolves to kimi-k3 and uses the same pricing. K3 currently supports reasoning_effort: "max"; omit fixed sampling fields such as temperature and top_p.
Qwen3.8 models: Use qwen3.8-max for Alibaba's managed multimodal flagship with optional thinking, a 1M-token context window, and up to 128K output. Use qwen3.8-flash for the cost-efficient managed alias of qwen3.8-flash-next with vision input, thinking enabled by default, and a 262K context window, or qwen3.8-27b for the compact dense 27B vision-language model with flexible thinking control. Use qwen3.8-2.4t-a95b for the underlying open-weight 2.4T-total/95B-active model: it is text-only, thinking is mandatory, and reasoning_effort accepts low, medium, or xhigh. All four routes have full v1/chat/completions and v1/messages support and partial v1/responses support; see the Alibaba models documentation.
DeepSeek Flash automatic upgrade: deepseek-flash and deepseek-v4.1-flash now both use DeepSeek-V4.1-Flash-1017. No client-side code changes are necessary and pricing is unchanged: keep the existing ID, endpoint, and request format; the base-model name is not a new AvalAI API ID. V4.1 Flash supports native vision, thinking/non-thinking, tools, and prompt caching. The catalog lists 1,000,000 maximum input and 393,216 maximum output tokens (384K in provider notation). Fixed, around-the-clock USD rates remain $0.15 input, $0.003 cached input, and $0.60 output per million tokens; no scheduling, peak doubling, or further halving applies. This upgrade does not announce new endpoint support or changes to other aliases. See the DeepSeek provider guide and October 18 upgrade announcement. The separate V4-Pro routing notice remains in the September 11 release history.
Grok 4.6: Use grok-4.6 for long-running agents, coding, knowledge work, and interactive visual applications—not image generation. It supports vision, reasoning, tools, structured output, and caching, with catalog maximum input and output limits of 500,000 tokens each. Up to and including 200K input tokens, USD prices per 1 million tokens are $2.00 input, $0.50 cached input, and $6.00 output; above 200K they are $4.00, $1.00, and $12.50 respectively. See the xAI provider guide.
Endpoint compatibility for both models: v1/chat/completions and v1/messages are supported; v1/responses support is partial. Do not assume full Responses built-in tool or stateful workflow parity. Check your exact workflow before migration. See the September 11 announcement.

Endpoint

POST https://api.avalai.ir/v1/chat/completions

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.

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-6-astra",
    reasoning={"effort": "medium"},
    instructions="You are a helpful assistant.",
    input="Write a one-sentence summary of AvalAI.",
)

print(response.output_text)

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.

Request Body

Parameter	Type	Required	Description
`model`	string	Yes	ID of the model to use. See Models for available options.
`messages`	array	Yes	Array of message objects representing the conversation history.
`temperature`	number	No	Sampling temperature between 0 and 2. Higher values like 0.8 make output more random, while lower values like 0.2 make it more focused. Default is 1.
`top_p`	number	No	Alternative to temperature, nucleus sampling. Default is 1.
`n`	integer	No	Number of chat completion choices to generate. Default is 1.
`stream`	boolean	No	If set to true, partial message deltas will be sent. Default is false.
`stream_options`	object	No	Options for streaming responses. Only set this when `stream: true`; support varies by route and SDK.
`modalities`	array	No	Output types to generate. Most chat models return `["text"]`; audio output requires model/route support and the `audio` parameter.
`audio`	object	No	Audio-output configuration when `modalities` includes `"audio"`. For most AvalAI workflows, prefer dedicated Audio or Realtime routes.
`prediction`	object	No	Predicted output content for latency-sensitive rewrites where most completion tokens are already known. Provider/model support varies; see Predicted Outputs.
`stop`	string or array	No	Up to 4 sequences where the API will stop generating further tokens.
`max_completion_tokens`	integer	No	Upper bound for generated tokens, including visible output and hidden reasoning tokens. If reasoning consumes the budget, the model can stop with `finish_reason: "length"` before producing visible text; leave headroom or lower reasoning effort. See Reasoning token budgets.
`max_tokens`	integer	No	Legacy maximum output-token setting. Deprecated in OpenAI's current API shape in favor of `max_completion_tokens` and not compatible with some reasoning models. Where it applies to a reasoning model, the same shared-budget warning applies.
`presence_penalty`	number	No	Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far. Default is 0.
`frequency_penalty`	number	No	Number between -2.0 and 2.0. Positive values penalize new tokens based on their frequency in the text so far. Default is 0.
`logit_bias`	object	No	Modify the likelihood of specified tokens appearing in the completion.
`logprobs`	boolean	No	Whether to return log probabilities for output tokens when supported.
`top_logprobs`	integer	No	Number of most likely tokens to return at each output-token position, from 0 to 20. Requires `logprobs: true` and model/route support.
`metadata`	object	No	Up to 16 key-value pairs for filtering stored completions and dashboard/API queries. Keys can be up to 64 characters and values up to 512 characters.
`safety_identifier`	string	No	Privacy-preserving identifier for abuse monitoring. Use a stable hash or opaque internal ID, maximum 64 characters, and avoid raw PII. See Safety best practices.
`prompt_cache_key`	string	No	Cache-bucketing key for similar repeated prefixes. Keep it opaque and stable per assistant, tenant, policy, or schema; prefer `safety_identifier` for abuse monitoring. See Prompt caching.
`prompt_cache_retention`	string	No	Legacy maximum-retention policy for pre-GPT-5.6 models. It is deprecated for GPT-5.6 and later, where OpenAI uses `prompt_cache_options.ttl`; AvalAI pass-through for the newer controls is route-dependent. Omit unsupported cache controls.
`moderation`	object	No	Inline moderation configuration, for example `{ "model": "omni-moderation-latest" }`, when enabled for the selected route/model. If unavailable, call `/v1/moderations` separately.
`user`	string	No	Legacy end-user field. Prefer `safety_identifier` for abuse monitoring and `prompt_cache_key` for cache bucketing.
`response_format`	object	No	Output format constraint. Use `{"type":"json_schema","json_schema":...}` for Structured Outputs when the model supports schema adherence, or `{"type":"json_object"}` for JSON mode fallback. Prefer `/v1/responses` `text.format` for new structured-output workflows.
`reasoning_effort`	string	No	Reasoning-effort control for supported reasoning models. Supported values and defaults are model-specific; verify with the selected AvalAI route. DeepSeek-V4-Flash-0731 supports `low`, `high`, and `max`; Claude Fable 5.1 and Claude Opus 5 use provider-specific adaptive thinking and `output_config.effort` through `extra_body`. Claude Fable 5.1 keeps thinking enabled.
`verbosity`	string	No	Controls final-answer verbosity for supported models (`low`, `medium`, or `high`) without changing reasoning depth.
`seed`	integer	No	If specified, system will make a best effort to sample deterministically.
`store`	boolean	No	Whether to store the chat completion for later retrieval, distillation, or evals when the selected route/account supports stored chat completions.
`tools`	array	No	A list of tools the model may call.
`tool_choice`	string or object	No	Controls which (if any) tool is called by the model.
`parallel_tool_calls`	boolean	No	Whether to allow parallel function/tool calls. Set `false` for state-mutating tools or flows that require sequential execution.
`web_search_options`	object	No	Chat-compatible web-search options when the selected OpenAI-style model supports built-in web search. For provider-independent retrieval, prefer `/v1/search`.
`service_tier`	string	No	The service tier to use for this request. AvalAI generally supports `"default"` (default) and `"flex"`. Flex offers 50% reduced pricing for select OpenAI models but has higher latency and may time out (up to 900s). OpenAI examples may mention `"priority"`; use `"default"` on AvalAI unless priority processing is explicitly enabled for your account. See Pricing.

Tip

Parameter support differs by model and provider. New reasoning models may ignore or reject older sampling/stop/token fields, and hosted tools are route/account dependent in AvalAI. If you are starting a new OpenAI-style workflow with tools, state, or reasoning, compare this page with Responses before choosing Chat Completions.

For response_format, prefer json_schema over json_object whenever the selected model and route support it. JSON mode only guarantees syntactically valid JSON; it does not guarantee required keys, enum values, or application-specific types, so validate the parsed result in your app. See Structured Outputs for schema design, refusal handling, and migration to Responses text.format.

Claude Opus 5.5 parameter constraints: Do not send disabled thinking, a fixed thinking budget, assistant prefill, or unsupported sampling fields such as temperature and top_p. To configure effort, use Anthropic's adaptive thinking and output_config.effort through extra_body, starting at medium; do not assume another provider's reasoning_effort mapping. Remove tool-choice configurations that force a tool call. Preserve complete assistant thinking and tool blocks in subsequent turns, and do not depend on visible text between tool calls at the default display setting. See Claude Opus 5.5 reasoning.

Message Object

Each message in the messages array should have the following structure:

Parameter	Type	Required	Description
`role`	string	Yes	The role of the message author. Common roles are `developer`, `system`, `user`, `assistant`, and `tool`. Use `developer` or `system` for durable instructions depending on model support.
`content`	string or array	Yes	The content of the message. Can be a string or an array of content parts when using multimodal inputs.
`name`	string	No	The name of the author of this message. Required for `tool` roles.
`tool_call_id`	string	No	Required for `tool` role messages. The ID of the tool call that this message is responding to.

Examples

Gemini 4 Argon quick start

Use gemini-4-argon in a standard Chat Completions request. This baseline avoids optional controls whose Argon-specific values are not established by the release:

BashPythonJavaScript

bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gemini-4-argon",
    "messages": [
      {"role": "user", "content": "Review a database migration plan: identify failure modes and give a concise verification checklist."}
    ]
  }'

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="gemini-4-argon",
    messages=[
        {
            "role": "user",
            "content": "Review a database migration plan: identify failure modes and give a concise verification checklist.",
        }
    ],
)
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: "gemini-4-argon",
  messages: [
    { role: "user", content: "Review a database migration plan: identify failure modes and give a concise verification checklist." },
  ],
});
console.log(response.choices[0].message.content);

If switching to Responses, use input and read response.output_text. Native Gemini and Messages use their own schemas; do not send this Chat Completions body unchanged to those routes. The release examples cover all four formats.

GPT-6.1 Sol and Claude Sonnet 5.5 quick start

Both models accept the minimal Chat Completions shape below. It deliberately omits sampling and effort overrides. For Sonnet-specific adaptive thinking and output_config.effort, use the native Messages example and verify any compatibility-layer mapping separately. Preserve full assistant/tool turns and allow output headroom for reasoning.

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"], base_url="https://api.avalai.ir/v1"
)
for model in ("gpt-6.1-sol", "claude-sonnet-5-5"):
    response = client.chat.completions.create(
        model=model,
        messages=[
            {
                "role": "user",
                "content": "Review this release plan and give a concise verification checklist: deploy an API behind a feature flag.",
            }
        ],
    )
    print(model, response.choices[0].message.content)

Claude Opus 5.5 quick start

Start without optional reasoning or sampling overrides. Adaptive thinking remains enabled; allow enough completion tokens for reasoning as well as the final answer.

bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "claude-opus-5-5",
    "max_completion_tokens": 8192,
    "messages": [
      {"role": "user", "content": "Review a staged database migration and list verification and rollback checks."}
    ]
  }'

USD prices per 1 million tokens are $4.00 input, $0.20 cached input, $8.00 cache creation, and $20.00 output. For native Messages and Responses examples, see the announcement.

GPT-6 Sol, GPT-6 Luna, and Grok 4.7 quick start

Use the same minimal Chat Completions request for all three models. To compare the other options, change only model to gpt-6-luna or grok-4.7. They understand image inputs but are not direct image-generation models. For Sol and Luna, reasoning controls use reasoning_effort here and reasoning.effort on Responses; validate supported levels rather than copying another model's defaults.

bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      {"role": "user", "content": "Suggest a concise verification checklist for deploying an API behind a feature flag."}
    ]
  }'

Check pricing before choosing output budgets: the higher input, cache, and output rates apply above 272K input tokens for Sol and Luna and above 200K for Grok 4.7. These are input-length pricing tiers, not maximum context sizes.

DeepSeek V4.1 Flash and Grok 4.6 quick start

Start with a minimal request. To compare Grok 4.6, change only the model to grok-4.6. Do not copy effort values from older models without confirming support.

bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [
      {"role": "user", "content": "Review this release plan and propose a concise test checklist: deploy a new API behind a feature flag."}
    ]
  }'

Basic Chat Completion

bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
  "model": "gpt-6-astra",
  "messages": [
  {
    "role": "system",
    "content": "You are a helpful assistant."
  },
  {
    "role": "user",
    "content": "Hello!"
  }
  ]
}'

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
)

response = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
)

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.6-luna",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" },
  ],
});

console.log(response.choices[0].message.content);

go

package main

import (
	"context"
	"fmt"
	openai "github.com/openai/openai-go"
)

func main() {
	client := openai.NewClient("AVALAI_API_KEY")
	client.BaseURL = "https://api.avalai.ir/v1"

	resp, err := client.CreateChatCompletion(
		context.Background(),
		openai.ChatCompletionRequest{
			Model: "gpt-5.6-sol",
			Messages: []openai.ChatCompletionMessage{
				{
					Role:    openai.ChatMessageRoleSystem,
					Content: "You are a helpful assistant.",
				},
				{
					Role:    openai.ChatMessageRoleUser,
					Content: "Hello!",
				},
			},
		},
	)

	if err != nil {
		fmt.Printf("ChatCompletion error: %v\n", err)
		return
	}

	fmt.Println(resp.Choices[0].Message.Content) // Corrected access to response content
}

php

<?php
// PHP Example for Chat Completion via AvalAI

$apiKey = getenv('AVALAI_API_KEY'); // Or replace with your key directly
$apiUrl = 'https://api.avalai.ir/v1/chat/completions';

$data = [
'model' => 'gpt-5.6-sol',
'messages' => [
['role' => 'system', 'content' => 'You are a helpful assistant.'],
['role' => 'user', 'content' => 'Hello!']
]
// Add other parameters like temperature, max_tokens etc. if needed
// 'temperature' => 0.7,
// 'max_tokens' => 150
];

$jsonData = json_encode($data);

$ch = curl_init($apiUrl);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $apiKey,
'Content-Length: ' . strlen($jsonData)
]);

$response = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$err = curl_error($ch);

curl_close($ch);

if ($err) {
  echo "cURL Error #:" . $err;
} elseif ($httpcode >= 400) {
  echo "HTTP Error: " . $httpcode . "\n";
  echo $response;
} else {
  $responseData = json_decode($response, true);
  if (isset($responseData['choices'][0]['message']['content'])) {
    echo "Assistant: " . $responseData['choices'][0]['message']['content'] . "\n";
  } else {
    echo "Response received:\n";
    print_r($responseData);
  }
}
?>

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.

PythonJavaScriptBash

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.6-sol",
    instructions="You are a helpful assistant.",
    input="Hello!",
)

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.6-luna",
  instructions: "You are a helpful assistant.",
  input: "Hello!",
});

console.log(response.output_text);

bash

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '
  {
    "model": "gpt-5.6-sol",
    "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.

Response Format

json

{
  "id": "chatcmpl-123abc",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "gpt-5.6-sol",
  "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
  },
  "service_tier": "default"
}

Response Parameters

Parameter	Type	Description
`id`	string	A unique identifier for the chat completion.
`object`	string	The object type, which is always "chat.completion".
`created`	integer	The Unix timestamp (in seconds) of when the chat completion was created.
`model`	string	The model used for the chat completion.
`choices`	array	An array of chat completion choices.
`usage`	object	An object containing token usage information.
`moderation`	object	Inline input/output moderation results when requested and supported.
`service_tier`	string	The service tier used for this request. Public AvalAI values are generally `"default"` or `"flex"`; `"priority"` is account-specific unless explicitly enabled.

Choice Object

Parameter	Type	Description
`message`	object	A message object containing the response content.
`finish_reason`	string	The reason why the model stopped generating tokens. Can be "stop", "length", "tool_calls", "content_filter", or "function_call".
`index`	integer	The index of the choice in the array.

Usage Object

Parameter	Type	Description
`prompt_tokens`	integer	The number of tokens used in the prompt.
`completion_tokens`	integer	The number of tokens used in the completion.
`total_tokens`	integer	The total number of tokens used (prompt + completion).

Streaming

To receive incremental model responses, set stream: true in your request:

javascript

const stream = await client.chat.completions.create({
  model: "gpt-5.6-luna",
  messages: [{ role: "user", content: "Write a long story about a dog." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

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.

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.6-sol",
    instructions="You are a helpful assistant.",
    input="Write a long story about a dog.",
)

print(response.output_text)

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.

Function Calling / Tool Use

You can specify tools that the model can call:

javascript

const response = await client.chat.completions.create({
  model: "gpt-5.6-luna",
  messages: [{ role: "user", content: "What's the weather in San Francisco?" }],
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "Get the current weather in a given location",
        strict: true,
        parameters: {
          type: "object",
          properties: {
            location: {
              type: "string",
              description: "The city and state, e.g. San Francisco, CA",
            },
            unit: {
              type: "string",
              enum: ["celsius", "fahrenheit"],
              description: "The temperature unit",
            },
          },
          required: ["location", "unit"],
          additionalProperties: false,
        },
      },
    },
  ],
});

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.

python

import os
import json
from openai import OpenAI

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


def get_current_weather(location, unit):
    return {
        "location": location,
        "temperature": "18",
        "unit": unit or "celsius",
        "condition": "partly cloudy",
    }


tools = [
    {
        "type": "function",
        "name": "get_current_weather",
        "description": "Get the current weather in a given location.",
        "strict": True,
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string"},
                "unit": {
                    "type": ["string", "null"],
                    "enum": ["celsius", "fahrenheit", None],
                },
            },
            "required": ["location", "unit"],
            "additionalProperties": False,
        },
    }
]

input_items = [
    {
        "role": "user",
        "content": "What's the weather in San Francisco in celsius?",
    }
]

response = client.responses.create(
    model="gpt-5.6-sol",
    input=input_items,
    tools=tools,
)

input_items += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = get_current_weather(args["location"], args.get("unit"))
        input_items.append(
            {
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(result),
            }
        )

final_response = client.responses.create(
    model="gpt-5.6-sol",
    input=input_items,
    tools=tools,
)

print(final_response.output_text)

messages → input
system message → instructions or a developer item
choices[0].message.content → response.output_text
tool_calls → response.output items where type == "function_call"; return results as function_call_output with the same call_id.
preserve prior response.output items when you manage the tool loop manually, especially for reasoning-capable models.

Audio Input and Output

OpenAI's audio models (gpt-audio and gpt-audio-mini) support both audio and text inputs/outputs through the Chat Completions API. These models enable voice-based conversational applications with native audio processing capabilities.

Gemini 3.8 TTS

For new text-to-speech workloads, choose gemini-3.8-flash-tts for creative quality, expressive acting, regional accents, and stable long-form dialogue; choose gemini-3.8-flash-lite-tts for high throughput, low latency, and everyday read-aloud speech. Both accept text input and produce audio output. They are not transcription, audio-input conversation, Live API, or reasoning models.

AvalAI supports these TTS models only through native /v1beta/models methods, /v1/chat/completions, and /v1/audio/speech. Do not send them to /v1/responses, /v1/messages, or legacy /v1/text:synthesize. Use a separate conversational or reasoning model to write the answer before passing final text to TTS.

bash

curl --fail-with-body -sS https://api.avalai.ir/v1/chat/completions \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "messages": [{"role": "user", "content": "Have a wonderful day!"}],
    "modalities": ["audio"],
    "audio": {"voice": "Zephyr", "format": "pcm16"}
  }' \
  --output chat-speech.json

python3 - <<'PYTHON'
import base64
import json
from pathlib import Path

response = json.loads(Path("chat-speech.json").read_text())
data = response["choices"][0]["message"]["audio"]["data"]
Path("speech.pcm").write_bytes(base64.b64decode(data, validate=True))
PYTHON

ffmpeg -f s16le -ar 24000 -ac 1 -i speech.pcm speech.wav

This request reads the supplied transcript; it does not answer questions or accept audio input. Chat returns Base64 at choices[0].message.audio.data, not message.content. The requested pcm16 is headerless signed 16-bit little-endian PCM at 24000 Hz, mono, so save it as raw PCM and convert with explicit input parameters. Do not use a .content fallback or strip DEPRECATED text from Base64. Native unary 3.8 output instead defaults to WAV: follow mimeType before deciding whether a WAV wrapper is needed. For native per-part speechMetadata and migration from gemini-3.1-flash-tts-preview / gemini-2.5-flash-tts / gemini-2.5-pro-tts, see Text to speech.

Audio Parameters

When using audio models, you can specify additional parameters:

Parameter	Type	Required	Description
`modalities`	array	No	Specifies output modalities. Use `["text", "audio"]` for audio output. For image generation models such as `gemini-3-pro-image`, `gemini-3.1-flash-image`, `gemini-3.1-flash-lite-image`, and `gemini-2.5-flash-image`, use `["image", "text"]`. Default is `["text"]`.
`audio`	object	No	Audio output configuration. Required when requesting audio output.

Audio Configuration Object

Parameter	Type	Required	Description
`format`	string	No	Audio output format. Options: `mp3`, `wav`, `pcm16`, `opus`, `aac`, `flac`. Default is `mp3`.
`voice`	string	No	Voice to use for audio output. Options: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`. Default is `alloy`.

Basic Audio Generation

bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-audio",
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing in simple terms."
      }
    ],
    "modalities": ["text", "audio"],
    "audio": {
      "format": "mp3",
      "voice": "nova"
    }
  }'

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-audio",
    messages=[
        {"role": "user", "content": "Explain quantum computing in simple terms."}
    ],
    modalities=["text", "audio"],
    audio={"format": "mp3", "voice": "nova"},
)

# Access the audio data and transcript
audio_data = response.choices[0].message.audio.data  # Base64 encoded audio
transcript = response.choices[0].message.audio.transcript  # Text transcript

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-audio",
    messages: [
        {
            role: "user",
            content: "Explain quantum computing in simple terms.",
        },
    ],
    modalities: ["text", "audio"],
    audio: {
        format: "mp3",
        voice: "nova",
    },
});

// Access the audio data and transcript
const audioData = response.choices[0].message.audio.data;
const transcript = response.choices[0].message.audio.transcript;

go

package main

import (
	"context"
	"fmt"
	"os"

	"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"),
	)

	completion, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
		Model: openai.F("gpt-audio"),
		Messages: openai.F([]openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("Explain quantum computing in simple terms."),
		}),
		Modalities: openai.F([]openai.ChatCompletionModality{
			openai.ChatCompletionModalityText,
			openai.ChatCompletionModalityAudio,
		}),
		Audio: openai.F(openai.ChatCompletionAudioParam{
			Format: openai.F(openai.ChatCompletionAudioFormatMp3),
			Voice:  openai.F(openai.ChatCompletionAudioVoiceNova),
		}),
	})

	if err != nil {
		panic(err)
	}

	fmt.Printf("Audio Data: %s\n", completion.Choices[0].Message.Audio.Data)
	fmt.Printf("Transcript: %s\n", completion.Choices[0].Message.Audio.Transcript)
}

php

<?php

require 'vendor/autoload.php';

use OpenAI\Client;

$client = OpenAI::factory()
    ->withApiKey(getenv('AVALAI_API_KEY'))
    ->withBaseUri('https://api.avalai.ir/v1')
    ->make();

$response = $client->chat()->create([
    'model' => 'gpt-audio',
    'messages' => [
        [
            'role' => 'user',
            'content' => 'Explain quantum computing in simple terms.',
        ],
    ],
    'modalities' => ['text', 'audio'],
    'audio' => [
        'format' => 'mp3',
        'voice' => 'nova',
    ],
]);

$audioData = $response['choices'][0]['message']['audio']['data'];
$transcript = $response['choices'][0]['message']['audio']['transcript'];

echo "Transcript: " . $transcript . "\n";

The audio returns as Base64 at choices[0].message.audio.data. To decode it into a playable MP3 straight from the terminal (requires jq), run a one-time command:

zsh

# macOS (zsh)
curl -sS "https://api.avalai.ir/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-audio",
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing in simple terms."
      }
    ],
    "modalities": ["text", "audio"],
    "audio": {
      "format": "mp3",
      "voice": "nova"
    }
  }' \
  | jq -r '.choices[0].message.audio.data' \
  | base64 -D > output.mp3

afplay output.mp3

bash

# Linux (bash/zsh)
curl -sS "https://api.avalai.ir/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-audio",
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing in simple terms."
      }
    ],
    "modalities": ["text", "audio"],
    "audio": {
      "format": "mp3",
      "voice": "nova"
    }
  }' \
  | jq -r '.choices[0].message.audio.data' \
  | base64 --decode >output.mp3

ffplay -nodisp -autoexit output.mp3

powershell

# Windows (PowerShell)
$response = curl.exe -sS "https://api.avalai.ir/v1/chat/completions" `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer $env:AVALAI_API_KEY" `
  -d '{
    "model": "gpt-audio",
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing in simple terms."
      }
    ],
    "modalities": ["text", "audio"],
    "audio": {
      "format": "mp3",
      "voice": "nova"
    }
  }' | ConvertFrom-Json

[IO.File]::WriteAllBytes(
  (Join-Path $PWD "output.mp3"),
  [Convert]::FromBase64String($response.choices[0].message.audio.data)
)

Start-Process .\output.mp3

These are one-time terminal commands; nothing needs to be added to .zshrc, .bashrc, or the PowerShell profile.

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.

PythonJavaScriptBash

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-audio",
    input="Explain quantum computing in simple terms.",
)

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-audio",
  instructions: "You are a helpful assistant.",
  input: "Explain quantum computing in simple terms.",
});

console.log(response.output_text);

bash

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '
  {
    "model": "gpt-audio",
    "input": "Explain quantum computing in simple terms.",
    "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.

Audio Response Format

When using audio models with the audio modality, the response includes an audio object in the message:

json

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1763042146,
  "model": "gpt-audio-2025-08-28",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "audio": {
          "id": "audio_abc123",
          "data": "SUQzBAAAAA...", // Base64 encoded audio

          "expires_at": 1763045747,
          "transcript": "Quantum computing is a revolutionary technology..."
        }
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 75,
    "total_tokens": 87,
    "completion_tokens_details": {
      "audio_tokens": 58,
      "text_tokens": 17
    },
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "text_tokens": 12
    }
  }
}

Using gpt-audio-1.5 for Premium Audio Quality

For the highest quality voice synthesis and audio understanding, use gpt-audio-1.5:

python

response = client.chat.completions.create(
    model="gpt-audio-1.5",  # Best voice model with 256K context
    messages=[{"role": "user", "content": "What's the weather like today?"}],
    modalities=["text", "audio"],
    audio={"format": "mp3", "voice": "nova"},
)

Responses API version This version uses `gpt-5.5` because `gpt-audio-1.5` may not be enabled for `/v1/responses` in the current AvalAI model data.

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

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.6-sol",
    input="What's the weather like today? Answer in one sentence.",
)

print(response.output_text)

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.

Using gpt-audio-mini for Cost-Effective Processing

For high-volume applications, use gpt-audio-mini which offers the same capabilities at a lower cost:

python

response = client.chat.completions.create(
    model="gpt-audio-mini",  # More cost-effective option
    messages=[{"role": "user", "content": "What's the weather like today?"}],
    modalities=["text", "audio"],
    audio={"format": "mp3", "voice": "alloy"},
)

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.

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-audio-mini",
    input="What's the weather like today? Answer in one sentence.",
)

print(response.output_text)

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.

Legacy Audio Models

For backwards compatibility, the following preview models are still available:

gpt-4o-audio-preview
gpt-4o-mini-audio-preview

Audio input: Use input_audio with a compatible conversational model such as gpt-audio-mini; see the audio-input example. Gemini TTS models accept text only. For dedicated file transcription, use the Audio Transcriptions API.

Error Handling

The API may return various error codes:

Status Code	Description
400	Bad Request - Your request is invalid.
401	Unauthorized - Your API key is wrong.
403	Forbidden - You don't have permission to access this resource.
404	Not Found - The specified resource could not be found.
429	Too Many Requests - You have exceeded your rate limit.
500	Internal Server Error - We had a problem with our server.

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

Models - Learn about available models
Authentication - Learn about authentication methods
Rate Limits - Learn about API rate limits

Chat Completions API ​

Endpoint ​

Request Body ​

Message Object ​

Examples ​

Gemini 4 Argon quick start ​

GPT-6.1 Sol and Claude Sonnet 5.5 quick start ​

Claude Opus 5.5 quick start ​

GPT-6 Sol, GPT-6 Luna, and Grok 4.7 quick start ​

DeepSeek V4.1 Flash and Grok 4.6 quick start ​

Basic Chat Completion ​

Response Format ​

Response Parameters ​

Choice Object ​

Usage Object ​

Streaming ​

Function Calling / Tool Use ​

Audio Input and Output ​

Gemini 3.8 TTS ​

Audio Parameters ​

Audio Configuration Object ​

Basic Audio Generation ​

Audio Response Format ​

Using gpt-audio-1.5 for Premium Audio Quality ​

Using gpt-audio-mini for Cost-Effective Processing ​

Legacy Audio Models ​

Error Handling ​

Related Resources ​

Chat Completions API

Endpoint

Request Body

Message Object

Examples

Gemini 4 Argon quick start

GPT-6.1 Sol and Claude Sonnet 5.5 quick start

Claude Opus 5.5 quick start

GPT-6 Sol, GPT-6 Luna, and Grok 4.7 quick start

DeepSeek V4.1 Flash and Grok 4.6 quick start

Basic Chat Completion

Response Format

Response Parameters

Choice Object

Usage Object

Streaming

Function Calling / Tool Use

Audio Input and Output

Gemini 3.8 TTS

Audio Parameters

Audio Configuration Object

Basic Audio Generation

Audio Response Format

Using gpt-audio-1.5 for Premium Audio Quality

Using gpt-audio-mini for Cost-Effective Processing

Legacy Audio Models

Error Handling

Related Resources