> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Streaming de texto em voz

Este guia aborda três abordagens: gerar voz como um arquivo, transmitir a resposta de áudio diretamente e, opcionalmente, enviar o áudio gerado para um bucket do AWS S3 para compartilhá-lo por meio de uma URL assinada.

> **Note**
>
> Este guia pressupõe que você já [configurou sua chave de API e o SDK](/docs/pt/eleven-api/quickstart). Conclua
> o guia de início rápido primeiro, caso ainda não tenha feito isso. A seção opcional de envio para o S3 também exige uma conta da AWS
> com acesso ao S3.

> **Tip**
>
> Quer saber por que o streaming funciona dessa forma? [Entenda o streaming de áudio](/docs/pt/eleven-api/concepts/audio-streaming) explica em detalhes o protocolo, o buffering e os
> impactos na latência.

## Converter texto em voz (arquivo)

Para converter texto em voz e salvá-lo como arquivo, usaremos o método `convert` do SDK da ElevenLabs e o salvaremos localmente como um arquivo `.mp3`.

**`Python`**

```python Python

import os
import uuid
from dotenv import load_dotenv
from elevenlabs import VoiceSettings
from elevenlabs.client import ElevenLabs

load_dotenv()

ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(
    api_key=ELEVENLABS_API_KEY,
)


def text_to_speech_file(text: str) -> str:
    # Calling the text_to_speech conversion API with detailed parameters
    response = elevenlabs.text_to_speech.convert(
        voice_id="pNInz6obpgDQGcFmaJgB", # Adam pre-made voice
        output_format="mp3_22050_32",
        text=text,
        model_id="eleven_flash_v2_5", # use the flash model for low latency
        # Optional voice settings that allow you to customize the output
        voice_settings=VoiceSettings(
            stability=0.0,
            similarity_boost=1.0,
            style=0.0,
            use_speaker_boost=True,
            speed=1.0,
        ),
    )

    # uncomment the line below to play the audio back
    # play(response)

    # Generating a unique file name for the output MP3 file
    save_file_path = f"{uuid.uuid4()}.mp3"

    # Writing the audio to a file
    with open(save_file_path, "wb") as f:
        for chunk in response:
            if chunk:
                f.write(chunk)

    print(f"{save_file_path}: A new audio file was saved successfully!")

    # Return the path of the saved audio file
    return save_file_path

```

**`TypeScript`**

```typescript TypeScript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import * as dotenv from "dotenv";
import { createWriteStream } from "fs";
import { v4 as uuid } from "uuid";

dotenv.config();

const ELEVENLABS_API_KEY = process.env.ELEVENLABS_API_KEY;

const elevenlabs = new ElevenLabsClient({
  apiKey: ELEVENLABS_API_KEY,
});

export const createAudioFileFromText = async (text: string): Promise<string> => {
  return new Promise<string>(async (resolve, reject) => {
    try {
      const audio = await elevenlabs.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
        modelId: "eleven_v4",
        text,
        outputFormat: "mp3_44100_128",
        // Optional voice settings that allow you to customize the output
        voiceSettings: {
          stability: 0,
          similarityBoost: 0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      });

      const fileName = `${uuid()}.mp3`;
      const fileStream = createWriteStream(fileName);

      audio.pipe(fileStream);
      fileStream.on("finish", () => resolve(fileName)); // Resolve with the fileName
      fileStream.on("error", reject);
    } catch (error) {
      reject(error);
    }
  });
};
```

Depois, execute esta função com:

**`Python`**

```python Python
text_to_speech_file("Hello World")
```

**`TypeScript`**

```typescript TypeScript
await createAudioFileFromText("Hello World");
```

## Converter texto em voz (streaming)

Se preferir transmitir o áudio diretamente sem salvá-lo em um arquivo, você pode usar nosso recurso de streaming.

**`Python`**

```python Python

import os
from typing import IO
from io import BytesIO
from dotenv import load_dotenv
from elevenlabs import VoiceSettings
from elevenlabs.client import ElevenLabs

load_dotenv()

ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(
    api_key=ELEVENLABS_API_KEY,
)


def text_to_speech_stream(text: str) -> IO[bytes]:
    # Perform the text-to-speech conversion
    response = elevenlabs.text_to_speech.stream(
        voice_id="pNInz6obpgDQGcFmaJgB", # Adam pre-made voice
        output_format="mp3_22050_32",
        text=text,
        model_id="eleven_multilingual_v2",
        # Optional voice settings that allow you to customize the output
        voice_settings=VoiceSettings(
            stability=0.0,
            similarity_boost=1.0,
            style=0.0,
            use_speaker_boost=True,
            speed=1.0,
        ),
    )

    # Create a BytesIO object to hold the audio data in memory
    audio_stream = BytesIO()

    # Write each chunk of audio data to the stream
    for chunk in response:
        if chunk:
            audio_stream.write(chunk)

    # Reset stream position to the beginning
    audio_stream.seek(0)

    # Return the stream for further use
    return audio_stream

```

