TTS-rajapinta

Tämä dokumentti kuvaa a.i.materin TTS-rajapinnan käytön (Text-to-Speech).

Synteesiä varten on olemassa kaksi eri käyttötapaa:

Tavallinen syntetisointi
- Tarkoitettu lyhyempien äänien tuottamiseen. Max 1000 merkkiä.
- Äänidata palautetaan suoraan pyynnön vastauksena.
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.

Pyynnöt

Tavallinen syntetisointi

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

Pyynnön 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.
  - Huom! Ei ole tuettu englannin kielellä.
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.
  - Huom! Ei ole tuettu englannin kielellä.
auth
- key: string
  - Rajapinnan todentamisavain. Puuttuessa tai avaimen ollessa väärä palautetaan HTTP-koodi 401.

Vastauksen runko

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

Vastauksen kentät

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

Virhetilanteet

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

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

Virhepalautuksen 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-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ä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
  }
}

Pyynnön 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
}

Vastauksen kentät

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

Virhetilanteet

Virhetilanteissa vastauksen runko sisältää virhepalautuksen:

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

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

Pyynnön 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

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
}

Vastauksen kentät

audioContent: string
- Äänidata base64-koodattuna.

Virhetilanteet

Virhetilanteissa vastauksen runko on aina JSON:ia, vaikka pyydetty tyyppi olisikin binääri. Jos syntetisointi on yhä kesken tai se on epäonnistunut, vastauksen runko sisältää virhepalautuksen:

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

Virhepalautuksen 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

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

Tuettujen äänten haku

Voit tarvittaessa hakea kaikki tuetut äänet rajapinnasta omalla rajapinta-avaimellasi.

HTTP-pyyntö

GET https://api.aimater.com/tts/v2/voices/<api_key>

Korvaa <api_key> omalla rajapinta-avaimellasi.

Vastauksen runko

{
    "voices": [
        {
            "name": string,
            "languageCode": string,
            "background": string
        },
        ...
    ]
}

Vastauksen kentät

voices
- Lista tuetuista äänistä objekteina.
- Näitä objekteja voi käyttää syntetisointikutsujen voice-kentässä.
- Objekteissa on seuraavat kentät:
  - name: string
    - Äänen nimi.
  - languageCode: string
    - Äänen kielikoodi.
  - background: string | null
    - Äänen taustakuva CSS:n background-attribuuttina.
    - Käytetään esimerkiksi a.i.materin tuotteissa äänten näyttämiseen käyttäjälle.
    - Arvo saattaa muuttua tulevaisuudessa.

Muuta

Yleiset huomiot

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

SSML-syöte

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

Tavallinen tekstin syntetisointi

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ötteen syntetisointi

Syöte

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

Tuloste

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

Eräsynteesin 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äsynteesin valmiin äänidatan hakeminen

Syöte

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

Tuloste

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

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search