Metin okuma için toplu sentez API'si
Batch sentez API'si, büyük miktarda metin girişini (uzun ve kısa) zaman uyumsuz olarak sentezleyebilir. Yayımcılar ve ses içeriği platformları toplu olarak uzun ses içeriği oluşturabilir. Örneğin: sesli kitaplar, haber makaleleri ve belgeler. Toplu sentez API'si 10 dakikadan daha uzun bir şekilde sentezlenmiş ses oluşturabilir.
Önemli
Batch sentez API'sini genel olarak kullanabilirsiniz. Uzun Ses API'si 1 Nisan 2027'de kullanımdan kaldırılacaktır. Daha fazla bilgi için bkz . Toplu sentez API'sine geçiş.
Toplu sentez API'si zaman uyumsuzdur ve sentezlenmiş sesi gerçek zamanlı olarak döndürmez. Sentezlenecek metin dosyalarını gönderir, durumu yoklar ve durum başarılı olduğunda ses çıkışını indirirsiniz. Metin girişleri düz metin veya Konuşma Sentezi Biçimlendirme Dili (SSML) metni olmalıdır.
Bu diyagram, iş akışına üst düzey bir genel bakış sağlar.
İpucu
Konuşma SDK'sını, metin üzerinde yineleme yaparak ve öbekler halinde sentezleyerek 10 dakikadan uzun bir şekilde sentezlenmiş ses oluşturmak için de kullanabilirsiniz. C# örneği için bkz . GitHub.
Toplu sentez için aşağıdaki REST API işlemlerini kullanabilirsiniz:
| İşlem | Method | REST API çağrısı |
|---|---|---|
| Toplu sentez oluşturma | PUT |
texttospeech/batchsyntheses/YourSynthesisId |
| Toplu sentez alma | GET |
texttospeech/batchsyntheses/YourSynthesisId |
| Toplu iş sentezi listeleme | GET |
texttospeech/batchsyntheses |
| Toplu sentezi silme | DELETE |
texttospeech/batchsyntheses/YourSynthesisId |
Kod örnekleri için bkz . GitHub.
Toplu sentez oluşturma
Toplu sentez isteği göndermek için HTTP PUT istek yolunu ve gövdesini aşağıdaki yönergelere göre oluşturun:
- Gerekli
inputKindözelliği ayarlayın. inputKindÖzelliği "PlainText" olarak ayarlandıysa, özelliğini içindesynthesisConfigde ayarlamanızvoicegerekir. Aşağıdaki örnekte ,inputKind"SSML" olarak ayarlanmıştır, dolayısıylasynthesisConfigayarı ayarlanmadı.- İsteğe bağlı olarak ,
timeToLiveInHoursve diğer özellikleri ayarlayabilirsinizdescription. Daha fazla bilgi için bkz . toplu sentez özellikleri.
Not
Kabul edilecek maksimum JSON yükü boyutu 2 megabayttır.
Yolda gerekli YourSynthesisId değerini ayarlayın. benzersiz YourSynthesisId olmalıdır. 3-64 uzunluğunda olmalı, yalnızca sayı, harf, kısa çizgi, alt çizgi ve nokta içermelidir, bir harf veya sayı ile başlayıp bitmelidir.
Aşağıdaki örnekte gösterildiği gibi URI kullanarak bir HTTP PUT isteği oluşturun. değerini Konuşma kaynak anahtarınız ile değiştirin YourSpeechKey , değerini Konuşma kaynağı bölgenizle değiştirin YourSpeechRegion ve istek gövdesi özelliklerini daha önce açıklandığı gibi ayarlayın.
curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
"description": "my ssml test",
"inputKind": "SSML",
"inputs": [
{
"content": "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
}
],
"properties": {
"outputFormat": "riff-24khz-16bit-mono-pcm",
"wordBoundaryEnabled": false,
"sentenceBoundaryEnabled": false,
"concatenateResult": false,
"decompressOutputFiles": false
}
}' "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"
Aşağıdaki biçimde bir yanıt gövdesi almanız gerekir:
{
"id": "YourSynthesisId",
"internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
"status": "NotStarted",
"createdDateTime": "2024-03-12T07:23:18.0097387Z",
"lastActionDateTime": "2024-03-12T07:23:18.0097388Z",
"inputKind": "SSML",
"customVoices": {},
"properties": {
"timeToLiveInHours": 744,
"outputFormat": "riff-24khz-16bit-mono-pcm",
"concatenateResult": false,
"decompressOutputFiles": false,
"wordBoundaryEnabled": false,
"sentenceBoundaryEnabled": false
}
}
Özelliğin status durum, Running, ve son olarak veya Failedolarak ilerlemesi SucceededNotStarted gerekir. Döndürülen durum Succeeded veya Failedolana kadar GET toplu sentez API'sini düzenli aralıklarla çağırabilirsiniz.
Toplu sentez alma
Toplu sentez işinin durumunu almak için aşağıdaki örnekte gösterildiği gibi URI'yi kullanarak bir HTTP GET isteği oluşturun. değerini YourSpeechKey Konuşma kaynak anahtarınızla, değerini de Konuşma kaynak bölgenizle değiştirin YourSpeechRegion .
curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
Aşağıdaki biçimde bir yanıt gövdesi almanız gerekir:
{
"id": "YourSynthesisId",
"internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
"status": "Succeeded",
"createdDateTime": "2024-03-12T07:23:18.0097387Z",
"lastActionDateTime": "2024-03-12T07:23:18.7979669",
"inputKind": "SSML",
"customVoices": {},
"properties": {
"timeToLiveInHours": 744,
"outputFormat": "riff-24khz-16bit-mono-pcm",
"concatenateResult": false,
"decompressOutputFiles": false,
"wordBoundaryEnabled": false,
"sentenceBoundaryEnabled": false,
"sizeInBytes": 120000,
"succeededAudioCount": 1,
"failedAudioCount": 0,
"durationInMilliseconds": 2500,
"billingDetails": {
"neuralCharacters": 29
}
},
"outputs": {
"result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/YourSynthesisId/results.zip?SAS_Token"
}
}
adresinden outputs.result, sesi (örneğin 0001.wav), özetini ve hata ayıklama ayrıntılarını içeren bir ZIP dosyasını indirebilirsiniz. Daha fazla bilgi için bkz . toplu sentez sonuçları.
Toplu iş sentezi listeleme
Konuşma kaynağının tüm toplu sentez işlerini listelemek için, aşağıdaki örnekte gösterildiği gibi URI'yi kullanarak bir HTTP GET isteği oluşturun. değerini YourSpeechKey Konuşma kaynak anahtarınızla, değerini de Konuşma kaynağı bölgenizle değiştirin YourSpeechRegion . İsteğe bağlı olarak, URL'de skip ve maxpagesize (en fazla 100) sorgu parametresi ayarlayabilirsiniz. için skip varsayılan değer 0 ve için maxpagesize varsayılan değer 100'dür.
curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?api-version=2024-04-01&skip=1&maxpagesize=2" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
Aşağıdaki biçimde bir yanıt gövdesi almanız gerekir:
{
"value": [
{
"id": "my-job-03",
"internalId": "5f7e9ab6-2c92-4dcb-b5ee-ec0983ee4db0",
"status": "Succeeded",
"createdDateTime": "2024-03-12T07:28:32.5690441Z",
"lastActionDateTime": "2024-03-12T07:28:33.0042293",
"inputKind": "SSML",
"customVoices": {},
"properties": {
"timeToLiveInHours": 744,
"outputFormat": "riff-24khz-16bit-mono-pcm",
"concatenateResult": false,
"decompressOutputFiles": false,
"wordBoundaryEnabled": false,
"sentenceBoundaryEnabled": false,
"sizeInBytes": 120000,
"succeededAudioCount": 1,
"failedAudioCount": 0,
"durationInMilliseconds": 2500,
"billingDetails": {
"neuralCharacters": 29
}
},
"outputs": {
"result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-03/results.zip?SAS_Token"
}
},
{
"id": "my-job-02",
"internalId": "5577585f-4710-4d4f-aab6-162d14bd7ee0",
"status": "Succeeded",
"createdDateTime": "2024-03-12T07:28:29.6418211Z",
"lastActionDateTime": "2024-03-12T07:28:30.0910306",
"inputKind": "SSML",
"customVoices": {},
"properties": {
"timeToLiveInHours": 744,
"outputFormat": "riff-24khz-16bit-mono-pcm",
"concatenateResult": false,
"decompressOutputFiles": false,
"wordBoundaryEnabled": false,
"sentenceBoundaryEnabled": false,
"sizeInBytes": 120000,
"succeededAudioCount": 1,
"failedAudioCount": 0,
"durationInMilliseconds": 2500,
"billingDetails": {
"neuralCharacters": 29
}
},
"outputs": {
"result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-02/results.zip?SAS_Token"
}
}
],
"nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?skip=3&maxpagesize=2&api-version=2024-04-01"
}
adresinden outputs.result, sesi (örneğin 0001.wav), özetini ve hata ayıklama ayrıntılarını içeren bir ZIP dosyasını indirebilirsiniz. Daha fazla bilgi için bkz . toplu sentez sonuçları.
value json yanıtında özelliği, sentez isteklerinizi listeler. Liste sayfalandırılmıştır ve sayfa boyutu en fazla 100'dür. "nextLink" Özelliği, sayfalandırılmış listenin sonraki sayfasını almak için gerektiği şekilde sağlanır.
Toplu sentezi silme
Ses çıkış sonuçlarını aldıktan sonra toplu sentez iş geçmişini silin. Konuşma hizmeti toplu sentez geçmişini 31 güne kadar veya istek timeToLiveInHours özelliğinin süresini (hangisi daha erken gelirse) tutar. Otomatik silme tarihi ve saati ("Başarılı" veya "Başarısız" durumundaki sentez işleri için) özelliklere lastActionDateTime + timeToLiveInHours eşittir.
Toplu sentez işini silmek için, aşağıdaki örnekte gösterildiği gibi URI'yi kullanarak bir HTTP DELETE isteği oluşturun. öğesini YourSynthesisId toplu sentez kimliğiniz ile değiştirin, yerine YourSpeechKey Konuşma kaynak anahtarınızı yazın ve yerine Konuşma kaynak bölgenizi yazın YourSpeechRegion .
curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
Yanıt üst bilgileri, silme isteğinin başarılı olup olmadığını içerir HTTP/1.1 204 No Content .
Toplu sentez sonuçları
"Başarılı" ile status toplu sentez işi aldıktan sonra ses çıkış sonuçlarını indirebilirsiniz. Get batch synthesis yanıtının özelliğinden URL'yi outputs.result kullanın.
Toplu sentez sonuçları dosyasını almak için, aşağıdaki örnekte gösterildiği gibi URI'yi kullanarak bir HTTP GET isteği oluşturun. değerini get batch synthesis yanıtının özelliğindeki outputs.result URL ile değiştirinYourOutputsResultUrl. değerini Konuşma kaynak anahtarınız ile değiştirin YourSpeechKey .
curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > results.zip
Sonuçlar, sesi (örneğin 0001.wav), özetini ve hata ayıklama ayrıntılarını içeren bir ZIP dosyasında bulunur. Her dosya adının numaralandırılmış ön eki (aşağıda gösterilmiştir [nnnn]) toplu sentezi oluştururken kullanılan metin girişleriyle aynı sıradadır.
Not
Dosya, [nnnn].debug.json sentez sonuç kimliğini ve sorun gidermeye yardımcı olabilecek diğer bilgileri içerir. İçeren özellikler değişebilir, bu nedenle JSON biçiminde herhangi bir bağımlılık almamalısınız.
Özet dosyası, her metin girişi için sentez sonuçlarını içerir. Örnek bir summary.json dosya aşağıda verilmişti:
{
"jobID": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
"status": "Succeeded",
"results": [
{
"contents": [
"<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
],
"status": "Succeeded",
"audioFileName": "0001.wav",
"properties": {
"sizeInBytes": "120000",
"durationInMilliseconds": "2500"
}
}
]
}
Cümle sınırı verileri istendiyse ("sentenceBoundaryEnabled": true ), sonuçlara karşılık gelen [nnnn].sentence.json bir dosya eklenir. Benzer şekilde, sözcük sınırı verileri istendiyse ("wordBoundaryEnabled": true ), sonuçlara karşılık gelen [nnnn].word.json bir dosya eklenir.
Burada, milisaniye cinsinden hem ses uzaklığı hem de süresi olan örnek bir sözcük veri dosyası verilmiştir:
[
{
"Text": "The",
"AudioOffset": 50,
"Duration": 137
},
{
"Text": "rainbow",
"AudioOffset": 200,
"Duration": 350
},
{
"Text": "has",
"AudioOffset": 562,
"Duration": 175
},
{
"Text": "seven",
"AudioOffset": 750,
"Duration": 300
},
{
"Text": "colors",
"AudioOffset": 1062,
"Duration": 625
},
{
"Text": ".",
"AudioOffset": 1700,
"Duration": 100
}
]
Toplu sentez gecikme süresi ve en iyi yöntemler
Sentezlenmiş konuşma oluşturmak için toplu sentez kullanılırken, söz konusu gecikme süresini göz önünde bulundurmak ve en iyi sonuçları elde etmek için en iyi yöntemleri izlemek önemlidir.
Toplu sentezde gecikme süresi
Toplu sentezdeki gecikme süresi, giriş metninin karmaşıklığı, toplu işlemdeki girişlerin sayısı ve temel alınan donanımın işleme özellikleri gibi çeşitli faktörlere bağlıdır.
Toplu sentez için gecikme süresi aşağıdaki gibidir (yaklaşık):
Sentezlenen konuşma çıkışlarının %50'sinin gecikme süresi 10-20 saniye arasındadır.
Sentezlenen konuşma çıkışlarının %95'inin gecikme süresi 120 saniye içindedir.
En iyi yöntemler
Uygulamanız için toplu sentezi göz önünde bulundururken gecikme süresinin gereksinimlerinizi karşılayıp karşılamadığını değerlendirmeniz önerilir. Gecikme süresi istediğiniz performansla uyumluysa, toplu sentez uygun bir seçim olabilir. Ancak gecikme süresi gereksinimlerinizi karşılamıyorsa gerçek zamanlı API kullanmayı düşünebilirsiniz.
HTTP durum kodu
bölümünde toplu sentez API'sinden http yanıt kodları ve iletileri ayrıntılı olarak verilmiştir.
HTTP 200 Tamam
HTTP 200 Tamam, isteğin başarılı olduğunu gösterir.
HTTP 201 Oluşturuldu
HTTP 201 Created, toplu sentez oluşturma isteğinin (HTTP PUT aracılığıyla) başarılı olduğunu gösterir.
HTTP 204 hatası
HTTP 204 hatası isteğin başarılı olduğunu ancak kaynağın mevcut olmadığını gösterir. Örneğin:
- Var olmayan bir sentez işini almaya veya silmeye çalıştınız.
- Bir sentez işini başarıyla sildiyseniz.
HTTP 400 hatası
Aşağıda 400 hatasına neden olabilecek örnekler verilmiştir:
outputFormatdesteklenmiyor veya geçersiz. Geçerli bir biçim değeri sağlayın veya varsayılan ayarı kullanmak için boş bırakınoutputFormat.- İstenen metin girişi sayısı 10.000 sınırını aştı.
- Geçersiz bir dağıtım kimliği veya başarıyla dağıtılmayan özel bir ses kullanmayı denediniz. Konuşma kaynağının özel sese erişimi olduğundan ve özel sesin başarıyla dağıtıldığından emin olun. Toplu sentez isteğinizde eşlemesinin
{"your-custom-voice-name": "your-deployment-ID"}doğru olduğundan da emin olmanız gerekir. - F0 Konuşma kaynağını kullanmayı denediniz, ancak bölge yalnızca Standart Konuşma kaynağı fiyatlandırma katmanını destekliyor.
- 300 etkin iş sınırını aşacak yeni bir toplu sentez işi oluşturmayı denediniz. Her Konuşma kaynağının "Başarılı" veya "Başarısız" durumuna sahip olmayan en fazla 300 toplu sentez işi olabilir.
HTTP 404 hatası
Belirtilen varlık bulunamıyor. Sentez kimliğinin doğru olduğundan emin olun.
HTTP 429 hatası
Çok fazla son istek var. Her istemci uygulaması, her Konuşma kaynağı için 10 saniye başına en fazla 100 istek gönderebilir. Saniye başına istek sayısını azaltın.
HTTP 500 hatası
HTTP 500 İç Sunucu Hatası, isteğin başarısız olduğunu gösterir. Yanıt gövdesi hata iletisini içerir.
HTTP hata örneği
burada bir http 400 hatasına neden olan örnek bir istek verilmiştir, çünkü inputs özellik bir iş oluşturmak için gereklidir.
curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
"inputKind": "SSML"
}' "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"
Bu durumda, yanıt üst bilgileri içerir HTTP/1.1 400 Bad Request.
Yanıt gövdesi aşağıdaki JSON örneğine benzer:
{
"error": {
"code": "BadRequest",
"message": "The inputs is required."
}
}