پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

API تکمیل گفتگو (Chat Completions)

API تکمیل گفتگو هسته اصلی پلتفرم AvalAI است که به شما امکان می‌دهد پاسخ‌های محاوره‌ای را از مدل‌های مختلف هوش مصنوعی از جمله Claude Opus 5 از Anthropic، جدیدترین خانواده GPT-5.6 از OpenAI (GPT-5.6 Sol، Terra و Luna)، سری GPT-5.5، Grok 4.5 و Grok 4.3 از XAI، GLM-5.2 از Z.AI، Kimi K3 از Moonshot، Gemini 3.6 Flash، Gemini 3.5 Flash-Lite و Gemma 4 از Google، Qwen3.8-Max و Qwen3.7-Plus از Alibaba، مدل DeepSeek-V4-Flash-0731 از طریق شناسه پایدار deepseek-v4-flash، Nemotron-3-120B از Cloudflare، Nemotron-3-Ultra از Fireworks.ai و مدل‌های M3 از MiniMax تولید کنید.

Claude Opus 5: از claude-opus-5 برای مهندسی نرم‌افزار دشوار، تحلیل علت ریشه‌ای، کار دانشی، استفاده از کامپیوتر، تحلیل علمی و عامل‌های طولانی‌مدت استفاده کنید. این مدل پنجره ورودی ۱M، حداکثر ۱۲۸K توکن خروجی، تفکر تطبیقی، خروجی ساختاریافته، بینایی، ورودی PDF، کش پرامپت و ابزارها را پشتیبانی می‌کند. پشتیبانی در v1/chat/completions و v1/messages کامل و در v1/responses جزئی است؛ مستندات مدل‌های Anthropic را ببینید.

Gemini 3.6 Flash و Gemini 3.5 Flash-Lite: از gemini-3.6-flash برای کدنویسی عاملی، کار دانشی، استفاده از ابزار و تحلیل پیچیده چندوجهی استفاده کنید. gemini-3.5-flash-lite برای پردازش اسناد، استخراج، دسته‌بندی و بارهای کاری زیرعامل پرترافیک با هزینه کمتر مناسب است. هر دو مدل از v1/chat/completions، API بومی Gemini یعنی v1beta/ و v1/messages پشتیبانی می‌کنند و در v1/responses پشتیبانی جزئی دارند؛ مستندات مدل‌های Google را ببینید.

Kimi K3: برای پرچم‌دار Moonshot AI با زمینه ۱M، بینایی بومی و استدلال همیشه‌فعال از kimi-k3 استفاده کنید. این مدل از v1/chat/completions و v1/messages به‌طور کامل و از v1/responses به‌صورت جزئی پشتیبانی می‌کند. alias مدل kimi-latest اکنون به kimi-k3 اشاره می‌کند و همان قیمت را دارد. K3 در حال حاضر از reasoning_effort: "max" پشتیبانی می‌کند؛ فیلدهای sampling ثابت مانند temperature و top_p را ارسال نکنید.
Qwen3.8-Max: برای پرچم‌دار جدید Alibaba با ۲٫۴ تریلیون پارامتر، زمینه ۱M، حداکثر خروجی ۱۲۸K، درک بومی متن/تصویر/ویدئو، کدنویسی بلندمدت، خروجی ساختاریافته، کش پرامپت و ابزارها از qwen3.8-max استفاده کنید. پشتیبانی در v1/chat/completions و v1/messages کامل و در v1/responses جزئی است؛ مستندات مدل‌های Alibaba را ببینید.
ارتقای DeepSeek-V4-Flash: همچنان از deepseek-v4-flash استفاده کنید؛ AvalAI اکنون این شناسه پایدار را بدون نیاز به تغییر کد یا قیمت به DeepSeek-V4-Flash-0731 هدایت می‌کند. نسخه رسمی از مقدارهای low، high و max برای reasoning_effort پشتیبانی می‌کند؛ مستندات مدل‌های DeepSeek را ببینید.

