> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Audio

> Converts text to speech using AI-powered voices. Returns an audio stream in MP3 format.

Converts text to speech using AI-powered voices. Returns an audio stream in MP3 format that can be played, downloaded, or integrated into applications.

## Overview

The Text-to-Speech API allows you to generate natural-sounding speech from text in multiple languages and voices. This endpoint is useful for creating voice content, accessibility features, voice assistants, and more.

## Use Cases

* **Voice Assistants**: Generate spoken responses for chatbots and virtual assistants
* **Accessibility**: Create audio versions of text content for visually impaired users
* **Content Creation**: Produce voiceovers for videos, podcasts, or presentations
* **E-Learning**: Generate audio narration for educational materials
* **IVR Systems**: Create dynamic voice prompts for phone systems

## Basic Usage

```javascript theme={null}
{
  "text": "Hello, welcome to InstaView. We're excited to help you conduct AI-powered interviews.",
  "voice": "ALEX",
  "language": "en"
}
```

## Voice Options

The API supports 12 different voices with various characteristics:

| Voice Name   | Gender | Best For                     |
| ------------ | ------ | ---------------------------- |
| **ALEX**     | Male   | Professional, clear delivery |
| **PETER**    | Male   | Warm, conversational tone    |
| **MIRIAM**   | Female | Professional, authoritative  |
| **SUE**      | Female | Friendly, approachable       |
| **VIERA**    | Female | Clear, neutral tone          |
| **CASANDRA** | Female | Warm, engaging               |
| **SILVIA**   | Female | Professional, polished       |
| **MICHAEL**  | Male   | Deep, authoritative          |
| **LUKE**     | Male   | Energetic, dynamic           |
| **EMMA**     | Female | Clear, friendly              |
| **SARAH**    | Female | Warm, professional           |
| **EVA**      | Female | Neutral, versatile           |

## Language Support

The API supports 33 languages. Use the appropriate language code for your text:

| Language  | Code | Language   | Code  | Language  | Code |
| --------- | ---- | ---------- | ----- | --------- | ---- |
| English   | `en` | Japanese   | `ja`  | Chinese   | `zh` |
| German    | `de` | Hindi      | `hi`  | French    | `fr` |
| Korean    | `ko` | Portuguese | `pt`  | Italian   | `it` |
| Spanish   | `es` | Indonesian | `id`  | Dutch     | `nl` |
| Turkish   | `tr` | Filipino   | `fil` | Polish    | `pl` |
| Swedish   | `sv` | Bulgarian  | `bg`  | Romanian  | `ro` |
| Arabic    | `ar` | Czech      | `cs`  | Greek     | `el` |
| Finnish   | `fi` | Croatian   | `hr`  | Malay     | `ms` |
| Slovak    | `sk` | Danish     | `da`  | Tamil     | `ta` |
| Ukrainian | `uk` | Russian    | `ru`  | Hungarian | `hu` |
| Norwegian | `no` | Vietnamese | `vi`  |           |      |

## Response Format

The endpoint returns an audio stream with `Content-Type: audio/mpeg`. You can:

* **Stream directly**: Play the audio in real-time
* **Save to file**: Download and store the MP3 file
* **Integrate**: Use in applications, websites, or phone systems

### Example: Saving Audio (Node.js)

```javascript theme={null}
const fs = require('fs');
const response = await fetch('https://api.instaview.sk/v1/public/voice', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Hello, this is a test.',
    voice: 'SARAH',
    language: 'en'
  })
});

if (!response.ok) {
  throw new Error(`API error: ${response.status}`);
}

const buffer = await response.arrayBuffer();
fs.writeFileSync('output.mp3', Buffer.from(buffer));
```

### Example: Playing Audio (Browser)

```javascript theme={null}
const response = await fetch('https://api.instaview.sk/v1/public/voice', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Hello, this is a test.',
    voice: 'EMMA',
    language: 'en'
  })
});

if (!response.ok) {
  throw new Error(`API error: ${response.status}`);
}

const blob = await response.blob();
const audioUrl = URL.createObjectURL(blob);
const audio = new Audio(audioUrl);
audio.play();
```

### Example: Python

