REST API ucapan ke teks untuk audio pendek

Artikel
01/21/2024

Kasus penggunaan untuk REST API Ucapan ke teks untuk audio pendek dibatasi. Gunakan hanya dalam kasus di mana Anda tidak dapat menggunakan Azure Cognitive Service untuk Ucapan SDK.

Sebelum Anda menggunakan REST API Ucapan ke teks untuk audio pendek, pertimbangkan batasan berikut:

Permintaan yang menggunakan REST API untuk audio pendek dan mentrasnmisikan audio secara langsung hanya dapat berisi maksimal 60 detik audio. Format audio input lebih terbatas dibandingkan dengan Speech SDK.
REST API untuk audio pendek hanya mengembalikan hasil akhir. Hal tersebut tidak memberikan hasil parsial.
Terjemahan ucapan tidak didukung melalui REST API untuk audio pendek. Anda perlu menggunakan SDK Ucapan.
Transkripsi batch dan ucapan kustom tidak didukung melalui REST API untuk audio pendek. Anda harus selalu menggunakan REST API Ucapan ke teks untuk transkripsi batch dan ucapan kustom.

Sebelum Anda menggunakan REST API Ucapan ke teks untuk audio pendek, pahami bahwa Anda perlu menyelesaikan pertukaran token sebagai bagian dari autentikasi untuk mengakses layanan. Untuk informasi lebih lanjut, lihat Autentikasi.

Wilayah dan titik akhir

Titik akhir untuk REST API untuk audio pendek memiliki format ini:

https://<REGION_IDENTIFIER>.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1

Ganti <REGION_IDENTIFIER> dengan pengidentifikasi yang cocok dengan wilayah sumber daya Ucapan Anda.

Catatan

Untuk Azure Government dan Microsoft Azure yang dioperasikan oleh titik akhir 21Vianet, lihat artikel tentang sovereign cloud ini.

Format audio

Audio dikirim dalam isi permintaan HTTP POST. Itu harus dalam salah satu format dalam tabel ini:

Format	Codec	Laju bit	Tingkat sampel
WAV	PCM	256 kbps	16 kHz, mono
OGG	OPUS	256 kbps	16 kHz, mono

Catatan

Format sebelumnya didukung melalui REST API untuk audio pendek dan WebSocket di layanan Ucapan. SDK Ucapan saat ini mendukung format WAV dengan codec PCM serta format lain.

Header permintaan

Tabel ini mencantumkan header yang diperlukan dan opsional untuk permintaan ucapan ke teks:

Header	Deskripsi	Diperlukan atau opsional
`Ocp-Apim-Subscription-Key`	Kunci sumber daya Anda untuk layanan Ucapan.	Baik header ini atau `Authorization` diperlukan.
`Authorization`	Token otorisasi didahului oleh kata `Bearer`. Untuk informasi lebih lanjut, lihat Autentikasi.	Baik header ini atau `Ocp-Apim-Subscription-Key` diperlukan.
`Pronunciation-Assessment`	Menentukan parameter untuk menampilkan skor pengucapan dalam hasil pengenalan. Skor ini menilai kualitas pengucapan input ucapan, dengan indikator seperti akurasi, kefasihan, dan kelengkapan. Parameter ini adalah JSON yang dikodekan Base64 yang berisi beberapa parameter terperinci. Untuk mempelajari cara membuat header ini, lihat Parameter penilaian pengucapan.	Opsional
`Content-type`	Menjelaskan format dan codec dari data audio yang disediakan. Nilai yang diterima adalah `audio/wav; codecs=audio/pcm; samplerate=16000` dan `audio/ogg; codecs=opus`.	Wajib
`Transfer-Encoding`	Menentukan bahwa data audio yang dipotong sedang dikirim, bukan satu file. Gunakan header ini hanya jika Anda memotong data audio.	Opsional
`Expect`	Jika menggunakan transfer yang terpotong, kirim `Expect: 100-continue`. Layanan Ucapan mengakui permintaan awal dan menunggu lebih banyak data.	Diperlukan jika Anda mengirim data audio yang terpotong.
`Accept`	Jika disediakan, itu harusnya menjadi `application/json`. Layanan Ucapan memberikan hasil dalam JSON. Beberapa kerangka kerja permintaan memberikan nilai default yang tidak kompatibel. Praktik terbaik adalah selalu menyertakan `Accept`.	Opsional, tetapi direkomendasikan.