نقطه پایانی (Endpoint)

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

نسخه معادل Responses API

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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 one-sentence summary of AvalAI.",
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

بدنه درخواست (Request Body)

پارامتر	نوع	الزامی	توضیحات
`model`	string	بله	شناسه مدلی که باید استفاده شود. برای گزینه‌های موجود به مدل‌ها مراجعه کنید.
`messages`	array	بله	آرایه‌ای از اشیا پیام که تاریخچه گفتگو را نشان می‌دهد.
`temperature`	number	خیر	دمای نمونه‌برداری بین ۰ و ۲. مقادیر بالاتر مانند ۰.۸ خروجی را تصادفی‌تر می‌کنند، در حالی که مقادیر پایین‌تر مانند ۰.۲ آن را متمرکزتر می‌کنند. پیش‌فرض ۱ است.
`top_p`	number	خیر	جایگزینی برای دما، نمونه‌برداری هسته‌ای (nucleus sampling). پیش‌فرض ۱ است.
`n`	integer	خیر	تعداد انتخاب‌های تکمیل گفتگو برای تولید. پیش‌فرض ۱ است.
`stream`	boolean	خیر	اگر روی true تنظیم شود، دلتاهای پیام جزئی ارسال خواهند شد. پیش‌فرض false است.
`stream_options`	object	خیر	گزینه‌های جریان‌دهی پاسخ. فقط همراه `stream: true` استفاده کنید؛ پشتیبانی به route و SDK وابسته است.
`modalities`	array	خیر	نوع‌های خروجی که می‌خواهید مدل تولید کند. بیشتر مدل‌های chat مقدار `["text"]` برمی‌گردانند؛ خروجی صوتی به پشتیبانی مدل/route و پارامتر `audio` نیاز دارد.
`audio`	object	خیر	پیکربندی خروجی صوتی وقتی `modalities` شامل `"audio"` است. برای بیشتر workflowهای AvalAI، routeهای اختصاصی Audio یا Realtime را ترجیح دهید.
`prediction`	object	خیر	محتوای خروجی پیش‌بینی‌شده برای rewriteهای حساس به latency که بیشتر completion tokenها از قبل مشخص هستند. پشتیبانی به provider/model وابسته است؛ خروجی‌های پیش‌بینی‌شده را ببینید.
`stop`	string or array	خیر	حداکثر ۴ دنباله که API تولید توکن‌های بیشتر را در آنجا متوقف می‌کند.
`max_completion_tokens`	integer	خیر	سقف توکن‌های تولیدی، شامل خروجی قابل مشاهده و توکن‌های reasoning پنهان. اگر reasoning تمام بودجه را مصرف کند، مدل ممکن است پیش از تولید متن قابل مشاهده با `finish_reason: "length"` متوقف شود؛ حاشیه امن بگذارید یا effort را کاهش دهید. بخش بودجه توکن reasoning را ببینید.
`max_tokens`	integer	خیر	تنظیم قدیمی سقف توکن خروجی. در شکل فعلی API OpenAI به نفع `max_completion_tokens` deprecated شده و با برخی مدل‌های reasoning سازگار نیست. هرجا برای مدل reasoning قابل استفاده باشد، همان هشدار بودجه مشترک برقرار است.
`presence_penalty`	number	خیر	عددی بین -۲.۰ و ۲.۰. مقادیر مثبت توکن‌های جدید را بر اساس اینکه آیا تاکنون در متن ظاهر شده‌اند جریمه می‌کنند. پیش‌فرض ۰ است.
`frequency_penalty`	number	خیر	عددی بین -۲.۰ و ۲.۰. مقادیر مثبت توکن‌های جدید را بر اساس فراوانی آن‌ها در متن تاکنون جریمه می‌کنند. پیش‌فرض ۰ است.
`logit_bias`	object	خیر	احتمال ظاهر شدن توکن‌های مشخص شده در تکمیل را تغییر دهید.
`logprobs`	boolean	خیر	در صورت پشتیبانی، log probability توکن‌های خروجی را برمی‌گرداند.
`top_logprobs`	integer	خیر	تعداد محتمل‌ترین توکن‌ها در هر موقعیت توکن خروجی، از ۰ تا ۲۰. به `logprobs: true` و پشتیبانی مدل/route نیاز دارد.
`metadata`	object	خیر	حداکثر ۱۶ جفت کلید/مقدار برای فیلتر کردن completionهای ذخیره‌شده و query در dashboard/API. کلیدها حداکثر ۶۴ و مقدارها حداکثر ۵۱۲ کاراکتر دارند.
`safety_identifier`	string	خیر	شناسه پایدار و حفظ‌کننده حریم خصوصی برای پایش سوءاستفاده. از hash پایدار یا شناسه داخلی opaque با حداکثر 64 کاراکتر استفاده کنید و PII خام نفرستید. بهترین شیوه‌های ایمنی را ببینید.
`prompt_cache_key`	string	خیر	کلید bucket کردن cache برای prefixهای تکراری مشابه. آن را opaque و پایدار برای assistant، tenant، policy یا schema نگه دارید؛ برای پایش سوءاستفاده `safety_identifier` را ترجیح دهید. Prompt caching را ببینید.
`prompt_cache_retention`	string	خیر	سیاست legacy برای حداکثر ماندگاری مدل‌های پیش از GPT-5.6. این فیلد برای GPT-5.6 و خانواده‌های بعدی deprecated است؛ OpenAI در نسل جدید از `prompt_cache_options.ttl` استفاده می‌کند و pass-through کنترل‌های جدید در AvalAI به route وابسته است. کنترل پشتیبانی‌نشده را حذف کنید.
`moderation`	object	خیر	پیکربندی inline moderation، مثلا `{ "model": "omni-moderation-latest" }`، در صورت فعال بودن برای route/model انتخابی. اگر در دسترس نیست، `/v1/moderations` را جداگانه فراخوانی کنید.
`user`	string	خیر	فیلد قدیمی شناسه کاربر نهایی. برای پایش سوءاستفاده از `safety_identifier` و برای bucket کردن cache از `prompt_cache_key` استفاده کنید.
`response_format`	object	خیر	محدودکننده فرمت خروجی. برای Structured Outputs در مدل‌های دارای پایبندی به schema از `{"type":"json_schema","json_schema":...}` استفاده کنید، یا برای fallback حالت JSON از `{"type":"json_object"}`. برای workflowهای جدید structured output، `text.format` در `/v1/responses` را ترجیح دهید.
`reasoning_effort`	string	خیر	کنترل تلاش reasoning برای مدل‌های reasoning پشتیبانی‌شده. مقدارهای مجاز و پیش‌فرض‌ها model-specific هستند؛ با route انتخابی AvalAI بررسی کنید. DeepSeek-V4-Flash-0731 از `low`، `high` و `max` پشتیبانی می‌کند؛ Claude Opus 5 از تفکر تطبیقی اختصاصی ارائه‌دهنده و `output_config.effort` در `extra_body` استفاده می‌کند.
`verbosity`	string	خیر	در مدل‌های پشتیبانی‌شده طول/جزئیات پاسخ نهایی را (`low`، `medium` یا `high`) بدون تغییر عمق reasoning کنترل می‌کند.
`seed`	integer	خیر	اگر مشخص شود، سیستم بهترین تلاش خود را برای نمونه‌برداری قطعی انجام خواهد داد.
`store`	boolean	خیر	آیا chat completion برای بازیابی بعدی، distillation یا evals ذخیره شود، وقتی route/account انتخابی از stored chat completions پشتیبانی کند.
`tools`	array	خیر	لیستی از ابزارهایی که مدل ممکن است فراخوانی کند.
`tool_choice`	string or object	خیر	کنترل می‌کند که کدام ابزار (در صورت وجود) توسط مدل فراخوانی شود.
`parallel_tool_calls`	boolean	خیر	آیا فراخوانی‌های function/tool موازی مجاز باشد. برای ابزارهایی که state را تغییر می‌دهند یا execution ترتیبی می‌خواهند مقدار `false` بگذارید.
`web_search_options`	object	خیر	گزینه‌های web search سازگار با Chat وقتی مدل OpenAI-style انتخابی از web search داخلی پشتیبانی کند. برای retrieval مستقل از provider، `/v1/search` را ترجیح دهید.
`service_tier`	string	خیر	سطح سرویس مورد استفاده برای این درخواست. AvalAI به‌طور عمومی `"default"` (پیش‌فرض) و `"flex"` را پشتیبانی می‌کند. سطح flex ۵۰٪ کاهش قیمت برای مدل‌های منتخب OpenAI ارائه می‌دهد اما تاخیر بالاتر دارد و ممکن است تایم‌اوت شود (تا ۹۰۰ ثانیه). بعضی مثال‌های OpenAI ممکن است `"priority"` داشته باشند؛ در AvalAI از `"default"` استفاده کنید مگر اینکه priority processing صراحتا برای حساب شما فعال شده باشد. قیمت‌گذاری را ببینید.

