# Amazon Polly

> Turn text into lifelike speech with Amazon Polly: create audio files in dozens of voices and languages, get word timings, run long texts to S3, and manage pronunciation lexicons.

App · Voice AI · 10 actions. Web page: https://docs.lodol.com/docs/integrations/amazon-polly

## Actions

### Delete lexicon

Delete a pronunciation lexicon. There is no undo, and speech that names it will fail until it is recreated.

**Inputs**

- Lexicon (`lexicon_name`, text, required): The lexicon's name (case-sensitive).

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "deleted": true,
    "name": "BrandNames"
  }
}
```

### Get lexicon

Read a lexicon's PLS content and its details.

**Inputs**

- Lexicon (`lexicon_name`, text, required): The lexicon's name (case-sensitive).

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "alphabet": "ipa",
    "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<lexicon version=\"1.0\" xmlns=\"http://www.w3.org/2005/01/pronunciation-lexicon\" alphabet=\"ipa\" xml:lang=\"en-US\">\n  <lexeme><grapheme>Lodol</grapheme><alias>Low doll</alias></lexeme>\n</lexicon>",
    "language_code": "en-US",
    "last_modified_at": "2026-09-28T09:00:00Z",
    "lexemes_count": 1,
    "lexicon_arn": "arn:aws:polly:us-east-1:123456789012:lexicon/BrandNames",
    "name": "BrandNames",
    "size": 262
  }
}
```

### Get speech marks

Find when each sentence, word or mouth shape (viseme) of a text would be spoken, in milliseconds - for captions, highlighting or lip-sync. Run it with the same voice and engine as the audio.

**Inputs**

- Voice (`voice_id`, text, required): The voice to speak in. The list shows each voice's language, gender and the engines it supports; you can also type a voice id such as 'Joanna'.
- Text (`text`, text, required): The same text (or SSML) that was spoken.
- Mark types (`speech_mark_types`, list, required): Which marks to return. SSML marks need SSML text. Generative voices produce none. One or more of: `sentence`, `word`, `viseme`, `ssml` (SSML marks). Default: `["word", "sentence"]`.
- Engine (`engine`, text): Must be one the voice supports (shown in the Voice list). Left empty, Polly uses standard, which neural-only voices refuse. Long-form and generative cost more per character. One of: `standard` (Standard (cheapest, every region)), `neural` (Neural (more natural)), `long-form` (Long-form (us-east-1 only)), `generative` (Generative (most expressive, some regions)). Default: `neural`.
- Text type (`text_type`, text): Plain text, or SSML for pauses, emphasis and pronunciation. Left empty, text that starts with <speak> is read as SSML. One of: `text` (Plain text), `ssml`.
- Language (`language_code`, text): Only for bilingual voices (e.g. Aditi): which of its languages to speak. Leave empty to use the voice's main language.
- Lexicons (`lexicon_names`, list): Pronunciation lexicons to apply, up to 5. Create them with Save lexicon.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "character_count": 23,
    "count": 2,
    "marks": [
      {
        "end": 23,
        "start": 0,
        "time": 0,
        "type": "sentence",
        "value": "Mary had a little lamb."
      },
      {
        "end": 4,
        "start": 0,
        "time": 6,
        "type": "word",
        "value": "Mary"
      }
    ],
    "speech_mark_types": [
      "sentence",
      "word"
    ],
    "voice_id": "Joanna"
  }
}
```

### Get speech synthesis task

Check a synthesis task's status and, once completed, the S3 address of its file. Polly keeps tasks for 72 hours.

**Inputs**

- Task id (`task_id`, text, required): The task_id from Start speech synthesis task (its output URL also works).

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "task": {
      "created_at": "2026-09-28T09:15:02.123000Z",
      "engine": "neural",
      "language_code": null,
      "lexicon_names": [],
      "output_format": "mp3",
      "output_uri": "https://s3.us-east-1.amazonaws.com/my-polly-audio/audio/d8a3f1b2-5c4e-4a7b-9f60-2e1d3c4b5a69.mp3",
      "request_characters": 1840,
      "sample_rate": null,
      "sns_topic_arn": null,
      "speech_mark_types": [],
      "status": "completed",
      "status_reason": null,
      "task_id": "d8a3f1b2-5c4e-4a7b-9f60-2e1d3c4b5a69",
      "text_type": "text",
      "voice_id": "Joanna"
    }
  }
}
```

### List lexicons

List the pronunciation lexicons in the connected region.