Parameter kueri

Parameter ini mungkin disertakan dalam string kueri permintaan REST.

Catatan

Anda harus menambahkan parameter bahasa ke URL untuk menghindari menerima kesalahan HTTP 4xx. Misalnya, bahasa yang diatur ke bahasa Inggris AS melalui titik akhir US Barat adalah: https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Parameter	Deskripsi	Diperlukan atau opsional
`language`	Mengidentifikasi bahasa lisan yang sedang dikenali. Lihat Bahasa yang Didukung.	Wajib
`format`	Menentukan format hasil. Nilai yang diterima adalah `simple` dan `detailed`. Hasil sederhana mencakup `RecognitionStatus`, `DisplayText`, `Offset`, dan `Duration`. Respons terperinci mencakup empat representasi teks tampilan yang berbeda. Pengaturan default-nya `simple`.	Opsional
`profanity`	Menentukan cara menangani kata-kata tidak senonoh dalam hasil pengenalan. Nilai yang diterima adalah: `masked`, yang menggantikan kata-kata kotor dengan tanda bintang. `removed`, yang menghapus semua kata-kata kotor dari hasilnya. `raw`, yang menyertakan kata-kata kotor dalam hasilnya. Pengaturan default-nya `masked`.	Opsional
`cid`	Saat Anda menggunakan Speech Studio untuk membuat model kustom, Anda dapat memanfaatkan nilai ID Titik Akhir dari halaman Penyebaran. Gunakan nilai ID Titik Akhir sebagai argumen untuk `cid` parameter string kueri.	Opsional

Parameter penilaian pengucapan

Tabel ini mencantumkan parameter wajib dan opsional untuk penilaian pengucapan:

Parameter	Deskripsi	Diperlukan atau opsional
`ReferenceText`	Teks yang dievaluasi oleh pengucapan.	Wajib
`GradingSystem`	Sistem poin untuk kalibrasi skor. Sistem `FivePoint` memberikan skor poin floating 0-5, dan `HundredMark` memberikan skor poin floating 0-100. Default: `FivePoint`.	Opsional
`Granularity`	Granularitas evaluasi. Nilai yang diterima adalah: `Phoneme`, yang menunjukkan skor pada tingkat teks lengkap, kata, dan fonem. `Word`, yang menunjukkan skor pada tingkat teks lengkap dan kata. `FullText`, yang menunjukkan skor hanya pada tingkat teks lengkap. Pengaturan default-nya `Phoneme`.	Opsional
`Dimension`	Menentukan kriteria output. Nilai yang diterima adalah: `Basic`, yang menunjukkan hanya skor akurasi. `Comprehensive`, yang menunjukkan skor pada lebih banyak dimensi (misalnya, skor kefasihan dan skor kelengkapan pada tingkat teks lengkap, dan jenis kesalahan pada tingkat kata). Untuk melihat definisi dimensi skor dan jenis kesalahan kata yang berbeda, lihat Properti respons. Pengaturan default-nya `Basic`.	Opsional
`EnableMiscue`	Mengaktifkan perhitungan miscue. Dengan parameter ini diaktifkan, kata-kata yang diucapkan dibandingkan dengan teks referensi. Mereka ditandai dengan kelalaian atau penyisipan berdasarkan perbandingan. Nilai yang diterima adalah `False` dan `True`. Pengaturan default-nya `False`.	Opsional
`ScenarioId`	GUID yang menunjukkan sistem poin disesuaikan.	Opsional

Berikut adalah contoh JSON yang berisi parameter penilaian pengucapan:

{
  "ReferenceText": "Good morning.",
  "GradingSystem": "HundredMark",
  "Granularity": "FullText",
  "Dimension": "Comprehensive"
}