نکته

پشتیبانی پارامترها به مدل و provider وابسته است. مدل‌های reasoning جدید ممکن است برخی فیلدهای قدیمی sampling، stop یا token را نادیده بگیرند یا reject کنند، و ابزارهای hosted در AvalAI به route/account وابسته‌اند. اگر یک workflow جدید OpenAI-style با ابزار، state یا reasoning می‌سازید، قبل از انتخاب Chat Completions این صفحه را با Responses مقایسه کنید.

برای response_format، هر زمان مدل و route انتخابی پشتیبانی می‌کنند، json_schema را به json_object ترجیح دهید. حالت JSON فقط معتبر بودن syntax JSON را تضمین می‌کند؛ کلیدهای الزامی، مقدارهای enum یا typeهای برنامه شما را تضمین نمی‌کند، پس نتیجه parse شده را در برنامه validate کنید. برای طراحی schema، مدیریت refusal و migration به text.format در Responses، خروجی‌های ساختاریافته را ببینید.

شی پیام (Message Object)

هر پیام در آرایه messages باید ساختار زیر را داشته باشد:

پارامتر	نوع	الزامی	توضیحات
`role`	string	بله	نقش نویسنده پیام. نقش‌های رایج عبارت‌اند از `developer`، `system`، `user`، `assistant` و `tool`. بسته به پشتیبانی مدل، برای دستورهای پایدار از `developer` یا `system` استفاده کنید.
`content`	string or array	بله	محتوای پیام. می‌تواند یک رشته یا آرایه‌ای از بخش‌های محتوا هنگام استفاده از ورودی‌های چندوجهی باشد.
`name`	string	خیر	نام نویسنده این پیام. برای نقش‌های `tool` الزامی است.
`tool_call_id`	string	خیر	برای پیام‌های نقش `tool` الزامی است. شناسه فراخوانی ابزاری که این پیام به آن پاسخ می‌دهد.

