ارسال و دریافت صدا — Audio

آشا هم ارسال فایل صوتی به مدل‌های سازگار را پشتیبانی می‌کند و هم دریافت پاسخ صوتی از طریق API. این راهنما نحوهٔ کار با ورودی‌های صوتی و خروجی‌های صوتی را پوشش می‌دهد.

ورودی صوتی

فایل‌های صوتی را برای رونویسی، تحلیل و پردازش به مدل‌های سازگار بفرستید. درخواست‌های ورودی صوتی از API /v1/chat/completions با نوع محتوای input_audio استفاده می‌کنند. فایل‌های صوتی باید base64 کد شده و شامل مشخصات فرمت باشند.

نکته: فایل‌های صوتی باید base64 کد شوند — URL مستقیم برای محتوای صوتی پشتیبانی نمی‌شود.

می‌توانید مدل‌های پشتیبانِ ورودی صوتی را در صفحهٔ مدل‌ها با فیلتر کردن بر اساس حالتِ «ورودی صوتی» پیدا کنید.

ارسال فایل‌های صوتی

در اینجا نحوهٔ ارسال یک فایل صوتی برای پردازش آمده است:

import base64
import os

import requests

def encode_audio_to_base64(audio_path):
    with open(audio_path, "rb") as audio_file:
        return base64.b64encode(audio_file.read()).decode("utf-8")

url = "https://app.asha-ai.ir/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {os.environ['ASHA_API_KEY']}",
    "Content-Type": "application/json",
}

# Read and encode the audio file
audio_path = "path/to/your/audio.wav"
base64_audio = encode_audio_to_base64(audio_path)

payload = {
    "model": "~google/gemini-2.5-flash",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Please transcribe this audio file."},
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": base64_audio,
                        "format": "wav",
                    },
                },
            ],
        }
    ],
    "stream": False,
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
package main

import (
	"bytes"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func encodeAudioToBase64(audioPath string) (string, error) {
	raw, err := os.ReadFile(audioPath)
	if err != nil {
		return "", err
	}
	return base64.StdEncoding.EncodeToString(raw), nil
}

func main() {
	audioPath := "path/to/your/audio.wav"
	base64Audio, _ := encodeAudioToBase64(audioPath)

	payload := map[string]any{
		"model": "~google/gemini-2.5-flash",
		"messages": []any{
			map[string]any{
				"role": "user",
				"content": []any{
					map[string]any{"type": "text", "text": "Please transcribe this audio file."},
					map[string]any{
						"type": "input_audio",
						"input_audio": map[string]any{
							"data":   base64Audio,
							"format": "wav",
						},
					},
				},
			},
		},
		"stream": false,
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", "https://app.asha-ai.ir/v1/chat/completions", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("ASHA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]any
	_ = json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}
import fs from "fs/promises";

async function encodeAudioToBase64(audioPath: string): Promise<string> {
  const audioBuffer = await fs.readFile(audioPath);
  return audioBuffer.toString("base64");
}

// Read and encode the audio file
const audioPath = "path/to/your/audio.wav";
const base64Audio = await encodeAudioToBase64(audioPath);

const response = await fetch("https://app.asha-ai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ASHA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "~google/gemini-2.5-flash",
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "Please transcribe this audio file." },
          {
            type: "input_audio",
            input_audio: { data: base64Audio, format: "wav" },
          },
        ],
      },
    ],
  }),
});

const data = await response.json();
console.log(data);
import fs from "fs/promises";

async function encodeAudioToBase64(audioPath) {
  const audioBuffer = await fs.readFile(audioPath);
  return audioBuffer.toString("base64");
}

// Read and encode the audio file
const audioPath = "path/to/your/audio.wav";
const base64Audio = await encodeAudioToBase64(audioPath);

const response = await fetch("https://app.asha-ai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ASHA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "~google/gemini-2.5-flash",
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "Please transcribe this audio file." },
          {
            type: "input_audio",
            input_audio: { data: base64Audio, format: "wav" },
          },
        ],
      },
    ],
  }),
});

const data = await response.json();
console.log(data);
# Base64-encode your audio file
AUDIO_BASE64=$(base64 < audio.wav | tr -d 'n')

curl https://app.asha-ai.ir/v1/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $ASHA_API_KEY" 
  -d '{
    "model": "~google/gemini-2.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Please transcribe this audio file." },
          { "type": "input_audio", "input_audio": { "data": "'"$AUDIO_BASE64"'", "format": "wav" } }
        ]
      }
    ]
  }'

فرمت‌های ورودی صوتی پشتیبانی‌شده

فرمت‌های پشتیبانی‌شده بسته به ارائه‌دهنده متفاوت‌اند. از جمله فرمت‌های رایج:

  • wav — صوت WAV
  • mp3 — صوت MP3
  • aiff — صوت AIFF
  • aac — صوت AAC
  • ogg — صوت OGG Vorbis
  • flac — صوت FLAC
  • m4a — صوت M4A
  • pcm16 — صوت PCM16
  • pcm24 — صوت PCM24
نکته: مستندات مدل خود را بررسی کنید تا مطمئن شوید کدام فرمت‌های صوتی را پشتیبانی می‌کند. همهٔ مدل‌ها از همهٔ فرمت‌ها پشتیبانی نمی‌کنند.

خروجی صوتی

آشا دریافت پاسخ صوتی از مدل‌هایی که قابلیت خروجی صوتی دارند را پشتیبانی می‌کند. برای درخواست خروجی صوتی، پارامترهای modalities و audio را در درخواست خود قرار دهید.