**Inputs**: None.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "count": 1,
    "lexicons": [
      {
        "alphabet": "ipa",
        "language_code": "en-US",
        "last_modified_at": "2026-09-28T09:00:00Z",
        "lexemes_count": 1,
        "lexicon_arn": "arn:aws:polly:us-east-1:123456789012:lexicon/BrandNames",
        "name": "BrandNames",
        "size": 262
      }
    ],
    "names": [
      "BrandNames"
    ]
  }
}
```

### List speech synthesis tasks

List the synthesis tasks of the last 72 hours, newest first, optionally only those with one status.

**Inputs**

- Status (`status`, text): Only tasks with this status. One of: `scheduled`, `inProgress` (In progress), `completed`, `failed`.
- Max results (`max_results`, number): How many tasks per page, 1-100. From 1 to 100.
- Next token (`next_token`, text): The 'next_token' from a previous page, to read the next one.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "count": 1,
    "has_more": false,
    "next_token": null,
    "tasks": [
      {
        "created_at": "2026-09-28T09:15:02.123000Z",
        "engine": "neural",
        "language_code": null,
        "lexicon_names": [],
        "output_format": "mp3",
        "output_uri": "https://s3.us-east-1.amazonaws.com/my-polly-audio/audio/d8a3f1b2-5c4e-4a7b-9f60-2e1d3c4b5a69.mp3",
        "request_characters": 1840,
        "sample_rate": null,
        "sns_topic_arn": null,
        "speech_mark_types": [],
        "status": "scheduled",
        "status_reason": null,
        "task_id": "d8a3f1b2-5c4e-4a7b-9f60-2e1d3c4b5a69",
        "text_type": "text",
        "voice_id": "Joanna"
      }
    ]
  }
}
```

### List voices

List the voices available in the connected region, with the language, gender and engines of each. Filter by engine or language to find one that fits.

**Inputs**

- Engine (`engine`, text): Only voices that support this engine. One of: `standard` (Standard (cheapest, every region)), `neural` (Neural (more natural)), `long-form` (Long-form (us-east-1 only)), `generative` (Generative (most expressive, some regions)).
- Language (`language_code`, text): Only voices that speak this language.
- Include bilingual voices (`include_additional_language_codes`, true/false): With a language: also list voices that speak it as a second language.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "count": 1,
    "voice_ids": [
      "Joanna"
    ],
    "voices": [
      {
        "additional_language_codes": [],
        "gender": "Female",
        "id": "Joanna",
        "language_code": "en-US",
        "language_name": "US English",
        "name": "Joanna",
        "supported_engines": [
          "generative",
          "long-form",
          "neural",
          "standard"
        ]
      }
    ]
  }
}
```

### Save lexicon

Create a pronunciation lexicon - how Polly should say names, acronyms or words - or replace the one with the same name. It can take a few seconds before speech uses the new version.

**Inputs**

- Lexicon name (`lexicon_name`, text, required): 1-20 letters and digits, e.g. 'BrandNames'. An existing name is overwritten.
- Lexicon (PLS XML) (`content`, text, required): A W3C PLS document, up to 40,000 characters. Alphabet ipa or x-sampa; each <lexeme> maps a <grapheme> to a <phoneme> or an <alias>.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "name": "BrandNames",
    "saved": true
  }
}
```

### Speak text

Turn text or SSML (up to 3,000 characters) into an audio file. The file is saved and returned as a download link and document, so a later step can play, attach or send it.

**Inputs**

- Voice (`voice_id`, text, required): The voice to speak in. The list shows each voice's language, gender and the engines it supports; you can also type a voice id such as 'Joanna'.
- Text (`text`, text, required): What to say: plain text, or SSML wrapped in <speak>...</speak>. Up to 3,000 billed characters.
- Engine (`engine`, text): Must be one the voice supports (shown in the Voice list). Left empty, Polly uses standard, which neural-only voices refuse. Long-form and generative cost more per character. One of: `standard` (Standard (cheapest, every region)), `neural` (Neural (more natural)), `long-form` (Long-form (us-east-1 only)), `generative` (Generative (most expressive, some regions)). Default: `neural`.
- Audio format (`output_format`, text): The audio file format. Default MP3. One of: `mp3`, `ogg_vorbis` (Ogg Vorbis), `ogg_opus` (Ogg Opus), `pcm` (PCM (raw 16-bit mono, not directly playable)), `mulaw` (mu-law (telephony)), `alaw` (A-law (telephony)). Default: `mp3`.
- Sample rate (`sample_rate`, text): Leave empty for the voice's default. Must suit the audio format. One of: `8000` (8 kHz (pcm, mulaw, alaw, mp3, ogg_vorbis)), `16000` (16 kHz (pcm, mp3, ogg_vorbis)), `22050` (22.05 kHz (mp3, ogg_vorbis; standard default)), `24000` (24 kHz (mp3, ogg_vorbis; neural default)), `44100` (44.1 kHz (mp3, ogg_vorbis; newer, not every voice)), `48000` (48 kHz (ogg_opus; mp3/ogg_vorbis on newer voices)).
- Text type (`text_type`, text): Plain text, or SSML for pauses, emphasis and pronunciation. Left empty, text that starts with <speak> is read as SSML. One of: `text` (Plain text), `ssml`.
- Language (`language_code`, text): Only for bilingual voices (e.g. Aditi): which of its languages to speak. Leave empty to use the voice's main language.
- Lexicons (`lexicon_names`, list): Pronunciation lexicons to apply, up to 5. Create them with Save lexicon.

**Outputs**