مثال‌ها

تکمیل گفتگوی پایه

bash

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

python

# مثال پایتون (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.6-sol",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
)

print(response.choices[0].message.content)

javascript

# مثال جاوااسکریپت (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.5",
  messages: [
  {"role": "system", "content": "You are a helpful assistant."},
  {"role": "user", "content": "Hello!"}
  ]
});

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

go

# مثال گو (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) // دسترسی صحیح به محتوای پاسخ
}

php

<?php
// مثال PHP برای تکمیل گفتگو از طریق AvalAI

$apiKey = getenv('AVALAI_API_KEY'); // یا مستقیما با کلید خود جایگزین کنید
$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!'] // محتوای کاربر به انگلیسی باقی می‌ماند یا ترجمه می‌شود؟
]
// در صورت نیاز پارامترهای دیگری مانند دما، حداکثر توکن و غیره را اضافه کنید
// '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 #:" . $err;
} elseif ($httpcode >= 400) {
  echo "خطای HTTP: " . $httpcode . "\n";
  echo $response;
} else {
  $responseData = json_decode($response, true);
  if (isset($responseData['choices'][0]['message']['content'])) {
    echo "دستیار: " . $responseData['choices'][0]['message']['content'] . "\n";
  } else {
    echo "پاسخ دریافت شد:\n";
    print_r($responseData);
  }
}
?>

