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.

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.

Toplu sentez için aşağıdaki REST API işlemlerini kullanabilirsiniz:

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.

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

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

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

Sonraki adımlar

• Konuşma Sentezi biçimlendirme dili (SSML)
• Toplu sentez özellikleri
• Toplu senteze geçiş