Tavallinen syntetisointi

Syntetisoi ääntä ja palauttaa vastaavaan äänidatan suoraan pyynnön vastauksena. Tämä on tarkoitettu lyhyempien näytteiden tuottamiseen.


HTTP-pyyntö

POST https://api.aimater.com/tts/v1/synthesize


Pyynnön runko

Sisältää syntetisoitavan syötetekstin JSON-objektissa.

{
  "input": {
    "text": string,
    "ssml": string
  },
  "inputConfig": {
    "phonemized": boolean
  },
  "voice": {
    "languageCode": string,
    "name": string
  },
  "audioConfig": {
    "audioEncoding": string,
    "speakingRate": number,
    "volumeGainDb": number
  },
  "responseConfig": {
    "responseType": string,
    "includePhonemizedText": boolean
  },
  "auth": {
    "key": string
  }
}

Kentät

  • input Syöte voidaan antaa joko raakatekstinä tai SSML-muodossa.
    • text: string
      • Syntetisoitava raakateksti. Enintään 1000 merkkiä.
    • ssml: string
      • Syöte SSML-muodossa. Enintään 1500 merkkiä. Katso SSML.
  • inputConfig
    • phonemized: boolean
      • Onko syötetty teksti jo valmiiksi fonemisoidussa muodossa. Oletuksena false.
  • voice
    • languageCode: string
      • Syntetisoitavan materiaalin kielikoodi. Vaihtoehdot fi, sv-fi ja en. Oletuksena fi.
    • name: string
      • Jos käytössäsi on räätälöity ääni, voit vaihtaa sen käyttöön antamalla äänen nimen tässä.
  • audioConfig
    • audioEncoding: string
      • Syntetisoidun äänen koodaus. Vaihtoehdot WAV/LINEAR16, MP3 ja RAW (WAV ilman headeriä). Oletuksena WAV.
    • speakingRate: number
      • Syntetisoidun äänen nopeuskerroin väliltä [0.5, 2.0]. Oletuksena 1.0.
    • volumeGainDb: number
      • Syntetisoidun äänen vahvistus desibeleinä. Oletuksena 0.0.
  • responseConfig
    • responseType: string
      • Vastaustyyppi. Vaihtoehdot JSON ja BINARY. Oletuksena JSON.
    • includePhonemizedText: boolean
      • Palautetaanko audion lisäksi tekstin fonemisoitu muoto. Toimii vain, kun responseType on JSON. Oletuksena false.
  • auth
    • key: string
      • Rajapinnan todentamisavain. Puuttuessa tai avaimen ollessa väärä palautetaan HTTP-koodi 401.

Vastauksen runko

Jos pyyntö on onnistunut, vastauksen runko sisältää seuraavasti muotoiltua dataa.

Pyydetty vastaustyyppi vaikuttaa vastauksen runkoon. Vastaustyypin ollessa binääri, on runko suoraan syntetisoitu data.

Jos taas tyyppi on JSON, näyttää runko tältä:

{
  "audioContent": string,
  "phonemizedText": string // Vain jos käytettiin `includePhonemizedText`-parametria.
}

Kentät

  • audioContent: string
    • Äänidata base64-koodattuna.
  • phonemizedText: string
    • Syötetty teksti fonemisoidussa muodossa, josta audio on generoitu.

Virhetilanteet

Virhetilanteissa vastauksen runko sisältää virhepalautuksen:

{
  "error": string,
  "errorCode": string,
  "status": number
}

Kentät

  • error: string
    • Virheviesti, joka kertoo mikä annetuissa parametreissä ei ole sallittua.
  • errorCode: string
    • Virheviestiä vastaava virhekoodi.
  • status: number
    • Virhepalautuksen HTTP status.

Virhetilanteissa vastauksen runko on aina JSON:ia, vaikka pyydetty tyyppi olisikin binääri.

Mahdolliset virheet

errorCode status error
empty-request-body 400 Invalid argument: empty request body.
invalid-audio-encoding 400 Invalid argument: AudioEncoding.
invalid-input 400 Invalid argument: only one of text or ssml allowed.
invalid-language 400 Invalid argument: invalid language given.
invalid-request-body 400 Invalid argument: invalid JSON.
invalid-response-type 400 Invalid argument: responseType must be json or binary.
invalid-speaking-rate 400 Invalid argument: speakingRate has to be between 0.5 and 2.0.
invalid-ssml 400 Invalid argument: ssml field maximum length is 1500 characters.
invalid-text 400 Invalid argument: text field maximum length is 1000 characters.
invalid-voice 400 Invalid argument: The given voice is not allowed.
invalid-volume-gain-db 400 Invalid argument: volumeGainDb must be between -100 and 100.
missing-input 400 Invalid argument: text or ssml must be specified.
invalid-api-key 401 Invalid API key.