نسخه معادل Responses API

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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.5",
  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
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

فرمت پاسخ (Response Format)

json

{
  "id": "chatcmpl-123abc",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "gpt-5.6-sol",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "سلام! چطور می‌توانم امروز به شما کمک کنم؟"
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  },
  "service_tier": "default"
}

پارامترهای پاسخ (Response Parameters)

پارامتر	نوع	توضیحات
`id`	string	یک شناسه منحصر به فرد برای تکمیل گفتگو.
`object`	string	نوع شی، که همیشه "chat.completion" است.
`created`	integer	زمان یونیکس (به ثانیه) ایجاد تکمیل گفتگو.
`model`	string	مدلی که برای تکمیل گفتگو استفاده شده است.
`choices`	array	آرایه‌ای از انتخاب‌های تکمیل گفتگو.
`usage`	object	یک شی حاوی اطلاعات استفاده از توکن.
`moderation`	object	نتایج inline moderation ورودی/خروجی، در صورت درخواست و پشتیبانی.
`service_tier`	string	سطح سرویس استفاده شده برای این درخواست. مقادیر عمومی AvalAI معمولا `"default"` یا `"flex"` هستند؛ `"priority"` فقط در صورت فعال‌سازی صریح برای حساب/route قابل اتکاست.

شی انتخاب (Choice Object)

پارامتر	نوع	توضیحات
`message`	object	یک شی پیام حاوی محتوای پاسخ.
`finish_reason`	string	دلیلی که مدل تولید توکن‌ها را متوقف کرده است. می‌تواند "stop", "length", "tool_calls", "content_filter", یا "function_call" باشد.
`index`	integer	شاخص انتخاب در آرایه.

شی استفاده (Usage Object)

پارامتر	نوع	توضیحات
`prompt_tokens`	integer	تعداد توکن‌های استفاده شده در پرامپت.
`completion_tokens`	integer	تعداد توکن‌های استفاده شده در تکمیل.
`total_tokens`	integer	تعداد کل توکن‌های استفاده شده (پرامپت + تکمیل).

استریمینگ (Streaming)

برای دریافت پاسخ‌های افزایشی مدل، stream: true را در درخواست خود تنظیم کنید:

javascript