Kode contoh berikut menunjukkan cara menyusun parameter penilaian pengucapan ke dalam header Pronunciation-Assessment:

var pronAssessmentParamsJson = $"{{\"ReferenceText\":\"Good morning.\",\"GradingSystem\":\"HundredMark\",\"Granularity\":\"FullText\",\"Dimension\":\"Comprehensive\"}}";
var pronAssessmentParamsBytes = Encoding.UTF8.GetBytes(pronAssessmentParamsJson);
var pronAssessmentHeader = Convert.ToBase64String(pronAssessmentParamsBytes);

Kami sangat menyarankan streaming (transfer terpotong) mengunggah saat Anda memposting data audio, yang dapat secara signifikan mengurangi latensi. Untuk mempelajari cara mengaktifkan streaming, lihat kode sampel dalam berbagai bahasa pemrogram.

Catatan

Untuk informasi selengkapnya, lihat penilaian pengucapan.

Permintaan sampel

Sampel berikut mencakup nama host dan header yang diperlukan. Penting untuk dicatat bahwa layanan juga mengharapkan data audio, yang tidak termasuk dalam sampel ini. Seperti disebutkan sebelumnya, pemotongan disarankan, tetapi tidak wajib.

POST speech/recognition/conversation/cognitiveservices/v1?language=en-US&format=detailed HTTP/1.1
Accept: application/json;text/xml
Content-Type: audio/wav; codecs=audio/pcm; samplerate=16000
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Host: westus.stt.speech.microsoft.com
Transfer-Encoding: chunked
Expect: 100-continue

Untuk mengaktifkan penilaian pengucapan, Anda dapat menambahkan header berikut. Untuk mempelajari cara membuat header ini, lihat Parameter penilaian pengucapan.

Pronunciation-Assessment: eyJSZWZlcm...

Kode status HTTP

Kode status HTTP untuk setiap respons menunjukkan keberhasilan atau kesalahan umum.

Kode status HTTP	Deskripsi	Kemungkinan alasan
100	Lanjutkan	Permintaan awal diterima. Lanjutkan dengan mengirim sisa data. (Kode ini digunakan dengan transfer yang dipotong.)
200	OK	Permintaan berhasil. Isi respons adalah objek JSON.
400	Permintaan Buruk	Kode bahasa tidak disediakan, bahasa tidak didukung, atau file audio tidak valid (misalnya).
401	Tidak diizinkan	Kunci sumber daya atau token otorisasi tidak valid di wilayah yang ditentukan, atau titik akhir tidak valid.
403	Terlarang	Kunci sumber daya atau token otorisasi hilang.

Respons sampel

Berikut ini adalah respons umum untuk pengenalan simple:

{
  "RecognitionStatus": "Success",
  "DisplayText": "Remind me to buy 5 pencils.",
  "Offset": "1236645672289",
  "Duration": "1236645672289"
}

Berikut ini adalah respons umum untuk pengenalan detailed:

{
  "RecognitionStatus": "Success",
  "Offset": "1236645672289",
  "Duration": "1236645672289",
  "NBest": [
    {
      "Confidence": 0.9052885,
      "Display": "What's the weather like?",
      "ITN": "what's the weather like",
      "Lexical": "what's the weather like",
      "MaskedITN": "what's the weather like"
    },
    {
      "Confidence": 0.92459863,
      "Display": "what is the weather like",
      "ITN": "what is the weather like",
      "Lexical": "what is the weather like",
      "MaskedITN": "what is the weather like"
    }
  ]
}

Respon umum untuk pengenalan dengan penilaian pengucapan:

