LowCodeAPI awspolly skill

# AWS Polly Integration via LowCodeAPI

**Last Updated**: February 11, 2026

## Overview
AWS Polly is a service that turns text into lifelike speech, allowing you to create applications that talk. It provides:
- High-quality text-to-speech with multiple voices and languages
- Support for both standard and neural engines
- Multiple output formats (MP3, OGG, PCM, JSON)
- SSML (Speech Synthesis Markup Language) support
- Pronunciation lexicons for custom pronunciation
- Asynchronous synthesis tasks for long texts

## Base Endpoint
https://api.lowcodeapi.com/awspolly

**Important**: Always include the provider name in the URL path after `api.lowcodeapi.com/`

## Authentication
AWS Polly uses AWS Access Key authentication with the following credentials:

### Setup Instructions
1. Create an AWS account if you don't have one
2. Navigate to the IAM Console
3. Create a user with permissions to access Polly
4. Generate Access Key ID and Secret Access Key
5. Note your AWS region (e.g., us-east-1, us-west-2)
6. Add credentials to LowCodeAPI for the `awspolly` provider

### Get Credentials
- **AWS Access Keys**: [AWS IAM Documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)

**Required Credentials**:
- `accessKeyId` - Your AWS Access Key ID
- `secretAccessKey` - Your AWS Secret Access Key
- `region` - Your AWS region (e.g., us-east-1, us-west-2)

## URL Format (Important)

LowCodeAPI supports **two URL formats** for endpoints with path parameters. Always try the **New Format first**, and only fall back to the **Old Format** if it doesn't work.

### New Format (Priority) - Dynamic Path Parameters
Path parameters stay in the URL path - do NOT convert to query parameters.

Pattern: `https://api.lowcodeapi.com/awspolly/{path_with_params}?api_token={api_token}`

**Example**:
```bash
# New Format - Path parameter stays in the URL path
https://api.lowcodeapi.com/awspolly/v1/lexicons/my-lexicon?api_token=YOUR_API_TOKEN
```

### Old Format (Fallback) - Sanitized Path + Query Parameters
Path parameters become query parameters.

Pattern: `https://api.lowcodeapi.com/awspolly/{sanitized_path}?{path_params}&api_token={api_token}`

**Example**:
```bash
# Old Format - Path parameter becomes a query parameter
https://api.lowcodeapi.com/awspolly/v1/lexicons/lexicon_name?lexicon_name=my-lexicon&api_token=YOUR_API_TOKEN
```

### Decision Flow for AI Agents
1. Always use New Format first - Keep path parameters in the URL path
2. If you get a 404 or error, try Old Format with sanitized path
3. Log which format worked for future requests to AWS Polly

### Multiple Path Parameters
For endpoints with multiple path parameters:

```bash
# New Format (Priority)
https://api.lowcodeapi.com/awspolly/v1/synthesis-tasks/TASK_ID_123

# Old Format (Fallback)
https://api.lowcodeapi.com/awspolly/v1/synthesis-tasks/task_id?task_id=TASK_ID_123
```

## API Categories
- **Synthesis** - Text-to-speech synthesis
- **Voices** - Voice listing and information
- **Lexicons** - Pronunciation lexicon management
- **Synthesis Tasks** - Asynchronous long-form synthesis

## Common Endpoints

### Synthesize Speech
Synthesizes UTF-8 input, plain text or SSML, to a stream of bytes in a format like MP3, OGG, PCM, or JSON.

**Method**: POST | **LowCodeAPI Path**: `/v1/speech`

**New Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/speech?api_token={api_token}
```

**Old Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/speech?api_token={api_token}
```

**Path Parameters**: None

**Query Parameters**: None

**Request Body**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| Text | string | Yes | Input text to synthesize |
| OutputFormat | enum | Yes | Format in which the returned output will be encoded (json, mp3, ogg_vorbis, pcm) |
| VoiceId | enum | Yes | Voice ID to use for synthesis (e.g., Joanna, Matthew, Amy, Brian) |
| Engine | enum | No | Specifies the engine (standard or neural) for Amazon Polly to use |
| LanguageCode | string | No | Language code for the Synthesize Speech request |
| TextType | enum | No | Specifies whether the input text is plain text or SSML (text, ssml) |
| SampleRate | enum | No | The audio frequency specified in Hz (8000, 16000, 22050, 24000) |
| LexiconNames | array | No | List of one or more pronunciation lexicon names |
| SpeechMarkTypes | array | No | The type of speech marks returned (sentence, ssml, viseme, word) |