Eräsynteesi

Tämä on tarkoitettu pitkien tekstien syntetisointiin. Eräsynteesi tehdään kahdella eri pyynnöllä. Ensimmäisellä pyynnöllä annetaan syntetisoitava teksti, joka aloittaa syntetisoinnin taustalla. Syötteen pituudesta riippuen tässä voi kestää useita minuutteja. Toisella pyynnöllä pyydetään äänidata, kun se on valmistunut.


Eräsynteesin aloitus


HTTP-pyyntö

POST https://api.aimater.com/tts/v1/batch/synthesize


Pyynnön runko

Sisältää syntetisoitavan syötetekstin JSON-objektissa.

{
  "input": {
    "text": string,
    "ssml": string
  },
  "voice": {
    "languageCode": string,
    "name": string
  },
  "audioConfig": {
    "audioEncoding": string,
    "speakingRate": number,
    "volumeGainDb": number
  },
  "responseConfig": {
    "responseType": string
  },
  "auth": {
    "key": string
  }
}

Kentät

  • input Syöte voidaan antaa joko raakatekstinä tai SSML-muodossa.
    • text: string
      • Syntetisoitava raakateksti.
    • ssml: string
      • Syöte SSML-muodossa. Katso SSML.
  • voice
    • languageCode: string
      • Syntetisoitavan materiaalin kielikoodi. Vaihtoehdot fi, sv-fi ja en. Oletuksena fi.
    • name: string
      • Jos käytössäsi on räätälöity ääni, voit vaihtaa sen käyttöön antamalla äänen nimen tässä.
  • audioConfig
    • audioEncoding: string
      • Syntetisoidun äänen koodaus. Vaihtoehdot WAV/LINEAR16, MP3 ja RAW (WAV ilman headeriä). Oletuksena WAV.
    • speakingRate: number
      • Syntetisoidun äänen nopeuskerroin väliltä [0.5, 2.0]. Oletuksena 1.0.
    • volumeGainDb: number
      • Syntetisoidun äänen vahvistus desibeleinä. Oletuksena 0.0.
  • responseConfig
    • responseType: string
      • Vastaustyyppi. Vaihtoehdot JSON ja BINARY. Oletuksena JSON.
  • auth
    • key: string
      • Rajapinnan todentamisavain. Puuttuessa tai avaimen ollessa väärä palautetaan HTTP-koodi 401.

Vastauksen runko

Jos pyyntö on onnistunut, vastauksen runko sisältää seuraavasti muotoiltua JSON-dataa:

{
  "audioId": string
}

Kentät

  • audioId: string
    • UUID-tunniste, jota käyttäen äänidata voidaan hakea.

Virhetilanteet

Virhetilanteissa vastauksen runko sisältää virheviestin:

{
  "error": string,
  "errorCode": string,
  "status": number
}

Kentät

  • error: string
    • Virheviesti, joka kertoo mikä annetuissa parametreissä ei ole sallittua.
  • errorCode: string
    • Virheviestiä vastaava virhekoodi.
  • status: number
    • Virhepalautuksen HTTP status.

Mahdolliset virheet

errorCode status error
empty-request-body 400 Invalid argument: empty request body.
invalid-audio-encoding 400 Invalid argument: AudioEncoding.
invalid-input 400 Invalid argument: only one of text or ssml allowed.
invalid-language 400 Invalid argument: invalid language given.
invalid-request-body 400 Invalid argument: invalid JSON.
invalid-response-type 400 Invalid argument: responseType must be json or binary.
invalid-speaking-rate 400 Invalid argument: speakingRate has to be between 0.5 and 2.0.
invalid-voice 400 Invalid argument: The given voice is not allowed.
invalid-volume-gain-db 400 Invalid argument: volumeGainDb must be between -100 and 100.
missing-input 400 Invalid argument: text or ssml must be specified.
invalid-api-key 401 Invalid API key.

Eräsynteesin valmiin äänidatan hakeminen


HTTP-pyyntö

POST https://api.aimater.com/tts/v1/batch/fetch


Pyynnön runko

Sisältää syntetisoidun äänidataa vastaavan UUID-tunnisteen JSON-objektissa.

{
  "input": {
    "audioId": string
  },
  "auth": {
    "key": string
  }
}

Kentät

  • input
    • audioId: string
      • Vastaava UUID-tunniste, joka on saatu aikaisemmalla pyynnöllä.
  • auth
    • key: string
      • Rajapinnan todentamisavain. Puuttuessa tai avaimen ollessa väärä palautetaan HTTP-koodi 401.