**`TypeScript`**

```typescript TypeScript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import * as dotenv from "dotenv";

dotenv.config();

const ELEVENLABS_API_KEY = process.env.ELEVENLABS_API_KEY;

if (!ELEVENLABS_API_KEY) {
  throw new Error("Missing ELEVENLABS_API_KEY in environment variables");
}

const elevenlabs = new ElevenLabsClient({
  apiKey: ELEVENLABS_API_KEY,
});

export const createAudioStreamFromText = async (text: string): Promise<Buffer> => {
  const audioStream = await elevenlabs.textToSpeech.stream("JBFqnCBsd6RMkjVDRZzb", {
    modelId: "eleven_v4",
    text,
    outputFormat: "mp3_44100_128",
    // Optional voice settings that allow you to customize the output
    voiceSettings: {
      stability: 0,
      similarityBoost: 1.0,
      useSpeakerBoost: true,
      speed: 1.0,
    },
  });

  const chunks: Buffer[] = [];
  for await (const chunk of audioStream) {
    chunks.push(chunk);
  }

  const content = Buffer.concat(chunks);
  return content;
};
```

Depois, execute esta função com:

**`Python`**

```python Python
text_to_speech_stream("This is James")
```

**`TypeScript`**

```typescript TypeScript
await createAudioStreamFromText("This is James");
```

## Bônus — Enviar para o AWS S3 e obter um link seguro de compartilhamento

Depois que seus dados de áudio forem criados como arquivo ou stream, você talvez queira compartilhá-los com seus usuários. Uma forma de fazer isso é enviá-los para um bucket do AWS S3 e gerar um link seguro de compartilhamento.

#### Criar suas credenciais da AWS

Para enviar os dados ao S3, você precisará adicionar o ID da chave de acesso da AWS, a chave de acesso secreta e o nome da região da AWS ao seu arquivo `.env`. Siga estas etapas para encontrar as credenciais:

1. Faça login no AWS Management Console: acesse a página inicial da AWS e entre com sua conta.

![](/docs/_fern-img/e9f1f1b1950962c3d67ea25a0593ca989d33c9f49b641e22eb3f861fc72735e3.webp)

2. Acesse o painel do IAM (Identity and Access Management): você encontra o IAM em "Security, Identity, & Compliance" no menu de serviços. O painel do IAM gerencia com segurança o acesso aos seus serviços da AWS.

![](/docs/_fern-img/d6fa7e75879e7537693c4edde16d0ac5face78d72b00de50743a754c0681a5e3.webp)

3. Crie um novo usuário (se necessário): no painel do IAM, selecione "Users" e depois "Add user". Digite um nome de usuário.

![](/docs/_fern-img/47b05ffda6925e4e14147aadc296d7c86cbd3340aaa1025083f1e1464b230f51.webp)

4. Defina as permissões: anexe políticas diretamente ao usuário de acordo com o nível de acesso que deseja conceder. Para envios ao S3, você pode usar a política AmazonS3FullAccess. No entanto, a prática recomendada é conceder o menor privilégio, ou seja, as permissões mínimas necessárias para realizar uma tarefa. Talvez você queira criar uma política personalizada que permita apenas as ações necessárias no seu bucket do S3.

![](/docs/_fern-img/4b88bba4f5bb1509aa087a1ab5cc8068a274b17d8887c563f050b77e8438bb94.webp)

5. Revise e crie o usuário: revise suas configurações e crie o usuário. Após a criação, você receberá um ID de chave de acesso e uma chave de acesso secreta. Baixe e salve essas credenciais em segurança; a chave de acesso secreta não poderá ser recuperada novamente após esta etapa.

![](/docs/_fern-img/27dcdff3681522cf936ff6bfb81cf216ada1fe401c7c1dbd10e58cead8a48abc.webp)

6. Obtenha o nome da região da AWS: por exemplo, us-east-1

![](/docs/_fern-img/016bc11c2f040942b215366c5fc9ac8e01f6261f5ebd44a3456d4b7ba97e9ae8.webp)

Se você não tiver um bucket do AWS S3, precisará criar um seguindo estas etapas:

1. Acesse o painel do S3: você encontra o S3 em "Storage" no menu de serviços.