const stream = await client.chat.completions.create({
  model: "gpt-5.5",
  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

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

فراخوانی تابع / استفاده از ابزار (Function Calling / Tool Use)

می‌توانید ابزارهایی را مشخص کنید که مدل می‌تواند فراخوانی کند:

javascript

const response = await client.chat.completions.create({
  model: "gpt-5.5",
  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

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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": "هوای سان‌فرانسیسکو را با واحد سانتی‌گراد بگو.",
    }
]

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
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
tool_calls به آیتم‌های response.output با مقدار type == "function_call" تبدیل می‌شود؛ نتیجه را با آیتم function_call_output و همان call_id برگردانید.
وقتی tool loop را دستی مدیریت می‌کنید، آیتم‌های قبلی response.output را نگه دارید، به‌ویژه برای مدل‌های دارای reasoning.

ورودی و خروجی صوتی

مدل‌های صوتی OpenAI (gpt-audio و gpt-audio-mini) از ورودی/خروجی صوتی و متنی از طریق Chat Completions API پشتیبانی می‌کنند. این مدل‌ها امکان ایجاد برنامه‌های مکالمه‌ای مبتنی بر صدا با قابلیت‌های پردازش صوتی بومی را فراهم می‌آورند.

پارامترهای صوتی

هنگام استفاده از مدل‌های صوتی، می‌توانید پارامترهای اضافی را مشخص کنید:

پارامتر	نوع	الزامی	توضیحات
`modalities`	array	خیر	وجوه خروجی را مشخص می‌کند. از `["text", "audio"]` برای خروجی صوتی استفاده کنید. برای مدل‌های تولید تصویر مانند `gemini-3-pro-image`، `gemini-3.1-flash-image`، `gemini-3.1-flash-lite-image` و `gemini-2.5-flash-image` از `["image", "text"]` استفاده کنید. پیش‌فرض `["text"]` است.
`audio`	object	خیر	پیکربندی خروجی صوتی. هنگام درخواست خروجی صوتی الزامی است.

شی پیکربندی صوتی

پارامتر	نوع	الزامی	توضیحات
`format`	string	خیر	فرمت خروجی صوتی. گزینه‌ها: `mp3`, `wav`, `pcm16`, `opus`, `aac`, `flac`. پیش‌فرض `mp3` است.
`voice`	string	خیر	صدای مورد استفاده برای خروجی صوتی. گزینه‌ها: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`. پیش‌فرض `alloy` است.

تولید صوتی پایه

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": "محاسبات کوانتومی را به زبان ساده توضیح بده."
      }
    ],
    "modalities": ["text", "audio"],
    "audio": {
      "format": "mp3",
      "voice": "nova"
    }
  }'

python

from openai import OpenAI

client = OpenAI(api_key="avalai-api-key", base_url="https://api.avalai.ir/v1")

response = client.chat.completions.create(
    model="gpt-audio",
    messages=[
        {"role": "user", "content": "محاسبات کوانتومی را به زبان ساده توضیح بده."}
    ],
    modalities=["text", "audio"],
    audio={"format": "mp3", "voice": "nova"},
)

# دسترسی به داده‌های صوتی و متن رونویسی
audio_data = response.choices[0].message.audio.data  # صدای رمزگذاری‌شده Base64
transcript = response.choices[0].message.audio.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: "محاسبات کوانتومی را به زبان ساده توضیح بده.",
        },
    ],
    modalities: ["text", "audio"],
    audio: {
        format: "mp3",
        voice: "nova",
    },
});

// دسترسی به داده‌های صوتی و متن رونویسی
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("محاسبات کوانتومی را به زبان ساده توضیح بده."),
		}),
		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' => 'محاسبات کوانتومی را به زبان ساده توضیح بده.',
        ],
    ],
    'modalities' => ['text', 'audio'],
    'audio' => [
        'format' => 'mp3',
        'voice' => 'nova',
    ],
]);

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

echo "متن رونویسی: " . $transcript . "\n";

نسخه معادل Responses API

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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="محاسبات کوانتومی را به زبان ساده توضیح بده.",
)

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: "محاسبات کوانتومی را به زبان ساده توضیح بده.",
});

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": "محاسبات کوانتومی را به زبان ساده توضیح بده.",
    "instructions": "You are a helpful assistant."
  }'

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

فرمت پاسخ صوتی

هنگام استفاده از مدل‌های صوتی با وجه audio، پاسخ شامل یک شی audio در پیام است:

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

          "expires_at": 1763045747,
          "transcript": "محاسبات کوانتومی یک فناوری انقلابی است..."
        }
      },
      "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
    }
  }
}

استفاده از gpt-audio-1.5 برای کیفیت صوتی پرمیوم

برای بالاترین کیفیت سنتز صدا و درک صوتی، از gpt-audio-1.5 استفاده کنید:

python

response = client.chat.completions.create(
    model="gpt-audio-1.5",  # بهترین مدل صوتی با زمینه ۲۵۶ هزار توکن
    messages=[{"role": "user", "content": "هوای امروز چطور است؟"}],
    modalities=["text", "audio"],
    audio={"format": "mp3", "voice": "nova"},
)

نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `gpt-audio-1.5` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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="هوای امروز چطور است؟",
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

استفاده از gpt-audio-mini برای پردازش مقرون به صرفه

برای برنامه‌های با حجم بالا، از gpt-audio-mini استفاده کنید که قابلیت‌های مشابه را با هزینه کمتری ارائه می‌دهد:

python

response = client.chat.completions.create(
    model="gpt-audio-mini",  # گزینه مقرون به صرفه‌تر
    messages=[{"role": "user", "content": "هوای امروز چطور است؟"}],
    modalities=["text", "audio"],
    audio={"format": "mp3", "voice": "alloy"},
)

نسخه معادل Responses API

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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="هوای امروز چطور است؟",
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

مدل‌های صوتی قدیمی

برای سازگاری با نسخه‌های قبلی، مدل‌های پیش‌نمایش زیر همچنان در دسترس هستند:

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

توجه

ورودی صوتی (آپلود فایل‌های صوتی) هنوز در Chat Completions API پشتیبانی نمی‌شود. برای رونویسی صدا به متن، از API رونویسی صوتی استفاده کنید.

مدیریت خطا (Error Handling)

API ممکن است کدهای خطای مختلفی را برگرداند:

کد وضعیت	توضیحات
400	درخواست بد - درخواست شما نامعتبر است.
401	غیرمجاز - کلید API شما اشتباه است.
403	ممنوع - شما اجازه دسترسی به این منبع را ندارید.
404	یافت نشد - منبع مشخص شده یافت نشد.
429	درخواست‌های بیش از حد - شما از محدودیت نرخ خود فراتر رفته‌اید.
500	خطای داخلی سرور - مشکلی در سرور ما وجود داشت.

برای اطلاعات بیشتر در مورد مدیریت خطاها، به راهنمای مدیریت خطا مراجعه کنید.

منابع مرتبط

مدل‌ها - درباره مدل‌های موجود بیاموزید
احراز هویت - درباره روش‌های احراز هویت بیاموزید
محدودیت‌های نرخ - درباره محدودیت‌های نرخ API بیاموزید

API تکمیل گفتگو (Chat Completions) ​

نقطه پایانی (Endpoint) ​

بدنه درخواست (Request Body) ​

شی پیام (Message Object) ​

مثال‌ها ​

تکمیل گفتگوی پایه ​

فرمت پاسخ (Response Format) ​

پارامترهای پاسخ (Response Parameters) ​

شی انتخاب (Choice Object) ​

شی استفاده (Usage Object) ​

استریمینگ (Streaming) ​

فراخوانی تابع / استفاده از ابزار (Function Calling / Tool Use) ​

ورودی و خروجی صوتی ​

پارامترهای صوتی ​

شی پیکربندی صوتی ​

تولید صوتی پایه ​

فرمت پاسخ صوتی ​

استفاده از gpt-audio-1.5 برای کیفیت صوتی پرمیوم ​

استفاده از gpt-audio-mini برای پردازش مقرون به صرفه ​

مدل‌های صوتی قدیمی ​

مدیریت خطا (Error Handling) ​

منابع مرتبط ​

API تکمیل گفتگو (Chat Completions)

نقطه پایانی (Endpoint)

بدنه درخواست (Request Body)

شی پیام (Message Object)

مثال‌ها

تکمیل گفتگوی پایه

فرمت پاسخ (Response Format)

پارامترهای پاسخ (Response Parameters)

شی انتخاب (Choice Object)

شی استفاده (Usage Object)

استریمینگ (Streaming)

فراخوانی تابع / استفاده از ابزار (Function Calling / Tool Use)

ورودی و خروجی صوتی

پارامترهای صوتی

شی پیکربندی صوتی

تولید صوتی پایه

فرمت پاسخ صوتی

استفاده از gpt-audio-1.5 برای کیفیت صوتی پرمیوم

استفاده از gpt-audio-mini برای پردازش مقرون به صرفه

مدل‌های صوتی قدیمی

مدیریت خطا (Error Handling)

منابع مرتبط