Vastauksen runko

Jos pyyntö on onnistunut, vastauksen runko sisältää seuraavasti muotoiltua dataa.

Pyydetty vastaustyyppi vaikuttaa vastauksen runkoon. Vastaustyypin ollessa binääri, on runko suoraan syntetisoitu data.

Jos taas tyyppi on JSON, näyttää runko tältä:

{
  "audioContent": string
}

Kentät

  • audioContent: string
    • Äänidata base64-koodattuna.

Virhetilanteet

Jos syntetisointi on yhä kesken tai se on epäonnistunut, vastauksen rungossa on tästä virheviesti:

{
  "error": string,
  "errorCode": string,
  "status": number,
  "details": string | null
}

Kentät

  • error: string
    • Virheviesti. Tämä vaihtuu riippuen siitä, onko syntetisointi vielä kesken vai onko se epäonnistunut.
  • errorCode: string
    • Virheviestiä vastaava virhekoodi.
  • status: number
    • Virhepalautuksen HTTP status.
  • details: string | null
    • Saattaa sisältää tarkemman virheenkuvauksen, jos se on saatavilla.

Vastauksen tilakoodeista näkee myös suoraan syntetisoinnin tilan:

  • Valmis: 200
  • Keskeneräinen: 202
  • Epäonnistunut: 400

Virhetilanteissa tai ajon ollessa yhä keskeneräinen vastauksen runko on aina JSON:ia, vaikka pyydetty tyyppi olisikin binääri.

Mahdolliset virheet

errorCode status error
audio-not-ready 202 Audio generation for the given UUID is not ready yet.
audio-generation-failed 400 Audio generation for the given UUID has failed.
empty-request-body 400 Invalid argument: empty request body.
invalid-request-body 400 Invalid argument: invalid JSON.
invalid-uuid 400 Invalid UUID or the UUID is not allowed for the given API key.
invalid-api-key 401 Invalid API key.

SSML

SSML-syötteen tulee olla <speak>-tagien sisällä.

<speak> Testi. </speak>

Tuetut SSML-tagit

Tauko

<break>

Attribuutit: - time - Määirttelee tauon pituuden joko millisekunneissa (ms) tai sekunneissa (s).

Esimerkki:

<speak> Sekunnin tauko. <break time="1s" /> Puolen sekunnin tauko. <break time="500ms" /> </speak>

Esimerkit

Raakateksti

Syöte

{
  "input": {
    "text": "Tämä on testi."
  },
  "voice": {
    "languageCode": "fi"
  },
  "responseConfig": {
    "includePhonemizedText": true
  },
  "auth": {
    "key": "12345678-9abc-def1-2345-6789abcdef12"
  }
}

Tuloste

{
  "audioContent": "UklGRlYHAQBXQVZFZm10IBAAAAABAAEAwF0AAIC7AAACABAAZGF0YTIHAQAAAAAAAAA...",
  "phonemizedText": "Tämä on testi."
}

SSML

Syöte

{
  "input": {
    "ssml": "<speak>Tämä on testi. <break time=\"1s\" /></speak>"
  },
  "voice": {
    "languageCode": "fi"
  },
  "auth": {
    "key": "12345678-9abc-def1-2345-6789abcdef12"
  }
}

Huomiot

  • Virkkeen pituus ei voi ikinä olla yli 1000 merkkiä.

Tuloste

{
  "audioContent": "UklGRlYHAQBXQVZFZm10IBAAAAABAAEAwF0AAIC7AAACABAAZGF0YTIHAQAAAAAAAAA..."
}

Eräsyntetisoinnin aloitus

Syöte

{
  "input": {
    "text": "Tämä on pitkä, monen tuhannen merkin mittainen teksti ...."
  },
  "voice": {
    "languageCode": "fi"
  },
  "auth": {
    "key": "12345678-9abc-def1-2345-6789abcdef12"
  }
}

Tuloste

{
  "audioId": "e8cb3912-543b-43a2-89c5-48b0867c54dd"
}

Eräsyntetisoidun äänen hakeminen

Syöte

{
  "input": {
    "audioId": "e8cb3912-543b-43a2-89c5-48b0867c54dd"
  },
  "auth": {
    "key": "12345678-9abc-def1-2345-6789abcdef12"
  }
}

Tuloste

{
  "audioContent": "UklGRlYHAQBXQVZFZm10IBAAAAABAAEAwF0AAIC7AAACABAAZGF0YTIHAQAAAAAAAAA..."
}