![](/docs/_fern-img/d2455fa92ce6dfa705c3b91144fe22539fae1611848cb8e3cc2dac20e57db4e7.webp)

2. Crie um novo bucket: no painel do S3, clique no botão "Create bucket".

![](/docs/_fern-img/3b7d5bdb6559e8511445b41b1bbdeed3f6674791cf23021a30ccb5aa8143be28.webp)

3. Insira um nome para o bucket e clique no botão "Create bucket". Você pode deixar as outras opções do bucket com os valores padrão. O bucket recém-adicionado aparecerá na lista.

![](/docs/_fern-img/68d23f21bec1e3aa70b18f09c40c9bdace5ff0dd63edc17c6807e7ddac75758d.webp)![](/docs/_fern-img/63f7af93d4a73fab3011853c8393c954400d9f344a5811ec90b86d6c69b2ec16.webp)

#### Instalar o SDK da AWS e adicionar as credenciais

Instale o `boto3` para interagir com serviços da AWS usando `pip` e `npm`.

**`Python`**

```bash Python
pip install boto3
```

**`TypeScript`**

```bash TypeScript
npm install @aws-sdk/client-s3
npm install @aws-sdk/s3-request-presigner
```

Em seguida, adicione as variáveis de ambiente ao arquivo `.env` desta forma:

```
AWS_ACCESS_KEY_ID=your_aws_access_key_id_here
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key_here
AWS_REGION_NAME=your_aws_region_name_here
AWS_S3_BUCKET_NAME=your_s3_bucket_name_here
```

#### Enviar para o AWS S3 e gerar a URL assinada

Adicione as funções a seguir para enviar o stream de áudio ao S3 e gerar uma URL assinada.

**`s3_uploader.py (Python)`**

```python s3_uploader.py (Python)

import os
import boto3
import uuid

AWS_ACCESS_KEY_ID = os.getenv("AWS_ACCESS_KEY_ID")
AWS_SECRET_ACCESS_KEY = os.getenv("AWS_SECRET_ACCESS_KEY")
AWS_REGION_NAME = os.getenv("AWS_REGION_NAME")
AWS_S3_BUCKET_NAME = os.getenv("AWS_S3_BUCKET_NAME")

session = boto3.Session(
    aws_access_key_id=AWS_ACCESS_KEY_ID,
    aws_secret_access_key=AWS_SECRET_ACCESS_KEY,
    region_name=AWS_REGION_NAME,
)
s3 = session.client("s3")


def generate_presigned_url(s3_file_name: str) -> str:
    signed_url = s3.generate_presigned_url(
        "get_object",
        Params={"Bucket": AWS_S3_BUCKET_NAME, "Key": s3_file_name},
        ExpiresIn=3600,
    )  # URL expires in 1 hour
    return signed_url


def upload_audiostream_to_s3(audio_stream) -> str:
    s3_file_name = f"{uuid.uuid4()}.mp3"  # Generates a unique file name using UUID
    s3.upload_fileobj(audio_stream, AWS_S3_BUCKET_NAME, s3_file_name)

    return s3_file_name

```

**`s3_uploader.ts (TypeScript)`**

```typescript s3_uploader.ts (TypeScript)
import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import * as dotenv from "dotenv";
import { v4 as uuid } from "uuid";

dotenv.config();

const { AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION_NAME, AWS_S3_BUCKET_NAME } =
  process.env;

if (!AWS_ACCESS_KEY_ID || !AWS_SECRET_ACCESS_KEY || !AWS_REGION_NAME || !AWS_S3_BUCKET_NAME) {
  throw new Error("One or more environment variables are not set. Please check your .env file.");
}

const s3 = new S3Client({
  credentials: {
    accessKeyId: AWS_ACCESS_KEY_ID,
    secretAccessKey: AWS_SECRET_ACCESS_KEY,
  },
  region: AWS_REGION_NAME,
});

export const generatePresignedUrl = async (objectKey: string) => {
  const getObjectParams = {
    Bucket: AWS_S3_BUCKET_NAME,
    Key: objectKey,
    Expires: 3600,
  };
  const command = new GetObjectCommand(getObjectParams);
  const url = await getSignedUrl(s3, command, { expiresIn: 3600 });
  return url;
};

export const uploadAudioStreamToS3 = async (audioStream: Buffer) => {
  const remotePath = `${uuid()}.mp3`;
  await s3.send(
    new PutObjectCommand({
      Bucket: AWS_S3_BUCKET_NAME,
      Key: remotePath,
      Body: audioStream,
      ContentType: "audio/mpeg",
    })
  );
  return remotePath;
};
```

Depois, você pode chamar a função de envio com o stream de áudio do texto.

**`Python`**