**Available Voices** (VoiceId):
Aditi, Amy, Astrid, Bianca, Brian, Camila, Carla, Carmen, Celine, Chantal, Conchita, Cristiano, Dora, Emma, Enrique, Ewa, Filiz, Gabrielle, Geraint, Giorgio, Gwyneth, Hans, Ines, Ivy, Jacek, Jan, Joanna, Joey, Justin, Karl, Kendra, Kevin, Kimberly, Lea, Liv, Lotte, Lucia, Lupe, Mads, Maja, Marlene, Mathieu, Matthew, Maxim, Mia, Miguel, Mizuki, Naja, Nicole, Olivia, Penelope, Raveena, Ricardo, Ruben, Russell, Salli, Seoyeon, Takumi, Tatyana, Vicki, Vitoria, Zeina, Zhiyu

**Example Request** (New Format):
```bash
curl -X POST "https://api.lowcodeapi.com/awspolly/v1/speech?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Text": "Hello, this is AWS Polly speaking!",
    "OutputFormat": "mp3",
    "VoiceId": "Joanna",
    "Engine": "neural"
  }'
```

**Example Response**:
```json
{
  "data": {
    "audioStream": "<base64-encoded-audio>",
    "contentType": "audio/mpeg",
    "requestCharacters": 35
  }
}
```

**Official Documentation**: [Synthesize Speech](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html)

---

### Describe Voices
Returns the list of voices that are available for use when requesting speech synthesis.

**Method**: GET | **LowCodeAPI Path**: `/v1/voices`

**New Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/voices?api_token={api_token}
```

**Old Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/voices?api_token={api_token}
```

**Path Parameters**: None

**Query Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| Engine | enum | No | Specifies which engine to use (standard, neural) |
| LanguageCode | string | No | The language identification tag (ISO 639 code for the language name-ISO 3166 country code) |
| IncludeAdditionalLanguageCodes | boolean | No | Boolean value indicating whether to return any bilingual voices |
| NextToken | string | No | An opaque pagination token returned from the previous DescribeVoices operation |

**Example Request** (New Format):
```bash
curl -X GET "https://api.lowcodeapi.com/awspolly/v1/voices?Engine=neural&LanguageCode=en-US&api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "data": {
    "Voices": [
      {
        "Id": "Joanna",
        "Name": "Joanna",
        "LanguageCode": "en-US",
        "LanguageName": "US English",
        "Gender": "Female",
        "SupportedEngines": ["standard", "neural"]
      }
    ]
  }
}
```