```python theme={null}
import requests

response = requests.post(
    'https://api.instaview.sk/v1/public/voice',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'text': 'Hello, this is a test.',
        'voice': 'MICHAEL',
        'language': 'en'
    }
)

response.raise_for_status()

with open('output.mp3', 'wb') as f:
    f.write(response.content)
```

## Text Limitations

<Info>
  The `text` field has a maximum length of **5,000 characters**. For longer content, split the text into multiple requests.
</Info>

## Authentication & Scopes

<Warning>
  This endpoint requires the **VOICE** scope. Ensure your API key has this scope enabled before making requests.
</Warning>

## Error Handling

Common errors you may encounter:

* **400 Bad Request**: Invalid voice name or language code
* **401 Unauthorized**: Missing or invalid API key
* **403 Forbidden**: API key lacks VOICE scope
* **413 Payload Too Large**: Text exceeds 5,000 characters
* **429 Too Many Requests**: Rate limit exceeded

## Rate Limiting

This endpoint is subject to your API key's rate limits. Monitor the rate limit headers in the response:

* `X-RateLimit-Limit`: Maximum requests allowed
* `X-RateLimit-Remaining`: Requests remaining in current window
* `X-RateLimit-Reset`: Time when the rate limit resets

## Related Resources

<CardGroup cols={2}>
  <Card title="API Keys Guide" icon="key" href="/guides/api-keys">
    Learn about API key management and scopes
  </Card>

  <Card title="Rate Limiting" icon="gauge" href="/guides/rate-limiting">
    Understand rate limits and best practices
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/error-handling">
    Handle API errors gracefully
  </Card>

  <Card title="Scopes & Permissions" icon="shield-halved" href="/guides/scopes-and-permissions">
    Learn about API key scopes
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /voice
openapi: 3.0.0
info:
  title: InstaView API
  description: |-
    InstaView API Documentation

    ## Authentication

    All endpoints require API key authentication using Bearer token:
    ```
    Authorization: Bearer sk_your_api_key_here
    ```

    ## API Key Management

    The API Key module provides comprehensive key management for:
    - **Direct Client Keys**: Company-scoped keys for your applications
    - **ATS Partner Keys**: Resource-scoped keys for ATS integrations

    ### Key Features
    - HMAC-SHA256 hashing for API key storage
    - Configurable rate limiting
    - Comprehensive audit logging
    - Company-level isolation
    - Resource scoping for ATS partners
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.instaview.sk
    description: Production API Gateway
security: []
tags: []
paths:
  /voice:
    post:
      tags:
        - Public TTS
      summary: Generate audio from text
      description: >-
        Converts text to speech using AI-powered voices. Returns an audio stream
        in MP3 format.
      operationId: PublicTtsController_generateAudio_v1
      parameters:
        - name: companyId
          required: false
          in: query
          description: >-
            Required for ATS API keys to specify which company to access.
            Ignored for standard company API keys.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicGenerateAudioDto'
      responses:
        '200':
          description: Audio stream generated successfully
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request - Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearer: []
components:
  schemas:
    PublicGenerateAudioDto:
      type: object
      properties:
        text:
          type: string
          description: The text to convert to speech
          example: Hello, this is a test.
          maxLength: 5000
        voice:
          type: string
          description: The voice name to use for generation
          example: ALEX
          enum:
            - ALEX
            - PETER
            - MIRIAM
            - SUE
            - VIERA
            - CASANDRA
            - SILVIA
            - MICHAEL
            - LUKE
            - EMMA
            - SARAH
            - EVA
        language:
          type: string
          description: The language of the text
          example: en
          enum:
            - en
            - ja
            - zh
            - de
            - hi
            - fr
            - ko
            - pt
            - it
            - es
            - id
            - nl
            - tr
            - fil
            - pl
            - sv
            - bg
            - ro
            - ar
            - cs
            - el
            - fi
            - hr
            - ms
            - sk
            - da
            - ta
            - uk
            - ru
            - hu
            - 'no'
            - vi
      required:
        - text
        - voice
        - language
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          type: string
          example: Validation failed
        error:
          type: string
          example: Bad Request
      required:
        - statusCode
        - message
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key for authentication using Bearer scheme

````