```python Python
s3_file_name = upload_audiostream_to_s3(audio_stream)
```

**`TypeScript`**

```typescript TypeScript
const s3path = await uploadAudioStreamToS3(stream);
```

Após enviar o arquivo de áudio ao S3, gere uma URL assinada para compartilhar o acesso ao arquivo. Essa URL terá tempo limitado, ou seja, expirará após determinado período, o que a torna segura para compartilhamento temporário.

Agora você pode gerar uma URL a partir de um arquivo com:

**`Python`**

```python Python
signed_url = generate_presigned_url(s3_file_name)
print(f"Signed URL to access the file: {signed_url}")
```

**`TypeScript`**

```typescript TypeScript
const presignedUrl = await generatePresignedUrl(s3path);
console.log("Presigned URL:", presignedUrl);
```

Se quiser usar o arquivo várias vezes, armazene o caminho do arquivo no S3 no seu banco de dados e gere novamente a URL assinada sempre que precisar, em vez de salvar a URL assinada diretamente, pois ela expirará.

#### Juntando tudo

Para juntar tudo, você pode usar o seguinte script:

**`main.py (Python)`**

```python main.py (Python)

import os

from dotenv import load_dotenv

load_dotenv()

from text_to_speech_stream import text_to_speech_stream
from s3_uploader import upload_audiostream_to_s3, generate_presigned_url


def main():
    text = "This is James"

    audio_stream = text_to_speech_stream(text)
    s3_file_name = upload_audiostream_to_s3(audio_stream)
    signed_url = generate_presigned_url(s3_file_name)

    print(f"Signed URL to access the file: {signed_url}")


if __name__ == "__main__":
    main()

```

**`index.ts (Typescript)`**

```typescript index.ts (Typescript)
import "dotenv/config";

import { generatePresignedUrl, uploadAudioStreamToS3 } from "./s3_uploader";
import { createAudioFileFromText } from "./text_to_speech_file";
import { createAudioStreamFromText } from "./text_to_speech_stream";

(async () => {
  // save the audio file to disk
  const fileName = await createAudioFileFromText(
    "Today, the sky is exceptionally clear, and the sun shines brightly."
  );

  console.log("File name:", fileName);

  // OR stream the audio, upload to S3, and get a presigned URL
  const stream = await createAudioStreamFromText(
    "Today, the sky is exceptionally clear, and the sun shines brightly."
  );

  const s3path = await uploadAudioStreamToS3(stream);

  const presignedUrl = await generatePresignedUrl(s3path);

  console.log("Presigned URL:", presignedUrl);
})();
```

## Conclusão

Agora você sabe como converter texto em voz e gerar uma URL assinada para compartilhar o arquivo de áudio. Essa funcionalidade abre diversas possibilidades para criar e compartilhar conteúdo de forma dinâmica.

Veja alguns exemplos do que você pode criar com isso.

1. **Podcasts educacionais**: crie conteúdo educacional personalizado que os alunos possam acessar sob demanda. Professores podem converter suas aulas para o formato de áudio, enviá-las ao S3 e compartilhar os links com os alunos para uma experiência de aprendizagem mais envolvente fora do ambiente tradicional da sala de aula.

2. **Recursos de acessibilidade para sites**: melhore a acessibilidade de sites oferecendo conteúdo textual em formato de áudio. Isso pode tornar as informações dos sites mais acessíveis para pessoas com deficiência visual ou que preferem aprender ouvindo.

3. **Mensagens automatizadas de suporte ao cliente**: produza mensagens de áudio automatizadas e personalizadas para suporte ao cliente, como FAQs ou atualizações de pedidos. Isso pode proporcionar uma experiência mais envolvente ao cliente em comparação com e-mails de texto tradicionais.

4. **Audiolivros e narração**: converta livros inteiros ou contos em formato de áudio, oferecendo uma nova forma de o público aproveitar a literatura. Autores e editoras podem diversificar sua oferta de conteúdo e alcançar públicos que preferem ouvir a ler.

5. **Ferramentas de aprendizado de idiomas**: desenvolva recursos de aprendizado de idiomas que ofereçam aulas e exercícios em áudio. Isso possibilita praticar a pronúncia e as habilidades de escuta de forma direcionada.

## Próximas etapas

#### [Streaming com WebSocket](/docs/pt/eleven-api/guides/how-to/websockets/realtime-tts)

Use WebSockets para transmitir texto em voz em tempo real à medida que ele é gerado por um LLM.

#### [Entendendo a latência](/docs/pt/eleven-api/concepts/latency)

Saiba o que contribui para a latência e como minimizar o tempo até o primeiro áudio.