{
  "RecognitionStatus": "Success",
  "Offset": "400000",
  "Duration": "11000000",
  "NBest": [
      {
        "Confidence" : "0.87",
        "Lexical" : "good morning",
        "ITN" : "good morning",
        "MaskedITN" : "good morning",
        "Display" : "Good morning.",
        "PronScore" : 84.4,
        "AccuracyScore" : 100.0,
        "FluencyScore" : 74.0,
        "CompletenessScore" : 100.0,
        "Words": [
            {
              "Word" : "Good",
              "AccuracyScore" : 100.0,
              "ErrorType" : "None",
              "Offset" : 500000,
              "Duration" : 2700000
            },
            {
              "Word" : "morning",
              "AccuracyScore" : 100.0,
              "ErrorType" : "None",
              "Offset" : 5300000,
              "Duration" : 900000
            }
        ]
      }
  ]
}

Properti respons

Hasil disediakan sebagai JSON. Format simple mencakup bidang tingkat atas berikut:

Properti	Deskripsi
`RecognitionStatus`	Status, seperti `Success` untuk keberhasilan pengenalan. Lihat tabel berikutnya.
`DisplayText`	Teks yang dikenali setelah kapitalisasi, tanda baca, normalisasi teks terbalik, dan masking kata-kata kotor. Hanya hadir jika berhasil. Normalisasi teks terbalik adalah konversi teks lisan ke bentuk yang lebih pendek, seperti 200 untuk "dua ratus" ataupun "Dr. Smith" untuk "dokter smith."
`Offset`	Waktu (dalam unit 100 nanodetik) saat ucapan yang dikenali dimulai dalam aliran audio.
`Duration`	Durasi (dalam unit 100-nanodetik) ucapan yang dikenali dalam aliran audio.

Bidang RecognitionStatus bisa berisi nilai berikut:

Keadaan	Deskripsi
`Success`	Pengenalan berhasil, dan bidang `DisplayText` ada.
`NoMatch`	Ucapan terdeteksi di aliran audio, tetapi tidak ada kata dari bahasa target yang cocok. Status ini biasanya berarti bahwa bahasa pengenalan berbeda dari bahasa yang diucapkan pengguna.
`InitialSilenceTimeout`	Awal stream audio hanya berisi keheningan, dan waktu layanan habis saat menunggu ucapan.
`BabbleTimeout`	Awal stream audio hanya berisi kebisingan, dan waktu layanan habis saat menunggu ucapan.
`Error`	Layanan pengenalan mengalami kesalahan internal dan tidak dapat dilanjutkan. Coba lagi jika memungkinkan.

Catatan

Jika audio hanya berisi kata-kata tidak senonoh, dan parameter kueri profanity diatur ke remove, layanan tidak akan mengembalikan hasil ucapan.

Format ini detailed mencakup lebih banyak bentuk hasil yang dikenali. Saat menggunakan format detailed, DisplayText diberikan sebagai Display untuk setiap hasil dalam daftar NBest.

Objek dalam daftar NBest dapat mencakup:

Properti	Deskripsi
`Confidence`	Skor keyakinan entri, dari 0,0 (tidak yakin) hingga 1,0 (sangat yakin).
`Lexical`	Bentuk leksikal dari teks yang dikenali: kata-kata aktual yang dikenali.
`ITN`	Inverse-text-normalized (ITN) atau bentuk kanonik dari teks yang dikenali, dengan nomor telepon, angka, singkatan ("dokter smith" menjadi "dr smith"), dan transformasi lainnya diterapkan.
`MaskedITN`	Formulir ITN dengan penyembunyian kata-kata kotor diterapkan, jika diminta.
`Display`	Bentuk tampilan teks yang dikenali, dengan tanda baca dan penggunaan huruf besar/kecil ditambahkan. Parameter ini sama dengan yang disediakan `DisplayText` saat format diatur ke `simple`.
`AccuracyScore`	Akurasi pelafalan ucapan. Akurasi menunjukkan seberapa dekat fonem cocok dengan pengucapan penutur asli. Skor akurasi pada tingkat kata dan teks lengkap diagregasi dari skor akurasi di tingkat fonem.
`FluencyScore`	Kefasihan ucapan yang diberikan. Kefasihan menunjukkan seberapa dekat ucapan cocok dengan penggunaan jeda diam di antara kata-kata penutur asli.
`CompletenessScore`	Kelengkapan ucapan, ditentukan dengan menghitung rasio kata yang diucapkan dengan input teks referensi.
`PronScore`	Skor keseluruhan yang menunjukkan kualitas pengucapan dari ucapan yang diberikan. Skor ini diagregasi dari `AccuracyScore`, `FluencyScore`, dan `CompletenessScore` dengan bobot.
`ErrorType`	Nilai yang menunjukkan apakah kata dihilangkan, disisipkan, atau diucapkan dengan buruk, dibandingkan dengan `ReferenceText`. Nilai yang mungkin adalah `None` (artinya tidak ada kesalahan pada kata ini), `Omission`, `Insertion`, dan `Mispronunciation`.