- `character_count` (number): Characters Polly billed for this request (SSML tags excluded).
- `content_type` (text): Its MIME type, e.g. audio/mpeg.
- `document_ref` (text): The stored audio file's reference.
- `documents` (list): The audio file, as a document.
- `engine` (text): The engine requested (empty = standard).
- `filename` (text): Its file name.
- `output_format` (text): The audio format.
- `sample_rate` (text): The sample rate requested, if any.
- `size_bytes` (number): Its size in bytes.
- `text_type` (text): text or ssml.
- `url` (text): A link to download or play the audio.
- `voice_id` (text): The voice used.

**Example output**

```json
{
  "character_count": 38,
  "content_type": "audio/mpeg",
  "document_ref": "doc_4c1f7a2b9e0d5a63",
  "documents": [
    {
      "content_type": "audio/mpeg",
      "document_ref": "doc_4c1f7a2b9e0d5a63",
      "filename": "polly-joanna.mp3",
      "size_bytes": 18432,
      "url": "/actions/core/serve-document/doc_4c1f7a2b9e0d5a63?teamId=6512a1b2c3d4e5f600000001"
    }
  ],
  "engine": "neural",
  "filename": "polly-joanna.mp3",
  "output_format": "mp3",
  "sample_rate": null,
  "size_bytes": 18432,
  "text_type": "text",
  "url": "/actions/core/serve-document/doc_4c1f7a2b9e0d5a63?teamId=6512a1b2c3d4e5f600000001",
  "voice_id": "Joanna"
}
```

### Start speech synthesis task

Speak a long text (up to 100,000 characters) in the background, writing the audio file to your S3 bucket. Use Get speech synthesis task to see when it is done and where the file is.

**Inputs**

- Voice (`voice_id`, text, required): The voice to speak in. The list shows each voice's language, gender and the engines it supports; you can also type a voice id such as 'Joanna'.
- Text (`text`, text, required): What to say: plain text or SSML, up to 100,000 billed characters.
- S3 bucket (`output_s3_bucket_name`, text, required): The bucket Polly writes the file to, e.g. 'my-polly-audio' (an s3:// address also works). The access key needs s3:PutObject on it.
- S3 key prefix (`output_s3_key_prefix`, text): A folder-like prefix for the file name, e.g. 'audio/'. Polly adds the task id and extension.
- Engine (`engine`, text): Must be one the voice supports (shown in the Voice list). Left empty, Polly uses standard, which neural-only voices refuse. Long-form and generative cost more per character. One of: `standard` (Standard (cheapest, every region)), `neural` (Neural (more natural)), `long-form` (Long-form (us-east-1 only)), `generative` (Generative (most expressive, some regions)). Default: `neural`.
- Output format (`output_format`, text): The audio format, or Speech marks (JSON). Default MP3. One of: `mp3`, `ogg_vorbis` (Ogg Vorbis), `ogg_opus` (Ogg Opus), `pcm` (PCM (raw 16-bit mono, not directly playable)), `mulaw` (mu-law (telephony)), `alaw` (A-law (telephony)), `json` (Speech marks (JSON)). Default: `mp3`.
- Sample rate (`sample_rate`, text): Leave empty for the voice's default. One of: `8000` (8 kHz (pcm, mulaw, alaw, mp3, ogg_vorbis)), `16000` (16 kHz (pcm, mp3, ogg_vorbis)), `22050` (22.05 kHz (mp3, ogg_vorbis; standard default)), `24000` (24 kHz (mp3, ogg_vorbis; neural default)), `48000` (48 kHz (ogg_opus)).
- Text type (`text_type`, text): Plain text, or SSML for pauses, emphasis and pronunciation. Left empty, text that starts with <speak> is read as SSML. One of: `text` (Plain text), `ssml`.
- Language (`language_code`, text): Only for bilingual voices (e.g. Aditi): which of its languages to speak. Leave empty to use the voice's main language.
- Lexicons (`lexicon_names`, list): Pronunciation lexicons to apply, up to 5. Create them with Save lexicon.
- Mark types (`speech_mark_types`, list): Only with the Speech marks (JSON) format. One or more of: `sentence`, `word`, `viseme`, `ssml` (SSML marks).
- SNS topic ARN (`sns_topic_arn`, text): Optional: an SNS topic to notify when the task finishes. The access key needs sns:Publish on it.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "task": {
      "created_at": "2026-09-28T09:15:02.123000Z",
      "engine": "neural",
      "language_code": null,
      "lexicon_names": [],
      "output_format": "mp3",
      "output_uri": "https://s3.us-east-1.amazonaws.com/my-polly-audio/audio/d8a3f1b2-5c4e-4a7b-9f60-2e1d3c4b5a69.mp3",
      "request_characters": 1840,
      "sample_rate": null,
      "sns_topic_arn": null,
      "speech_mark_types": [],
      "status": "scheduled",
      "status_reason": null,
      "task_id": "d8a3f1b2-5c4e-4a7b-9f60-2e1d3c4b5a69",
      "text_type": "text",
      "voice_id": "Joanna"
    }
  }
}
```