**Official Documentation**: [Describe Voices](https://docs.aws.amazon.com/polly/latest/dg/API_DescribeVoices.html)

---

### List Lexicons
Returns a list of pronunciation lexicons stored in an AWS Region.

**Method**: GET | **LowCodeAPI Path**: `/v1/lexicons`

**New Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/lexicons?api_token={api_token}
```

**Old Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/lexicons?api_token={api_token}
```

**Path Parameters**: None

**Query Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| NextToken | string | No | An opaque pagination token returned from the previous ListLexicons operation |

**Example Request** (New Format):
```bash
curl -X GET "https://api.lowcodeapi.com/awspolly/v1/lexicons?api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "data": {
    "Lexicons": [
      {
        "Name": "example-lexicon",
        "Attributes": {
          "LexiconArn": "arn:aws:polly:us-east-1:123456789012:lexicon/example-lexicon",
          "LexemesCount": 10,
          "Size": 1024
        }
      }
    ]
  }
}
```

**Official Documentation**: [List Lexicons](https://docs.aws.amazon.com/polly/latest/dg/API_ListLexicons.html)

---

### Get Lexicon
Returns the content of the specified pronunciation lexicon stored in an AWS Region.

**Method**: GET | **LowCodeAPI Path**: `/v1/lexicons/{lexicon_name}`

**New Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/lexicons/{lexicon_name}?api_token={api_token}
```

**Old Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/lexicons/lexicon_name?lexicon_name={lexicon_name}&api_token={api_token}
```

**Path Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| lexicon_name | string | Yes | Name of the lexicon |

**Query Parameters**: None

**Example Request** (New Format):
```bash
curl -X GET "https://api.lowcodeapi.com/awspolly/v1/lexicons/example-lexicon?api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "data": {
    "Lexicon": {
      "Name": "example-lexicon",
      "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>\n    <grapheme>AWS</grapheme>\n    <phoneme>ˈaʊ wɛs</phoneme>\n  </lexeme>\n</lexicon>"
    },
    "LexiconAttributes": {
      "LexiconArn": "arn:aws:polly:us-east-1:123456789012:lexicon/example-lexicon",
      "LexemesCount": 1,
      "Size": 500
    }
  }
}
```

**Official Documentation**: [Get Lexicon](https://docs.aws.amazon.com/polly/latest/dg/API_GetLexicon.html)

---

### Put Lexicon
Stores a pronunciation lexicon in an AWS Region.

**Method**: PUT | **LowCodeAPI Path**: `/v1/lexicons/{lexicon_name}`

**New Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/lexicons/{lexicon_name}?api_token={api_token}
```

**Old Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/lexicons/lexicon_name?lexicon_name={lexicon_name}&api_token={api_token}
```

**Path Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| lexicon_name | string | Yes | Name of the lexicon |

**Query Parameters**: None

**Request Body**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| Content | string | Yes | PLS lexicon content in PLS format |

**Example Request** (New Format):
```bash
curl -X PUT "https://api.lowcodeapi.com/awspolly/v1/lexicons/example-lexicon?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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>\n    <grapheme>AWS</grapheme>\n    <phoneme>ˈaʊ wɛs</phoneme>\n  </lexeme>\n</lexicon>"
  }'
```

**Example Response**:
```json
{
  "data": {
    "Lexicon": {
      "Name": "example-lexicon",
      "Content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
    },
    "LexiconAttributes": {
      "LexiconArn": "arn:aws:polly:us-east-1:123456789012:lexicon/example-lexicon",
      "LexemesCount": 1,
      "Size": 500
    }
  }
}
```

**Official Documentation**: [Put Lexicon](https://docs.aws.amazon.com/polly/latest/dg/API_PutLexicon.html)

---

### Start Speech Synthesis Task
Allows the creation of an asynchronous synthesis task, by starting a new SpeechSynthesisTask.

**Method**: POST | **LowCodeAPI Path**: `/v1/synthesis-tasks`

**New Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/synthesis-tasks?api_token={api_token}
```

**Old Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/synthesis-tasks?api_token={api_token}
```

**Path Parameters**: None

**Query Parameters**: None

**Request Body**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| Text | string | Yes | Specifies the text input to synthesize |
| OutputFormat | enum | Yes | The format in which the returned output will be encoded (json, mp3, ogg_vorbis, pcm) |
| OutputS3BucketName | string | Yes | Amazon S3 bucket name to which the output file will be saved |
| VoiceId | enum | Yes | Voice ID to use for the synthesis |
| Engine | enum | No | Specifies the engine (standard or neural) |
| LanguageCode | string | No | Optional language code |
| TextType | enum | No | Specifies whether the input text is plain text or SSML |
| SampleRate | enum | No | The audio frequency specified in Hz |
| LexiconNames | array | No | List of pronunciation lexicon names |
| SpeechMarkTypes | array | No | The type of speech marks returned |
| OutputS3KeyPrefix | string | No | The Amazon S3 key prefix for the output speech file |
| SnsTopicArn | string | No | ARN for the SNS topic for completion notification |

**Example Request** (New Format):
```bash
curl -X POST "https://api.lowcodeapi.com/awspolly/v1/synthesis-tasks?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Text": "This is a long text that will be synthesized asynchronously.",
    "OutputFormat": "mp3",
    "OutputS3BucketName": "my-audio-bucket",
    "VoiceId": "Joanna",
    "Engine": "neural"
  }'
```

**Example Response**:
```json
{
  "data": {
    "SynthesisTask": {
      "TaskId": "12345678-1234-1234-1234-123456789012",
      "Engine": "neural",
      "TaskStatus": "inProgress",
      "OutputUri": "s3://my-audio-bucket/output.mp3",
      "CreationTime": "2026-02-11T12:00:00Z"
    }
  }
}
```

**Official Documentation**: [Start Speech Synthesis Task](https://docs.aws.amazon.com/polly/latest/dg/API_StartSpeechSynthesisTask.html)

---

### Get Speech Synthesis Task
Retrieves a specific SpeechSynthesisTask object based on its TaskID.

**Method**: GET | **LowCodeAPI Path**: `/v1/synthesis-tasks/{task_id}`

**New Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/synthesis-tasks/{task_id}?api_token={api_token}
```

**Old Format URL**:
```
https://api.lowcodeapi.com/awspolly/v1/synthesis-tasks/task_id?task_id={task_id}&api_token={api_token}
```

**Path Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| task_id | string | Yes | The Amazon Polly generated identifier for a speech synthesis task |

**Query Parameters**: None

**Example Request** (New Format):
```bash
curl -X GET "https://api.lowcodeapi.com/awspolly/v1/synthesis-tasks/12345678-1234-1234-1234-123456789012?api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "data": {
    "SynthesisTask": {
      "TaskId": "12345678-1234-1234-1234-123456789012",
      "Engine": "neural",
      "TaskStatus": "completed",
      "OutputUri": "s3://my-audio-bucket/output.mp3",
      "CreationTime": "2026-02-11T12:00:00Z",
      "CompletionTime": "2026-02-11T12:00:05Z"
    }
  }
}
```

**Official Documentation**: [Get Speech Synthesis Task](https://docs.aws.amazon.com/polly/latest/dg/API_GetSpeechSynthesisTask.html)

---

## Complete Endpoint Reference

| Method | Category | New Format Path | Description |
|--------|----------|-----------------|-------------|
| POST | Synthesis | `/v1/speech` | Synthesize speech |
| GET | Voices | `/v1/voices` | Describe voices |
| GET | Voices | `/v1/voices/{voice_id}` | Get voice |
| GET | Lexicons | `/v1/lexicons` | List lexicons |
| GET | Lexicons | `/v1/lexicons/{lexicon_name}` | Get lexicon |
| PUT | Lexicons | `/v1/lexicons/{lexicon_name}` | Put lexicon |
| DELETE | Lexicons | `/v1/lexicons/{lexicon_name}` | Delete lexicon |
| GET | Lexicons | `/v1/lexicons/{lexicon_name}/lexemes` | Get lexicon entries |
| POST | Synthesis Tasks | `/v1/synthesis-tasks` | Start speech synthesis task |
| GET | Synthesis Tasks | `/v1/synthesis-tasks/{task_id}` | Get speech synthesis task |
| GET | Synthesis Tasks | `/v1/synthesis-tasks` | List speech synthesis tasks |

## API Definition Endpoints

To discover all available endpoints programmatically:

```bash
# New Format - OpenAPI spec with dynamic path parameters
curl -X GET "https://backend.lowcodeapi.com/awspolly/openapi"

# Old Format - API definition with sanitized paths
curl -X GET "https://backend.lowcodeapi.com/awspolly/definition"
```

## Usage Examples

### Example 1: Simple Text-to-Speech

```bash
# No ID needed - just provide text directly
curl -X POST "https://api.lowcodeapi.com/awspolly/v1/speech?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Text": "Hello, this is AWS Polly speaking!",
    "OutputFormat": "mp3",
    "VoiceId": "Joanna",
    "Engine": "neural"
  }'

# Response contains base64-encoded audio
```

### Example 2: SSML Synthesis with Custom Pronunciation

```bash
# Step 1: Create a lexicon for custom pronunciation
# No ID needed - just provide a name
curl -X PUT "https://api.lowcodeapi.com/awspolly/v1/lexicons/tech-lexicon?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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>\n    <grapheme>SaaS</grapheme>\n    <phoneme>sæs</phoneme>\n  </lexeme>\n</lexicon>"
  }'

# Step 2: Synthesize speech using the lexicon
curl -X POST "https://api.lowcodeapi.com/awspolly/v1/speech?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Text": "Welcome to our SaaS platform!",
    "OutputFormat": "mp3",
    "VoiceId": "Matthew",
    "Engine": "neural",
    "LexiconNames": ["tech-lexicon"]
  }'
