Metin okuma için toplu sentez API'si

Makale
09/12/2024

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.

Batch Synthesis API iş akışının diyagramı.

İ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çinde synthesisConfigde ayarlamanız voice gerekir. Aşağıdaki örnekte , inputKind "SSML" olarak ayarlanmıştır, dolayısıyla synthesisConfig ayarı ayarlanmadı.
İsteğe bağlı olarak , timeToLiveInHoursve diğer özellikleri ayarlayabilirsinizdescription. Daha fazla bilgi için bkz . toplu sentez özellikleri.

Not

Kabul edilen maksimum JSON yükü boyutu 2 megabayttır.

Yolda gerekli YourSynthesisId değerini ayarlayın. YourSynthesisId benzersiz 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 Succeeded NotStarted 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"
}

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. Toplu sentez GET 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. öğesini toplu sentez GET 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 Oluşturuldu, 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:

outputFormat desteklenmiyor veya geçersiz. Geçerli bir biçim değeri sağlayın veya varsayılan ayarı kullanmak için boş bırakın outputFormat .
İ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.

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."
  }
}

Aracılığıyla paylaş

Metin okuma için toplu sentez API'si

Toplu sentez oluşturma

Toplu sentez alma

Toplu iş sentezi listeleme

Toplu sentezi silme

Toplu sentez sonuçları

Toplu sentez gecikme süresi ve en iyi yöntemler

Toplu sentezde gecikme süresi

En iyi yöntemler

HTTP durum kodu

HTTP 200 Tamam

HTTP 201 Oluşturuldu

HTTP 204 hatası

HTTP 400 hatası

HTTP 404 hatası

HTTP 429 hatası

HTTP 500 hatası

HTTP hata örneği

Sonraki adımlar

Geri Bildirim

Ek kaynaklar