REST API teks ke ucapan
Layanan Azure Cognitive Service untuk Ucapan memungkinkan Anda mengonversi teks menjadi ucapan yang disintesis dan mendapatkan daftar suara yang didukung untuk suatu wilayah menggunakan REST API. Dalam artikel ini, Anda mempelajari tentang opsi otorisasi, opsi kueri, cara menyusun permintaan, dan cara menginterpretasikan respons.
Tip
Kasus penggunaan untuk REST API teks ke ucapan terbatas. Gunakan hanya dalam kasus di mana Anda tidak dapat menggunakan Azure Cognitive Service untuk Ucapan SDK. Misalnya, dengan Speech SDK Anda dapat berlangganan peristiwa untuk wawasan lebih lanjut tentang pemrosesan dan hasil teks ke ucapan.
REST API teks ke ucapan mendukung teks neural ke suara ucapan di banyak lokal. Setiap titik akhir yang tersedia dikaitkan dengan kawasan. Kunci sumber daya Ucapan untuk titik akhir atau wilayah yang Anda rencanakan untuk digunakan diperlukan. Berikut tautan untuk informasi selengkapnya:
- Untuk daftar lengkap suara, lihat Dukungan bahasa dan suara untuk layanan Azure Cognitive Service untuk Ucapan.
- Untuk informasi tentang ketersediaan regional, lihat Wilayah yang didukung layanan Azure Cognitive Service untuk Ucapan.
- Untuk Azure Government dan Microsoft Azure yang dioperasikan oleh titik akhir 21Vianet, lihat artikel tentang sovereign cloud ini.
Penting
Biaya bervariasi untuk suara saraf bawaan (disebut Neural di halaman harga) dan suara neural kustom (disebut Neural Kustom di halaman harga). Untuk informasi selengkapnya, lihat Harga layanan Azure Cognitive Service untuk Ucapan.
Sebelum Anda menggunakan REST API teks ke ucapan, pahami bahwa Anda perlu menyelesaikan pertukaran token sebagai bagian dari autentikasi untuk mengakses layanan. Untuk informasi lebih lanjut, lihat Autentikasi.
Mendapatkan daftar suara
Anda dapat menggunakan tts.speech.microsoft.com/cognitiveservices/voices/list titik akhir untuk mendapatkan daftar lengkap suara untuk wilayah atau titik akhir tertentu. Awali titik akhir daftar suara dengan wilayah untuk mendapatkan daftar suara untuk wilayah tersebut. Misalnya, untuk mendapatkan daftar suara untuk wilayah tersebut westus , gunakan https://westus.tts.speech.microsoft.com/cognitiveservices/voices/list titik akhir. Untuk daftar semua wilayah yang didukung, lihat dokumentasi wilayah .
Catatan
Suara dan gaya dalam pratinjau hanya tersedia di tiga wilayah layanan: US Timur, Eropa Barat, dan Asia Tenggara.
Header permintaan
Tabel ini mencantumkan header yang diperlukan dan opsional untuk permintaan teks ke ucapan:
| Header | Deskripsi | Diperlukan atau opsional |
|---|---|---|
Ocp-Apim-Subscription-Key |
Kunci sumber daya Ucapan Anda. | 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. |
Isi permintaan
Badan tidak diperlukan untuk permintaan GET ke titik akhir ini.
Permintaan sampel
Permintaan ini hanya memerlukan header otorisasi:
GET /cognitiveservices/voices/list HTTP/1.1
Host: westus.tts.speech.microsoft.com
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Berikut adalah contoh perintah curl:
curl --location --request GET 'https://YOUR_RESOURCE_REGION.tts.speech.microsoft.com/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY'
Respon sampel
Anda harus menerima respons dengan isi JSON yang mencakup semua lokal, suara, jenis kelamin, gaya, dan detail lainnya yang didukung. Properti WordsPerMinute untuk setiap suara dapat digunakan untuk memperkirakan panjang ucapan output. Contoh JSON ini menunjukkan hasil parsial untuk mengilustrasikan struktur respons:
[
// Redacted for brevity
{
"Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyNeural)",
"DisplayName": "Jenny",
"LocalName": "Jenny",
"ShortName": "en-US-JennyNeural",
"Gender": "Female",
"Locale": "en-US",
"LocaleName": "English (United States)",
"StyleList": [
"assistant",
"chat",
"customerservice",
"newscast",
"angry",
"cheerful",
"sad",
"excited",
"friendly",
"terrified",
"shouting",
"unfriendly",
"whispering",
"hopeful"
],
"SampleRateHertz": "24000",
"VoiceType": "Neural",
"Status": "GA",
"ExtendedPropertyMap": {
"IsHighQuality48K": "True"
},
"WordsPerMinute": "152"
},
// Redacted for brevity
{
"Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyMultilingualNeural)",
"DisplayName": "Jenny Multilingual",
"LocalName": "Jenny Multilingual",
"ShortName": "en-US-JennyMultilingualNeural",
"Gender": "Female",
"Locale": "en-US",
"LocaleName": "English (United States)",
"SecondaryLocaleList": [
"de-DE",
"en-AU",
"en-CA",
"en-GB",
"es-ES",
"es-MX",
"fr-CA",
"fr-FR",
"it-IT",
"ja-JP",
"ko-KR",
"pt-BR",
"zh-CN"
],
"SampleRateHertz": "24000",
"VoiceType": "Neural",
"Status": "GA",
"WordsPerMinute": "190"
},
// Redacted for brevity
{
"Name": "Microsoft Server Speech Text to Speech Voice (ga-IE, OrlaNeural)",
"DisplayName": "Orla",
"LocalName": "Orla",
"ShortName": "ga-IE-OrlaNeural",
"Gender": "Female",
"Locale": "ga-IE",
"LocaleName": "Irish (Ireland)",
"SampleRateHertz": "24000",
"VoiceType": "Neural",
"Status": "GA",
"WordsPerMinute": "139"
},
// Redacted for brevity
{
"Name": "Microsoft Server Speech Text to Speech Voice (zh-CN, YunxiNeural)",
"DisplayName": "Yunxi",
"LocalName": "云希",
"ShortName": "zh-CN-YunxiNeural",
"Gender": "Male",
"Locale": "zh-CN",
"LocaleName": "Chinese (Mandarin, Simplified)",
"StyleList": [
"narration-relaxed",
"embarrassed",
"fearful",
"cheerful",
"disgruntled",
"serious",
"angry",
"sad",
"depressed",
"chat",
"assistant",
"newscast"
],
"SampleRateHertz": "24000",
"VoiceType": "Neural",
"Status": "GA",
"RolePlayList": [
"Narrator",
"YoungAdultMale",
"Boy"
],
"WordsPerMinute": "293"
},
// Redacted for brevity
]
Kode status HTTP
Kode status HTTP untuk setiap respons menunjukkan keberhasilan atau kesalahan umum.
| Kode status HTTP | Deskripsi | Kemungkinan alasan |
|---|---|---|
| 200 | OK | Permintaan berhasil. |
| 400 | Permintaan Buruk | Parameter yang diperlukan hilang, kosong, atau null. Atau, nilai yang diteruskan ke parameter yang diperlukan atau opsional tidak valid. Masalah umumnya adalah header yang terlalu panjang. |
| 401 | Tidak diizinkan | Permintaan tersebut tidak diotorisasi. Pastikan kunci sumber daya atau token Anda valid dan di wilayah yang benar. |
| 429 | Terlalu banyak permintaan | Anda melebihi kuota atau tingkat permintaan yang diizinkan untuk sumber daya Anda. |
| 502 | Gateway buruk | Ada masalah jaringan atau sisi server. Status ini mungkin juga menunjukkan header yang tidak valid. |
Mengonversi teks menjadi ucapan
Titik akhir cognitiveservices/v1 memungkinkan Anda mengonversi teks ke ucapan menggunakan Speech Synthesis Markup Language (SSML).
Wilayah dan titik akhir
Wilayah ini didukung untuk teks ke ucapan melalui REST API. Pastikan untuk memilih titik akhir yang cocok dengan wilayah sumber daya Ucapan Anda.
Suara neural bawaan
Gunakan tabel ini untuk menentukan ketersediaan suara neural menurut wilayah atau titik akhir:
| Wilayah | Titik akhir |
|---|---|
| Australia Timur | https://australiaeast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Brasil Selatan | https://brazilsouth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Kanada Tengah | https://canadacentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| US Tengah | https://centralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Asia Timur | https://eastasia.tts.speech.microsoft.com/cognitiveservices/v1 |
| AS Timur | https://eastus.tts.speech.microsoft.com/cognitiveservices/v1 |
| AS Timur 2 | https://eastus2.tts.speech.microsoft.com/cognitiveservices/v1 |
| Prancis Tengah | https://francecentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Jerman Barat Tengah | https://germanywestcentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| India Tengah | https://centralindia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Jepang Timur | https://japaneast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Jepang Barat | https://japanwest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Jio India Barat | https://jioindiawest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Korea Tengah | https://koreacentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| US Tengah Utara | https://northcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Eropa Utara | https://northeurope.tts.speech.microsoft.com/cognitiveservices/v1 |
| Norwegia Timur | https://norwayeast.tts.speech.microsoft.com/cognitiveservices/v1 |
| US Tengah Selatan | https://southcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Asia Tenggara | https://southeastasia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Swedia Tengah | https://swedencentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Swiss Utara | https://switzerlandnorth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Swiss Barat | https://switzerlandwest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Arab Saudi Utara | https://uaenorth.tts.speech.microsoft.com/cognitiveservices/v1 |
| US Gov Arizona | https://usgovarizona.tts.speech.azure.us/cognitiveservices/v1 |
| US Gov Virginia | https://usgovvirginia.tts.speech.azure.us/cognitiveservices/v1 |
| UK Selatan | https://uksouth.tts.speech.microsoft.com/cognitiveservices/v1 |
| AS Tengah Bagian Barat | https://westcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Eropa Barat | https://westeurope.tts.speech.microsoft.com/cognitiveservices/v1 |
| US Barat | https://westus.tts.speech.microsoft.com/cognitiveservices/v1 |
| US Barat 2 | https://westus2.tts.speech.microsoft.com/cognitiveservices/v1 |
| AS Barat 3 | https://westus3.tts.speech.microsoft.com/cognitiveservices/v1 |
Tip
Suara dalam pratinjau hanya tersedia di tiga wilayah ini: US Timur, Eropa Barat, dan Asia Tenggara.
Suara neural kustom
Jika Anda telah membuat font suara neural kustom, gunakan titik akhir yang telah Anda buat. Anda juga dapat menggunakan titik akhir berikut. Ganti {deploymentId} dengan ID penyebaran untuk model suara neural Anda.
| Wilayah | Pelatihan | Penyebaran | Titik akhir |
|---|---|---|---|
| Australia Timur | Ya | Ya | https://australiaeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Brasil Selatan | Tidak | Ya | https://brazilsouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Kanada Tengah | Tidak | Ya | https://canadacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| AS Tengah | Tidak | Ya | https://centralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Asia Timur | Tidak | Ya | https://eastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| AS Timur | Ya | Ya | https://eastus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| AS Timur 2 | Ya | Ya | https://eastus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Prancis Tengah | Tidak | Ya | https://francecentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Jerman Barat Tengah | Tidak | Ya | https://germanywestcentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| India Tengah | Ya | Ya | https://centralindia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Jepang Timur | Ya | Ya | https://japaneast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Jepang Barat | Tidak | Ya | https://japanwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Jio India Barat | Tidak | Ya | https://jioindiawest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Korea Tengah | Ya | Ya | https://koreacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| AS Tengah Bagian Utara | Tidak | Ya | https://northcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Eropa Utara | Ya | Ya | https://northeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Norwegia Timur | Tidak | Ya | https://norwayeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Afrika Selatan Utara | Tidak | Ya | https://southafricanorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| US Tengah Selatan | Ya | Ya | https://southcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Asia Tenggara | Ya | Ya | https://southeastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Swiss Utara | Tidak | Ya | https://switzerlandnorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Swiss Barat | Tidak | Ya | https://switzerlandwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Arab Saudi Utara | Tidak | Ya | https://uaenorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| UK Selatan | Ya | Ya | https://uksouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| AS Tengah Bagian Barat | Tidak | Ya | https://westcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Eropa Barat | Ya | Ya | https://westeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| US Barat | Ya | Ya | https://westus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| US Barat 2 | Ya | Ya | https://westus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| AS Barat 3 | Tidak | Ya | https://westus3.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
Catatan
Wilayah sebelumnya tersedia untuk hosting model suara neural dan sintesis real time. Pelatihan suara neural tersedia di beberapa wilayah. Tetapi pengguna dapat dengan mudah menyalin model suara neural dari tiga wilayah ke wilayah lain dalam daftar sebelumnya.
Long Audio API
API Audio Panjang tersedia di beberapa wilayah dengan titik akhir yang unik:
| Wilayah | Titik akhir |
|---|---|
| Australia Timur | https://australiaeast.customvoice.api.speech.microsoft.com |
| AS Timur | https://eastus.customvoice.api.speech.microsoft.com |
| India Tengah | https://centralindia.customvoice.api.speech.microsoft.com |
| US Tengah Selatan | https://southcentralus.customvoice.api.speech.microsoft.com |
| Asia Tenggara | https://southeastasia.customvoice.api.speech.microsoft.com |
| UK Selatan | https://uksouth.customvoice.api.speech.microsoft.com |
| Eropa Barat | https://westeurope.customvoice.api.speech.microsoft.com |
Header permintaan
Tabel ini mencantumkan header yang diperlukan dan opsional untuk permintaan teks ke ucapan:
| Header | Deskripsi | Diperlukan atau opsional |
|---|---|---|
Authorization |
Token otorisasi didahului oleh kata Bearer. Untuk informasi lebih lanjut, lihat Autentikasi. |
Wajib |
Content-Type |
Menentukan jenis konten untuk teks yang disediakan. Nilai yang diterima: application/ssml+xml. |
Wajib |
X-Microsoft-OutputFormat |
Menentukan format keluaran audio. Untuk daftar lengkap nilai yang diterima, lihat Output audio. | Wajib |
User-Agent |
Nama aplikasi. Panjang nilai yang diberikan harus kurang dari 255 karakter. | Wajib |
Isi permintaan
Jika menggunakan suara neural kustom, isi permintaan dapat dikirim sebagai teks biasa (ASCII atau UTF-8). Jika tidak, isi setiap permintaan POST akan dikirim sebagai SSML. SSML memungkinkan Anda memilih suara dan bahasa ucapan yang disintesis yang dikembalikan oleh fitur teks ke ucapan. Untuk mengetahui daftar lengkap suara, lihat Dukungan bahasa dan suara untuk layanan Azure Cognitive Service untuk Ucapan.
Permintaan sampel
Permintaan HTTP ini menggunakan SSML untuk menentukan suara dan bahasa. Jika isi terlalu panjang, dan audio yang dihasilkan melebihi 10 menit, hasilnya akan dipotong menjadi 10 menit. Dengan kata lain, durasi audio tidak boleh melebihi 10 menit.
POST /cognitiveservices/v1 HTTP/1.1
X-Microsoft-OutputFormat: riff-24khz-16bit-mono-pcm
Content-Type: application/ssml+xml
Host: westus.tts.speech.microsoft.com
Content-Length: <Length>
Authorization: Bearer [Base64 access_token]
User-Agent: <Your application name>
<speak version='1.0' xml:lang='en-US'><voice xml:lang='en-US' xml:gender='Male'
name='en-US-ChristopherNeural'>
I'm excited to try text to speech!
</voice></speak>
* Untuk Panjang Konten, Anda harus menggunakan panjang konten Anda sendiri. Dalam kebanyakan kasus, nilai ini dihitung secara otomatis.
Kode status HTTP
Kode status HTTP untuk setiap respons menunjukkan keberhasilan atau kesalahan umum:
| Kode status HTTP | Deskripsi | Kemungkinan alasan |
|---|---|---|
| 200 | OK | Permintaan berhasil. Isi respons merupakan file audio. |
| 400 | Permintaan Buruk | Parameter yang diperlukan hilang, kosong, atau null. Atau, nilai yang diteruskan ke parameter yang diperlukan atau opsional tidak valid. Masalah umumnya adalah header yang terlalu panjang. |
| 401 | Tidak diizinkan | Permintaan tersebut tidak diotorisasi. Pastikan kunci atau token sumber daya Ucapan Anda valid dan di wilayah yang benar. |
| 415 | Jenis Media yang Tidak Didukung | Ada kemungkinan bahwa nilai Content-Type yang salah disediakan. Content-Type harus ditetapkan ke application/ssml+xml. |
| 429 | Terlalu banyak permintaan | Anda melebihi kuota atau tingkat permintaan yang diizinkan untuk sumber daya Anda. |
| 502 | Gateway buruk | Ada masalah jaringan atau sisi server. Status ini mungkin juga menunjukkan header yang tidak valid. |
Jika status HTTP adalah 200 OK, badan respons berisi file audio dalam format yang diminta. File ini bisa diputar seperti yang ditransfer, disimpan ke penyangga, atau disimpan ke sebuah file.
Output audio
Format audio streaming dan nonstreaming yang didukung dikirim di setiap permintaan sebagai X-Microsoft-OutputFormat header. Setiap format menggabungkan bit rate dan jenis pengodean. Layanan Azure Cognitive Service untuk Ucapan mendukung output audio 48 kHz, 24 kHz, 16 kHz dan 8-kHz. Setiap model suara neural bawaan tersedia pada 24kHz dan high-fidelity 48kHz.
amr-wb-16000hz
audio-16khz-16bit-32kbps-mono-opus
audio-16khz-32kbitrate-mono-mp3
audio-16khz-64kbitrate-mono-mp3
audio-16khz-128kbitrate-mono-mp3
audio-24khz-16bit-24kbps-mono-opus
audio-24khz-16bit-48kbps-mono-opus
audio-24khz-48kbitrate-mono-mp3
audio-24khz-96kbitrate-mono-mp3
audio-24khz-160kbitrate-mono-mp3
audio-48khz-96kbitrate-mono-mp3
audio-48khz-192kbitrate-mono-mp3
ogg-16khz-16bit-mono-opus
ogg-24khz-16bit-mono-opus
ogg-48khz-16bit-mono-opus
raw-8khz-8bit-mono-alaw
raw-8khz-8bit-mono-mulaw
raw-8khz-16bit-mono-pcm
raw-16khz-16bit-mono-pcm
raw-16khz-16bit-mono-truesilk
raw-22050hz-16bit-mono-pcm
raw-24khz-16bit-mono-pcm
raw-24khz-16bit-mono-truesilk
raw-44100hz-16bit-mono-pcm
raw-48khz-16bit-mono-pcm
webm-16khz-16bit-mono-opus
webm-24khz-16bit-24kbps-mono-opus
webm-24khz-16bit-mono-opus
Catatan
Jika Anda memilih format output 48kHz, model suara dengan keakuratan tinggi dengan 48kHz akan dipanggil. Laju sampel selain 24kHz dan 48kHz dapat diperoleh melalui upsampling atau downsampling saat mensintesis, misalnya, 44,1kHz diturunkan dari 48kHz.
Jika format suara dan output yang Anda pilih memiliki laju bit yang berbeda, audio akan disampling ulang jika diperlukan. Anda dapat mendekode format ogg-24khz-16bit-mono-opus dengan menggunakan codec Opus.
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, hanya kunci sumber daya Anda yang harus disediakan. Contohnya:
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
Saat menggunakan Authorization: Bearer header, Anda perlu membuat permintaan ke issueToken titik akhir. Dalam permintaan ini, Anda menukar kunci sumber daya dengan token akses yang berlaku selama 10 menit.
Opsi lain adalah menggunakan autentikasi Microsoft Entra yang juga menggunakan Authorization: Bearer header, tetapi dengan token yang dikeluarkan melalui ID Microsoft Entra. Lihat Menggunakan autentikasi Microsoft Entra.
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...
Menggunakan autentikasi Microsoft Entra
Untuk menggunakan autentikasi Microsoft Entra dengan REST API Ucapan ke teks untuk audio pendek, Anda perlu membuat token akses. Langkah-langkah untuk mendapatkan token akses yang terdiri dari ID Sumber Daya dan token akses Microsoft Entra sama seperti saat menggunakan Speech SDK. Ikuti langkah-langkah di sini Menggunakan autentikasi Microsoft Entra
- Membuat sumber daya Ucapan
- Mengonfigurasi sumber daya Ucapan untuk autentikasi Microsoft Entra
- Mendapatkan token akses Microsoft Entra
- Dapatkan ID sumber daya Ucapan
Setelah ID sumber daya dan token akses Microsoft Entra diperoleh, token akses aktual dapat dibangun mengikuti format ini:
aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN
Anda perlu menyertakan awalan "aad#" dan pemisah "#" (hash) antara ID sumber daya dan token akses.
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...
Untuk mempelajari selengkapnya tentang token akses Microsoft Entra, termasuk masa pakai token, kunjungi Token akses di platform identitas Microsoft.