```

### Example 3: Asynchronous Long-Form Synthesis

```bash
# Step 1: Start an asynchronous synthesis task
# No ID needed - task ID is returned
curl -X POST "https://api.lowcodeapi.com/awspolly/v1/synthesis-tasks?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Text": "This is a very long text that exceeds the synchronous synthesis limit...",
    "OutputFormat": "mp3",
    "OutputS3BucketName": "my-audio-bucket",
    "VoiceId": "Joanna",
    "Engine": "neural"
  }'

# Response returns: { "data": { "SynthesisTask": { "TaskId": "12345678-..." } } }
# Note: Task ID returned here will be used to check status

# Step 2: Check task status using the returned Task ID
curl -X GET "https://api.lowcodeapi.com/awspolly/v1/synthesis-tasks/12345678-1234-1234-1234-123456789012?api_token=YOUR_API_TOKEN"
# Note: Using Task ID from Step 1

# Step 3: List all tasks
curl -X GET "https://api.lowcodeapi.com/awspolly/v1/synthesis-tasks?Status=completed&api_token=YOUR_API_TOKEN"
```

### Example 4: Discover and Use Available Voices

```bash
# Step 1: List all available voices
# No ID needed - just list voices
curl -X GET "https://api.lowcodeapi.com/awspolly/v1/voices?api_token=YOUR_API_TOKEN"