Transfer terpotong

Transfer terpotong (Transfer-Encoding: chunked) dapat membantu mengurangi latensi pengenalan. Ini memungkinkan layanan Ucapan untuk mulai memproses file audio saat sedang ditransmisikan. REST API untuk audio pendek tidak memberikan hasil parsial atau sementara.

Sampel kode berikut menunjukkan cara mengirim audio dalam potongan. Hanya potongan pertama yang harus berisi header file audio. request adalah objek HttpWebRequest yang tersambung ke titik akhir REST yang sesuai. audioFile adalah jalur ke file audio di disk.

var request = (HttpWebRequest)HttpWebRequest.Create(requestUri);
request.SendChunked = true;
request.Accept = @"application/json;text/xml";
request.Method = "POST";
request.ProtocolVersion = HttpVersion.Version11;
request.Host = host;
request.ContentType = @"audio/wav; codecs=audio/pcm; samplerate=16000";
request.Headers["Ocp-Apim-Subscription-Key"] = "YOUR_RESOURCE_KEY";
request.AllowWriteStreamBuffering = false;

using (var fs = new FileStream(audioFile, FileMode.Open, FileAccess.Read))
{
    // Open a request stream and write 1,024-byte chunks in the stream one at a time.
    byte[] buffer = null;
    int bytesRead = 0;
    using (var requestStream = request.GetRequestStream())
    {
        // Read 1,024 raw bytes from the input audio file.
        buffer = new Byte[checked((uint)Math.Min(1024, (int)fs.Length))];
        while ((bytesRead = fs.Read(buffer, 0, buffer.Length)) != 0)
        {
            requestStream.Write(buffer, 0, bytesRead);
        }

        requestStream.Flush();
    }
}

Autentikasi

Setiap permintaan memerlukan header otorisasi. Tabel ini mengilustrasikan header mana yang didukung untuk setiap fitur:

Header otorisasi yang didukung	Ucapan ke Teks	Teks ke ucapan
`Ocp-Apim-Subscription-Key`	Ya	Ya
`Authorization: Bearer`	Ya	Ya

Saat Anda menggunakan Ocp-Apim-Subscription-Key header , Anda hanya diharuskan untuk memberikan kunci sumber daya Anda. Misalnya:

'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'

Saat menggunakan header Authorization: Bearer, Anda diharuskan untuk membuat permintaan ke titik akhir issueToken. Dalam permintaan ini, Anda menukar kunci sumber daya dengan token akses yang berlaku selama 10 menit.

Cara mendapatkan token akses

Untuk mendapatkan token akses, Anda perlu membuat permintaan ke issueToken titik akhir dengan menggunakan Ocp-Apim-Subscription-Key dan kunci sumber daya Anda.

Titik akhir issueToken memiliki format ini:

https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken

Ganti <REGION_IDENTIFIER> dengan pengidentifikasi yang cocok dengan wilayah langganan Anda.

Gunakan sampel berikut untuk membuat permintaan token akses Anda.

Sampel HTTP

Contoh ini adalah permintaan HTTP sederhana untuk mendapatkan token. Ganti YOUR_SUBSCRIPTION_KEY dengan kunci sumber daya Anda untuk layanan Ucapan. Jika langganan Anda tidak berada di wilayah US Barat, ganti header Host dengan nama host wilayah Anda.

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: eastus.api.cognitive.microsoft.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0