می‌توانید مدل‌های پشتیبانِ خروجی صوتی را در صفحهٔ مدل‌ها با فیلتر کردن بر اساس حالتِ «خروجی صوتی» پیدا کنید.

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

برای دریافت خروجی صوتی، modalities را روی ["text", "audio"] تنظیم و پیکربندی audio را با صدا و فرمت دلخواه ارائه کنید:

import base64
import json
import os

import requests

url = "https://app.asha-ai.ir/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {os.environ['ASHA_API_KEY']}",
    "Content-Type": "application/json",
}

payload = {
    "model": "~openai/gpt-audio",
    "messages": [
        {"role": "user", "content": "Say hello in a friendly tone."}
    ],
    "modalities": ["text", "audio"],
    "audio": {
        "voice": "alloy",
        "format": "wav",
    },
    "stream": True,
}

# Audio output requires streaming — the response is delivered as SSE chunks
response = requests.post(url, headers=headers, json=payload, stream=True)

audio_data_chunks = []
transcript_chunks = []

for line in response.iter_lines():
    if not line:
        continue
    decoded = line.decode("utf-8")
    if not decoded.startswith("data: "):
        continue
    data = decoded[len("data: "):]
    if data.strip() == "[DONE]":
        break
    chunk = json.loads(data)
    delta = chunk["choices"][0].get("delta", {})
    audio = delta.get("audio", {})
    if audio.get("data"):
        audio_data_chunks.append(audio["data"])
    if audio.get("transcript"):
        transcript_chunks.append(audio["transcript"])

transcript = "".join(transcript_chunks)
print(f"Transcript: {transcript}")

# Combine and decode the base64 audio chunks, then save
full_audio_b64 = "".join(audio_data_chunks)
audio_bytes = base64.b64decode(full_audio_b64)
with open("output.wav", "wb") as f:
    f.write(audio_bytes)
const response = await fetch("https://app.asha-ai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ASHA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "~openai/gpt-audio",
    messages: [
      {
        role: "user",
        content: "Say hello in a friendly tone.",
      },
    ],
    modalities: ["text", "audio"],
    audio: {
      voice: "alloy",
      format: "wav",
    },
    stream: true,
  }),
});

// Audio output requires streaming — parse the SSE chunks
const reader = response.body!.getReader();
const decoder = new TextDecoder();

const audioDataChunks: string[] = [];
const transcriptChunks: string[] = [];
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("n");
  buffer = lines.pop()!; // keep incomplete line in buffer

  for (const line of lines) {
    if (!line.startsWith("data: ")) continue;
    const data = line.slice("data: ".length).trim();
    if (data === "[DONE]") break;

    const chunk = JSON.parse(data);
    const audio = chunk.choices?.[0]?.delta?.audio;
    if (audio?.data) audioDataChunks.push(audio.data);
    if (audio?.transcript) transcriptChunks.push(audio.transcript);
  }
}

const transcript = transcriptChunks.join("");
console.log(`Transcript: ${transcript}`);

// audioDataChunks joined together is the full base64-encoded audio
const fullAudioB64 = audioDataChunks.join("");
curl -N https://app.asha-ai.ir/v1/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $ASHA_API_KEY" 
  -d '{
    "model": "~openai/gpt-audio",
    "messages": [
      {
        "role": "user",
        "content": "Say hello in a friendly tone."
      }
    ],
    "modalities": ["text", "audio"],
    "audio": {
      "voice": "alloy",
      "format": "wav"
    },
    "stream": true
  }'

قالب چانک جریانی

خروجی صوتی نیاز به جریان‌سازی (stream: true) دارد. دادهٔ صوتی و متن به‌صورت تدریجی از طریق فیلد delta.audio در هر چانک ارائه می‌شوند:

JSON chunk
{
  "choices": [
    {
      "delta": {
        "audio": {
          "data": "<base64-encoded audio chunk>",
          "transcript": "Hello"
        }
      }
    }
  ]
}

گزینه‌های پیکربندی صدا

پارامتر audio گزینه‌های زیر را می‌پذیرد:

گزینهشرح
voice صدایی که برای تولید صوت استفاده می‌شود (مثلاً alloy، echo، fable، onyx، nova، shimmer). صداهای در دسترس بسته به مدل متفاوت‌اند.
format فرمت صوتی خروجی (مثلاً wav، mp3، flac، opus، pcm16). فرمت‌های در دسترس بسته به مدل متفاوت‌اند.

سؤالات متداول

آیا می‌توانم فایل صوتی را با URL مستقیم بفرستم؟

خیر. محتوای صوتی باید base64 کد شود و در نوع محتوای input_audio ارسال شود؛ URL مستقیم برای صوت پشتیبانی نمی‌شود.

خروجی صوتی جریانی است یا کامل؟

خروجی صوتی نیاز به جریان‌سازی (stream: true) دارد؛ دادهٔ صوتی و متن به‌صورت تکه‌تکه در فیلد delta.audio می‌رسند.

کدام مدل‌ها ورودی صوتی می‌پذیرند؟

مدل‌هایی که حالت «ورودی صوتی» را در صفحهٔ مدل‌ها دارند، مثل مدل‌های خانوادهٔ Gemini.

کدام مدل‌ها خروجی صوتی تولید می‌کنند؟

مدل‌های دارای حالت «خروجی صوتی» مثل ~openai/gpt-audio؛ با پارامترهای modalities و audio فعال می‌شوند.

از کدام صداها می‌توانم استفاده کنم؟

صدای انتخابی (مثل alloy) از طریق گزینهٔ audio.voice تعیین می‌شود؛ صداهای موجود بسته به مدل و ارائه‌دهنده متفاوت‌اند.