# Response returns all voices with their IDs

# Step 2: Filter voices by language and engine
curl -X GET "https://api.lowcodeapi.com/awspolly/v1/voices?LanguageCode=en-US&Engine=neural&api_token=YOUR_API_TOKEN"

# Step 3: Synthesize using a specific voice ID from the list
# Use the voice ID returned (e.g., "Joanna", "Matthew", "Amy")
curl -X POST "https://api.lowcodeapi.com/awspolly/v1/speech?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Text": "Testing voice selection.",
    "OutputFormat": "mp3",
    "VoiceId": "Joanna"
  }'
```

### Example 5: SSML with Speech Marks

```bash
# Synthesize speech with SSML and request speech marks
# No ID needed
curl -X POST "https://api.lowcodeapi.com/awspolly/v1/speech?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Text": "<speak><amazon:effect name=\"whispered\">This is whispered.</amazon:effect> <emphasis>This is emphasized.</emphasis></speak>",
    "OutputFormat": "json",
    "TextType": "ssml",
    "VoiceId": "Joanna",
    "SpeechMarkTypes": ["word", "sentence"]
  }'

# Response returns JSON with timing information for each word and sentence
```

## Error Handling

| Status Code | Description |
|-------------|-------------|
| 200 | Success |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid or missing credentials |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource or lexicon doesn't exist |
| 429 | Rate Limit Exceeded |
| 500 | Internal Server Error |

## Response Format

All responses are wrapped in a `data` key:

```json
{
  "data": {
    // Actual response from AWS Polly API (object or array)
  }
}
```

## SSML Examples

AWS Polly supports SSML for advanced control:

```xml
<speak>
  Hello, <prosody rate="slow">this is slow</prosody> speech.
  <break time="1s" />
  This is after a pause.
  <amazon:effect name="whispered">
    This is whispered.
  </amazon:effect>
</speak>
```

## Output Formats

| Format | Description | Use Case |
|--------|-------------|----------|
| mp3 | MPEG-3 audio | General purpose, web playback |
| ogg_vorbis | Ogg Vorbis | Open source alternative to MP3 |
| pcm | Raw PCM audio | Professional audio processing |
| json | JSON with speech marks | For timing and lip-sync |

## Links
- **Official Documentation**: https://docs.aws.amazon.com/polly/latest/dg/API_Reference.html
- **Website**: https://aws.amazon.com/polly/
- **Get AWS Access Keys**: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html