Verkkosivulukijan rajapinnan dokumentaatio

Verkkosivulukijan rajapintakutsuja käytetään tekstin lukemiseen lause kerrallaan. Lukeminen koostuu kahdesta eri API-kutsusta:

  1. /text-kutsulla lähetetään API:lle koko luettava teksti, esimerkiksi artikkelin tekstisisältö. Kutsu palauttaa listan ID-arvoja, jossa yksi ID vastaa yhtä lausetta.
  2. /sentence-kutsulla haetaan audio yhdelle lauseelle. Kutsulle lähetetään yksi /text-kutsun palauttamista ID-arvoista, ja kutsu palauttaa lausetta vastaavan audion.

/text-kutsu

HTTP-pyyntö

POST https://api.aimater.com/tts/v2/reader/text

Pyynnön runko

{
    "lang": string,
    "text": Array<string>,
    "auth": {
        "key": string
    }
}

Kentät

  • lang: Syötetyn tekstin kieli. Vaihtoehdot fi, sv-fi ja en. Puuttuessa oletetaan fi.
  • text: Lista teksteistä, jotka halutaan lukijan lukevan ääneen.
    • Tekstit voivat olla esimerkiksi verkkosivun elementeistä parsitut tekstisisällöt: ['OTSIKKO', 'Ensimmäisen kappaleen teksti.', ...].
    • Vaihtoehtoisesti kaikki tekstisisältö voi olla samassa alkiossa: ['OTSIKKO. Ensimmäisen kappaleen teksti. ...'].
  • auth:
    • key: Pakollinen rajapinnan todentamisavain.

Vastauksen runko

Jos pyyntö on onnistunut, vastauksen runko sisältää listan objekteja. Jokainen objekti vastaa yhtä lausetta alkuperäisessä /text-kutsun tekstissä.

[
    {
        "estimated_audio_duration": number,
        "text": string,
        "uuid": string
    },
    ...
]

Objektin kentät

  • text: Lauseen teksti.
  • uuid: Lausetta vastaavan audion yksilöllinen ID-arvo. Jos täysin sama lause esiintyy artikkelissa kaksi kertaa, on näillä objekteilla sama uuid-arvo.
  • (experimental) estimated_audio_duration: Audion arvioitu kesto sekunneissa.

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.
    • Esimerkkejä:
      • invalid-api-key: API-avain ei ole kelvollinen. Ota yhteys a.i.materiin.
      • access-denied: API-avainta ei ole sallittua käyttää tästä verkko-osoitteesta. Ota yhteys a.i.materiin.
  • status: number
    • Virhepalautuksen HTTP status.
Mahdolliset virheet
errorCode status error
empty-request-body 400 Invalid argument: empty request body.
invalid-language 400 Invalid argument: invalid language given.
invalid-request-body 400 Invalid argument: invalid JSON.
missing-text 400 Invalid argument: No text specified.
invalid-api-key 401 Invalid API key.
access-denied 403 Access denied.

/sentence-kutsu

HTTP-pyyntö

POST https://api.aimater.com/tts/v2/reader/sentence

Pyynnön runko

{
    "uuid": string,
    "auth": {
        "key": string
    }
}

Kentät

  • uuid: ID-arvo audiolle, joka halutaan hakea. Tämä on yksi /text-kutsun palauttamista uuid-arvoista.
  • auth:
    • key: Pakollinen rajapinnan todentamisavain. Sama kuin /text-kutsussa.

Vastauksen runko

Jos pyyntö on onnistunut, vastauksen runko sisältää audion, joka voidaan toistaa käyttäjälle.

{
    "audio": string,
    "text": string,
    "word_timestamps": Array<number>
}

Kentät

  • audio: Lauseen audio base64-koodattuna. Audio voidaan toistaa käyttäjälle.
  • text: Audiota vastaava teksti. Ei välttämättä ole täysin sama kuin /text-kutsussa. Eroa voi olla esimerkiksi isoissa ja pienissä kirjaimissa.
  • word_timestamps: Lista numeroista, jossa jokainen numero vastaa yhtä sanaa tekstissä. Numero kertoo missä vaiheessa audiota sana lausutaan. Arvo on sekunteissa. Tätä voi käyttää esimerkiksi sanojen korostamiseen audiota toistettaessa.

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.
    • Esimerkkejä:
      • invalid-api-key: API-avain ei ole kelvollinen. Ota yhteys a.i.materiin.
      • access-denied: API-avainta ei ole sallittua käyttää tästä verkko-osoitteesta. Ota yhteys a.i.materiin.
  • status: number
    • Virhepalautuksen HTTP status.
Mahdolliset virheet
errorCode status error
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.
missing-uuid 400 No UUID specified.
invalid-api-key 401 Invalid API key.
access-denied 403 Access denied.