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

وقتی یک فراخوانی مدل باید صوت را بپذیرد، صوت گفتاری برگرداند، یا یک گفت‌وگوی صوتی کوتاه را ادامه دهد، از مدل‌های 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 متنی را برای جستجو و تحلیل نگه دارید؛ بایت‌های صوتی را فقط وقتی برای پخش نیاز دارید ذخیره کنید.

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"));
}

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

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

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.5",
    instructions="متن گفتاری کوتاه برای یک پلتفرم توسعه‌دهندگان بنویس.",
    input="به یک توسعه‌دهنده جدید خوشامد بگو و https://api.avalai.ir/v1 را ذکر کن.",
)

with client.audio.speech.with_streaming_response.create(
    model="gpt-4o-mini-tts",
    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.5",
  instructions: "متن گفتاری کوتاه برای یک پلتفرم توسعه‌دهندگان بنویس.",
  input: "به یک توسعه‌دهنده جدید خوشامد بگو و https://api.avalai.ir/v1 را ذکر کن.",
});

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

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

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

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

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 بفرستید و وقتی پخش صوتی لازم است، متن نهایی را به گفتار تبدیل کنید.

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.5",
    instructions=instructions,
    input="آیا می‌توانم SDK پایتون OpenAI را با AvalAI استفاده کنم؟",
    store=True,
)

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

with client.audio.speech.with_streaming_response.create(
    model="gpt-4o-mini-tts",
    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.5",
  instructions,
  input: "آیا می‌توانم SDK نود OpenAI را با AvalAI استفاده کنم؟",
  store: true,
});

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

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

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

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

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

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، پاسخ مدل و خروجی صوتی.

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-4o-transcribe",
        file=audio_file,
        response_format="text",
    )

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

with client.audio.speech.with_streaming_response.create(
    model="gpt-4o-mini-tts",
    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-4o-transcribe",
  file: fs.createReadStream("question.wav"),
  response_format: "text",
});

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

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

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

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

برای دستیارهای صوتی ابزارمحور، قابل‌اعتمادترین الگوی 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 استفاده کنید.

منابع مرتبط

• مرجع API صوتی
• Realtime و صوت زنده
• مرجع API تکمیل چت
• مرجع API پاسخ‌ها
• راهنمای فراخوانی تابع
• راهنمای پاسخ‌های استریمینگ