Isi respons berisi token akses dalam format JSON Web Token (JWT).

Sampel PowerShell

Contoh ini adalah skrip PowerShell sederhana untuk mendapatkan token akses. Ganti YOUR_SUBSCRIPTION_KEY dengan kunci sumber daya Anda untuk layanan Ucapan. Pastikan untuk menggunakan titik akhir yang benar untuk wilayah yang cocok dengan langganan Anda. Contoh ini saat ini diatur ke US Barat.

$FetchTokenHeader = @{
  'Content-type'='application/x-www-form-urlencoded';
  'Content-Length'= '0';
  'Ocp-Apim-Subscription-Key' = 'YOUR_SUBSCRIPTION_KEY'
}

$OAuthToken = Invoke-RestMethod -Method POST -Uri https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken
 -Headers $FetchTokenHeader

# show the token received
$OAuthToken

Sampel cURL

cURL adalah alat baris perintah yang tersedia di Linux (dan di Subsistem Windows untuk Linux). Perintah cURL ini menggambarkan cara mendapatkan token akses. Ganti YOUR_SUBSCRIPTION_KEY dengan kunci sumber daya Anda untuk layanan Ucapan. Pastikan untuk menggunakan titik akhir yang benar untuk wilayah yang cocok dengan langganan Anda. Contoh ini saat ini diatur ke US Barat.

curl -v -X POST \
 "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
 -H "Content-type: application/x-www-form-urlencoded" \
 -H "Content-Length: 0" \
 -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

Sampel C#

Kelas C# ini menggambarkan cara mendapatkan token akses. Teruskan kunci sumber daya Anda untuk layanan Ucapan saat Anda membuat instans kelas. Jika langganan Anda tidak berada di wilayah US Barat, ubah nilai FetchTokenUri agar cocok dengan wilayah untuk langganan Anda.

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken";
    private string subscriptionKey;
    private string token;

    public Authentication(string subscriptionKey)
    {
        this.subscriptionKey = subscriptionKey;
        this.token = FetchTokenAsync(FetchTokenUri, subscriptionKey).Result;
    }

    public string GetAccessToken()
    {
        return this.token;
    }

    private async Task<string> FetchTokenAsync(string fetchUri, string subscriptionKey)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
            UriBuilder uriBuilder = new UriBuilder(fetchUri);

            var result = await client.PostAsync(uriBuilder.Uri.AbsoluteUri, null);
            Console.WriteLine("Token Uri: {0}", uriBuilder.Uri.AbsoluteUri);
            return await result.Content.ReadAsStringAsync();
        }
    }
}

Sampel Python

# Request module must be installed.
# Run pip install requests if necessary.
import requests

subscription_key = 'REPLACE_WITH_YOUR_KEY'


def get_token(subscription_key):
    fetch_token_url = 'https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken'
    headers = {
        'Ocp-Apim-Subscription-Key': subscription_key
    }
    response = requests.post(fetch_token_url, headers=headers)
    access_token = str(response.text)
    print(access_token)

Cara menggunakan token akses

Token akses harus dikirim ke layanan sebagai header Authorization: Bearer <TOKEN>. Setiap token akses berlaku selama 10 menit. Anda bisa mendapatkan token baru kapan saja, tetapi, untuk meminimalkan lalu lintas dan latensi jaringan, sebaiknya gunakan token yang sama selama sembilan menit.

Berikut adalah contoh permintaan HTTP ke REST API Ucapan ke teks untuk audio pendek:

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: westus.stt.speech.microsoft.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

REST API ucapan ke teks untuk audio pendek

Wilayah dan titik akhir

Format audio

Header permintaan

Parameter kueri

Parameter penilaian pengucapan

Permintaan sampel

Kode status HTTP

Respons sampel

Properti respons

Transfer terpotong

Autentikasi

Cara mendapatkan token akses

Sampel HTTP

Sampel PowerShell

Sampel cURL

Sampel C#

Sampel Python

Cara menggunakan token akses

Langkah berikutnya

Sumber Daya Tambahan: