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

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

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

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

ساخت برنامه‌های گفت‌وگومحور با مدل‌های صوتی

وقتی یک فراخوانی مدل باید صوت را بپذیرد، صوت گفتاری برگرداند، یا یک گفت‌وگوی صوتی کوتاه را ادامه دهد، از مدل‌های chat صوتی AvalAI استفاده کنید. برای reasoning عمیق‌تر، ابزارها، خروجی ساختاریافته یا مدیریت state، مسیر Responses-first بهتر است: صوت را رونویسی کنید، با /v1/responses reasoning انجام دهید و سپس گفتار بسازید.

مستندات مرتبط: API صوتی، پردازش صوت در Chat Completions، راهنمای پردازش صوت، Realtime و صوت زنده، Responses در برابر Chat Completions

انتخاب معماری

معماری	چه زمانی استفاده شود	مسیر AvalAI
Chat Completions صوتی مستقیم	به `input_audio`، `modalities` یا `message.audio` در یک فراخوانی نیاز دارید.	`/v1/chat/completions`
دستیار صوتی Responses-first	به ابزارها، reasoning، خروجی ساختاریافته یا state تمیزتر نیاز دارید.	`/v1/audio/transcriptions` → `/v1/responses` → `/v1/audio/speech`
برنامه صوتی Realtime	به صوت زنده و کم‌تاخیر در مرورگر یا تلفن نیاز دارید.	برای طراحی معماری از Realtime و صوت زنده شروع کنید؛ مگر اینکه Realtime برای حساب شما فعال باشد، از مسیرهای request-based AvalAI استفاده کنید.

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

مدل	مناسب برای
`gpt-audio-1.5`	کیفیت صوتی پرمیوم و گفت‌وگوهای صوتی طولانی‌تر.
`gpt-audio`	برنامه‌های متعادل با ورودی/خروجی صوتی.
`gpt-audio-mini`	توسعه، جریان‌های پشتیبانی و قابلیت‌های صوتی پرترافیک.

مثال ۱: پاسخ صوتی یک‌مرحله‌ای

ساده‌ترین الگو، متن را می‌فرستد و از مدل متن همراه با صوت می‌خواهد. transcript متنی را برای جستجو و تحلیل نگه دارید؛ بایت‌های صوتی را فقط وقتی برای پخش نیاز دارید ذخیره کنید.

BashPythonJavaScript

bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-audio-mini",
    "modalities": ["text", "audio"],
    "audio": { "voice": "alloy", "format": "mp3" },
    "messages": [
      {
        "role": "system",
        "content": "تو یک دستیار صوتی کوتاه‌گو برای یک پلتفرم توسعه‌دهندگان هستی."
      },
      {
        "role": "user",
        "content": "به یک توسعه‌دهنده جدید خوشامد بگو و base URL سازگار با OpenAI را هم ذکر کن."
      }
    ]
  }'

python

import base64
import os
from openai import OpenAI

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

completion = client.chat.completions.create(
    model="gpt-audio-mini",
    modalities=["text", "audio"],
    audio={"voice": "alloy", "format": "mp3"},
    messages=[
        {
            "role": "system",
            "content": "تو یک دستیار صوتی کوتاه‌گو برای یک پلتفرم توسعه‌دهندگان هستی.",
        },
        {
            "role": "user",
            "content": "به یک توسعه‌دهنده جدید خوشامد بگو و base URL سازگار با OpenAI را هم ذکر کن.",
        },
    ],
)

message = completion.choices[0].message
print(message.content)

if message.audio:
    with open("welcome.mp3", "wb") as audio_file:
        audio_file.write(base64.b64decode(message.audio.data))

javascript

import fs from "node:fs/promises";
import OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: "gpt-audio-mini",
  modalities: ["text", "audio"],
  audio: { voice: "alloy", format: "mp3" },
  messages: [
    {
      role: "system",
      content: "تو یک دستیار صوتی کوتاه‌گو برای یک پلتفرم توسعه‌دهندگان هستی.",
    },
    {
      role: "user",
      content:
        "به یک توسعه‌دهنده جدید خوشامد بگو و base URL سازگار با OpenAI را هم ذکر کن.",
    },
  ],
});

const message = completion.choices[0].message;
console.log(message.content);

if (message.audio?.data) {
  await fs.writeFile("welcome.mp3", Buffer.from(message.audio.data, "base64"));
}

صدای بازگشتی به‌صورت Base64 در مسیر choices[0].message.audio.data قرار می‌گیرد. با یک دستور یک‌باره در ترمینال (به jq نیاز دارد) می‌توانید آن را به یک فایل MP3 قابل پخش تبدیل کنید:

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-mini",
    "modalities": ["text", "audio"],
    "audio": { "voice": "alloy", "format": "mp3" },
    "messages": [
      {
        "role": "system",
        "content": "تو یک دستیار صوتی کوتاه‌گو برای یک پلتفرم توسعه‌دهندگان هستی."
      },
      {
        "role": "user",
        "content": "به یک توسعه‌دهنده جدید خوشامد بگو و base URL سازگار با OpenAI را هم ذکر کن."
      }
    ]
  }' \
  | jq -r '.choices[0].message.audio.data' \
  | base64 -D > welcome.mp3

afplay welcome.mp3

bash

# لینوکس (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-mini",
    "modalities": ["text", "audio"],
    "audio": { "voice": "alloy", "format": "mp3" },
    "messages": [
      {
        "role": "system",
        "content": "تو یک دستیار صوتی کوتاه‌گو برای یک پلتفرم توسعه‌دهندگان هستی."
      },
      {
        "role": "user",
        "content": "به یک توسعه‌دهنده جدید خوشامد بگو و base URL سازگار با OpenAI را هم ذکر کن."
      }
    ]
  }' \
  | jq -r '.choices[0].message.audio.data' \
  | base64 --decode >welcome.mp3

ffplay -nodisp -autoexit welcome.mp3

powershell

# ویندوز (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-mini",
    "modalities": ["text", "audio"],
    "audio": { "voice": "alloy", "format": "mp3" },
    "messages": [
      {
        "role": "system",
        "content": "تو یک دستیار صوتی کوتاه‌گو برای یک پلتفرم توسعه‌دهندگان هستی."
      },
      {
        "role": "user",
        "content": "به یک توسعه‌دهنده جدید خوشامد بگو و base URL سازگار با OpenAI را هم ذکر کن."
      }
    ]
  }' | ConvertFrom-Json

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

Start-Process .\welcome.mp3

این‌ها دستورهای یک‌باره ترمینال هستند و نیازی نیست چیزی به .zshrc، .bashrc یا پروفایل PowerShell اضافه شود.

نسخه Responses: اول متن را بنویسید، سپس گفتار بسازید.

وقتی می‌خواهید متن پاسخ از قابلیت‌های Responses استفاده کند و لازم نیست همان فراخوانی مدل message.audio برگرداند، از این مسیر استفاده کنید.

PythonJavaScript

python

import os
from pathlib import Path
from openai import OpenAI

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

script = client.responses.create(
    model="gpt-5.6-luna",
    instructions="متن گفتاری کوتاه برای یک پلتفرم توسعه‌دهندگان بنویس.",
    input="به یک توسعه‌دهنده جدید خوشامد بگو و https://api.avalai.ir/v1 را ذکر کن.",
)

with client.audio.speech.with_streaming_response.create(
    model="gpt-audio-1.5",
    voice="alloy",
    input=script.output_text,
) as speech:
    speech.stream_to_file(Path("welcome.mp3"))

javascript

import fs from "node:fs/promises";
import OpenAI from "openai";

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

const script = await client.responses.create({
  model: "gpt-5.6-luna",
  instructions: "متن گفتاری کوتاه برای یک پلتفرم توسعه‌دهندگان بنویس.",
  input: "به یک توسعه‌دهنده جدید خوشامد بگو و https://api.avalai.ir/v1 را ذکر کن.",
});

const speech = await client.audio.speech.create({
  model: "gpt-audio-1.5",
  voice: "alloy",
  input: script.output_text,
});

await fs.writeFile("welcome.mp3", Buffer.from(await speech.arrayBuffer()));

مثال ۲: گفت‌وگوی صوتی چندمرحله‌ای

برای sessionهای کوتاه، transcript متنی را در برنامه نگه دارید و پیام‌های کاربر/دستیار را به messages اضافه کنید. صوت تولیدشده را دوباره نفرستید، مگر اینکه مدل باید خود صوت را تحلیل کند.

PythonJavaScript

python

import base64
import os
from openai import OpenAI

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

messages = [
    {"role": "system", "content": "تو یک دستیار پشتیبانی API کوتاه‌گو هستی."},
    {
        "role": "user",
        "content": "آیا می‌توانم SDK پایتون OpenAI را با AvalAI استفاده کنم؟",
    },
]

first = client.chat.completions.create(
    model="gpt-audio-mini",
    modalities=["text", "audio"],
    audio={"voice": "coral", "format": "mp3"},
    messages=messages,
)

assistant_text = first.choices[0].message.content
messages.append({"role": "assistant", "content": assistant_text})
messages.append({"role": "user", "content": "حداقل تنظیمات کلاینت را هم بده."})

second = client.chat.completions.create(
    model="gpt-audio-mini",
    modalities=["text", "audio"],
    audio={"voice": "coral", "format": "mp3"},
    messages=messages,
)

reply = second.choices[0].message
print(reply.content)

if reply.audio:
    with open("followup.mp3", "wb") as audio_file:
        audio_file.write(base64.b64decode(reply.audio.data))

javascript

import fs from "node:fs/promises";
import OpenAI from "openai";

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

const messages = [
  { role: "system", content: "تو یک دستیار پشتیبانی API کوتاه‌گو هستی." },
  { role: "user", content: "آیا می‌توانم SDK نود OpenAI را با AvalAI استفاده کنم؟" },
];

const first = await client.chat.completions.create({
  model: "gpt-audio-mini",
  modalities: ["text", "audio"],
  audio: { voice: "coral", format: "mp3" },
  messages,
});

messages.push({ role: "assistant", content: first.choices[0].message.content });
messages.push({ role: "user", content: "حداقل تنظیمات کلاینت را هم بده." });

const second = await client.chat.completions.create({
  model: "gpt-audio-mini",
  modalities: ["text", "audio"],
  audio: { voice: "coral", format: "mp3" },
  messages,
});

const reply = second.choices[0].message;
console.log(reply.content);

if (reply.audio?.data) {
  await fs.writeFile("followup.mp3", Buffer.from(reply.audio.data, "base64"));
}

نسخه Responses: استفاده از `previous_response_id` برای state گفت‌وگو.

Responses می‌تواند state گفت‌وگو را با previous_response_id نگه دارد. instructions پایدار را در هر turn بفرستید و وقتی پخش صوتی لازم است، متن نهایی را به گفتار تبدیل کنید.

PythonJavaScript

python

import os
from pathlib import Path
from openai import OpenAI

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

instructions = "تو یک دستیار پشتیبانی API کوتاه‌گو هستی."

first = client.responses.create(
    model="gpt-5.6-luna",
    instructions=instructions,
    input="آیا می‌توانم SDK پایتون OpenAI را با AvalAI استفاده کنم؟",
    store=True,
)

second = client.responses.create(
    model="gpt-5.6-luna",
    instructions=instructions,
    input="حداقل تنظیمات کلاینت را هم بده.",
    previous_response_id=first.id,
    store=True,
)

with client.audio.speech.with_streaming_response.create(
    model="gpt-audio-1.5",
    voice="coral",
    input=second.output_text,
) as speech:
    speech.stream_to_file(Path("followup.mp3"))

javascript

import fs from "node:fs/promises";
import OpenAI from "openai";

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

const instructions = "تو یک دستیار پشتیبانی API کوتاه‌گو هستی.";

const first = await client.responses.create({
  model: "gpt-5.6-luna",
  instructions,
  input: "آیا می‌توانم SDK نود OpenAI را با AvalAI استفاده کنم؟",
  store: true,
});

const second = await client.responses.create({
  model: "gpt-5.6-luna",
  instructions,
  input: "حداقل تنظیمات کلاینت را هم بده.",
  previous_response_id: first.id,
  store: true,
});

const speech = await client.audio.speech.create({
  model: "gpt-audio-1.5",
  voice: "coral",
  input: second.output_text,
});

await fs.writeFile("followup.mp3", Buffer.from(await speech.arrayBuffer()));

مثال ۳: ورودی صوتی از کاربر

وقتی مدل باید خود صوت را بررسی کند، از input_audio مستقیم استفاده کنید. برای ذخیره‌های طولانی، صوت تماس پرنویز، analytics یا workflowهای ابزارمحور، ابتدا رونویسی کنید و سپس Responses را به کار ببرید.

PythonJavaScript

python

import base64
import os
from openai import OpenAI

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

with open("question.wav", "rb") as audio_file:
    audio_b64 = base64.b64encode(audio_file.read()).decode("utf-8")

completion = client.chat.completions.create(
    model="gpt-audio-mini",
    modalities=["text", "audio"],
    audio={"voice": "alloy", "format": "wav"},
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "به این سوال گفتاری کوتاه پاسخ بده."},
                {
                    "type": "input_audio",
                    "input_audio": {"data": audio_b64, "format": "wav"},
                },
            ],
        }
    ],
)

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

javascript

import fs from "node:fs/promises";
import OpenAI from "openai";

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

const audioB64 = (await fs.readFile("question.wav")).toString("base64");

const completion = await client.chat.completions.create({
  model: "gpt-audio-mini",
  modalities: ["text", "audio"],
  audio: { voice: "alloy", format: "wav" },
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "به این سوال گفتاری کوتاه پاسخ بده." },
        {
          type: "input_audio",
          input_audio: { data: audioB64, format: "wav" },
        },
      ],
    },
  ],
});

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

نسخه Responses: ابتدا رونویسی کنید، سپس روی متن reasoning انجام دهید.

این مسیر معمولا ساده‌تر عیب‌یابی می‌شود، چون هر مرحله artifact روشنی دارد: transcript، پاسخ مدل و خروجی صوتی.

PythonJavaScript

python

import os
from pathlib import Path
from openai import OpenAI

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

with open("question.wav", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="gpt-transcribe",
        file=audio_file,
        response_format="text",
    )

answer = client.responses.create(
    model="gpt-5.6-luna",
    instructions="به سوال گفتاری کاربر کوتاه پاسخ بده.",
    input=transcript,
)

with client.audio.speech.with_streaming_response.create(
    model="gpt-audio-1.5",
    voice="alloy",
    input=answer.output_text,
) as speech:
    speech.stream_to_file(Path("answer.wav"))

javascript

import fs from "node:fs";
import fsp from "node:fs/promises";
import OpenAI from "openai";

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

const transcript = await client.audio.transcriptions.create({
  model: "gpt-transcribe",
  file: fs.createReadStream("question.wav"),
  response_format: "text",
});

const answer = await client.responses.create({
  model: "gpt-5.6-luna",
  instructions: "به سوال گفتاری کاربر کوتاه پاسخ بده.",
  input: transcript,
});

const speech = await client.audio.speech.create({
  model: "gpt-audio-1.5",
  voice: "alloy",
  input: answer.output_text,
});

await fsp.writeFile("answer.wav", Buffer.from(await speech.arrayBuffer()));

تبدیل متن به گفتار با Gemini 3.8

برای کاربردهای جدید تبدیل متن به گفتار، gemini-3.8-flash-tts را برای کیفیت خلاقانه، اجرای احساسی، لهجه‌های منطقه‌ای و ثبات گفت‌وگوهای طولانی انتخاب کنید. برای توان عملیاتی بالا، تأخیر کم و خواندن متن‌های روزمره، gemini-3.8-flash-lite-tts مناسب‌تر است. هر دو مدل متن دریافت می‌کنند و صوت تولید می‌کنند؛ برای رونویسی، گفت‌وگو با ورودی صوتی، Live API یا استدلال طراحی نشده‌اند.

AvalAI این مدل‌های TTS را فقط از طریق روش‌های بومی /v1beta/models، مسیر /v1/chat/completions و مسیر /v1/audio/speech ارائه می‌دهد. آن‌ها را به /v1/responses، /v1/messages یا مسیر قدیمی /v1/text:synthesize نفرستید. ابتدا پاسخ را با یک مدل گفت‌وگومحور یا استدلالی جداگانه بنویسید و سپس متن نهایی را به TTS بدهید.

bash

curl --fail-with-body -sS https://api.avalai.ir/v1/audio/speech \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "voice": {"name": "Zephyr", "languageCode": "en-US"},
    "input": "Welcome to AvalAI. This voice was generated by AI.",
    "response_format": "mp3"
  }' \
  --output speech.mp3

متن انگلیسی نمونه با languageCode: "en-US" هماهنگ است. چون خروجی با پسوند MP3 ذخیره می‌شود، response_format: "mp3" را صریح تعیین کرده‌ایم. برای توان عملیاتی بالاتر، فقط مقدار model را به gemini-3.8-flash-lite-tts تغییر دهید. برای کنترل گوینده و سبک در هر نوبت و رمزگشایی خروجی بومی بر اساس نوع MIME، نمونه TTS بومی را ببینید.

افزودن ابزارها

برای دستیارهای صوتی ابزارمحور، قابل‌اعتمادترین الگوی AvalAI این است که /v1/responses ابزارها را انتخاب کند و پاسخ نهایی را بنویسد، سپس response.output_text را به /v1/audio/speech بدهید. Chat Completions صوتی مستقیم را زمانی نگه دارید که ورودی/خروجی صوتی نیاز اصلی است و مدل انتخابی رفتار ابزار موردنیاز را پشتیبانی می‌کند.

نکته‌های تولید

هنگام prototype از gpt-audio-mini استفاده کنید؛ وقتی کیفیت یا context طولانی‌تر مهم است، gpt-audio یا gpt-audio-1.5 را ارزیابی کنید.
برای فایل‌های ذخیره‌شده mp3 و برای پخش کم‌تاخیرتر wav یا pcm را ترجیح دهید.
transcript و metadata را کنار فایل‌های صوتی ذخیره کنید تا جستجو، moderation، analytics و بررسی پشتیبانی ساده‌تر شود.
API key را hard-code نکنید؛ AVALAI_API_KEY را از محیط بخوانید.
برای هر turn، model، modalities، فرمت صوت، latency و usage را log کنید.
برای فایل‌ها یا ذخیره‌های نزدیک به محدودیت upload، به جای قرار دادن صوت base64 در chat message از /v1/audio/transcriptions همراه با chunking استفاده کنید.

ساخت برنامه‌های گفت‌وگومحور با مدل‌های صوتی ​

انتخاب معماری ​

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

مثال ۱: پاسخ صوتی یک‌مرحله‌ای ​

مثال ۲: گفت‌وگوی صوتی چندمرحله‌ای ​

مثال ۳: ورودی صوتی از کاربر ​

تبدیل متن به گفتار با Gemini 3.8 ​

افزودن ابزارها ​

نکته‌های تولید ​

منابع مرتبط ​

ساخت برنامه‌های گفت‌وگومحور با مدل‌های صوتی

انتخاب معماری

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

مثال ۱: پاسخ صوتی یک‌مرحله‌ای

مثال ۲: گفت‌وگوی صوتی چندمرحله‌ای

مثال ۳: ورودی صوتی از کاربر

تبدیل متن به گفتار با Gemini 3.8

افزودن ابزارها

نکته‌های تولید

منابع مرتبط