> 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.

# Transmitir fala com marcação de tempo

POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream/with-timestamps
Content-Type: application/json

Converte texto em fala usando uma voz à sua escolha e retorna um fluxo de JSONs contendo áudio como uma string codificada em base64, junto com informações sobre quando cada caractere foi falado.

Reference: https://elevenlabs.io/docs/api-reference/text-to-speech/stream-with-timestamps

## Servers

- `https://api.elevenlabs.io` (Production, default)
- `https://api.us.elevenlabs.io` (Production US)
- `https://api.eu.residency.elevenlabs.io` (Production EU)
- `https://api.in.residency.elevenlabs.io` (Production India)
- `https://api.sg.residency.elevenlabs.io` (Production Singapore)

## Request

### Path parameters

- `voice_id` (string, required) — ID da voz a ser usada. Use o endpoint [Get voices](/docs/api-reference/voices/search) para listar todas as vozes disponíveis.

### Query parameters

- `enable_logging` (boolean, optional, default: true) — Quando enable_logging for definido como false, o modo de retenção zero será usado para a solicitação. Isso significa que os recursos de histórico não estarão disponíveis para esta solicitação, incluindo a união de solicitações. O modo de retenção zero só pode ser usado por clientes empresariais.
- `optimize_streaming_latency` (integer, optional, nullable, deprecated) — Você pode ativar otimizações de latência com alguma perda de qualidade. A melhor latência final possível varia conforme o modelo. Valores possíveis: 0 - modo padrão (sem otimizações de latência) 1 - otimizações normais de latência (cerca de 50% da possível melhoria de latência da opção 3) 2 - otimizações fortes de latência (cerca de 75% da possível melhoria de latência da opção 3) 3 - otimizações máximas de latência 4 - otimizações máximas de latência, mas também com o normalizador de texto desativado para reduzir ainda mais a latência (melhor latência, mas pode pronunciar incorretamente, por exemplo, números e datas). O padrão é None.
- `output_format` (enum, optional, default: mp3_44100_128) — Output format of the generated audio. Formatted as codec_sample_rate_bitrate. So an mp3 with 22.05kHz sample rate at 32kbs is represented as mp3_22050_32. MP3 with 192kbps bitrate requires you to be subscribed to Creator tier or above. PCM with 44.1kHz sample rate requires you to be subscribed to Pro tier or above. Note that the μ-law format (sometimes written mu-law, often approximated as u-law) is commonly used for Twilio audio inputs.
  - Allowed values: `mp3_22050_32`, `mp3_24000_48`, `mp3_44100_32`, `mp3_44100_64`, `mp3_44100_96`, `mp3_44100_128`, `mp3_44100_192`, `pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_32000`, `pcm_44100`, `pcm_48000`, `ulaw_8000`, `alaw_8000`, `opus_48000_32`, `opus_48000_64`, `opus_48000_96`, `opus_48000_128`, `opus_48000_192`

### Body (application/json)

This endpoint expects a Body_text_to_speech_stream_with_timestamps.

- `text` (string, required) — O texto que será convertido em fala.
- `model_id` (string, optional, default: eleven_multilingual_v2) — Identificador do modelo que será usado. Você pode consultá-lo usando GET /v1/models. O modelo precisa oferecer suporte a texto para voz, o que pode ser verificado pela propriedade can_do_text_to_speech.
- `language_code` (string, optional, nullable) — Código de idioma (ISO 639-1) usado para aplicar um idioma ao modelo e à normalização de texto. Se o modelo não oferecer suporte ao código de idioma fornecido, ele será ignorado. Este parâmetro não é compatível com modelos multilingual_v2.
- `voice_settings` (VoiceSettingsResponseModel, optional, nullable) — Configurações de voz que substituem as configurações armazenadas para a voz fornecida. Elas são aplicadas somente à solicitação fornecida.
- `pronunciation_dictionary_locators` (list of PronunciationDictionaryVersionLocatorRequestModel, optional, nullable) — Uma lista de localizadores de dicionários de pronúncia (id, version_id) a serem aplicados ao texto. Eles serão aplicados em ordem. Você pode ter até 3 localizadores por solicitação
- `seed` (integer, optional, nullable) — Se especificado, nosso sistema fará o possível para realizar a amostragem de forma determinística, de modo que solicitações repetidas com a mesma semente e os mesmos parâmetros retornem o mesmo resultado. O determinismo não é garantido. Deve ser um número inteiro entre 0 e 4294967295.
- `previous_text` (string, optional, nullable) — O texto que veio antes do texto da solicitação atual. Pode ser usado para melhorar a continuidade da fala ao concatenar várias gerações ou para influenciar a continuidade da fala na geração atual.
- `next_text` (string, optional, nullable) — O texto que vem depois do texto da solicitação atual. Pode ser usado para melhorar a continuidade da fala ao concatenar várias gerações ou para influenciar a continuidade da fala na geração atual.
- `previous_request_ids` (list of string, optional, nullable) — Uma lista de request_id das amostras geradas antes desta geração. Pode ser usada para melhorar a continuidade da fala ao dividir uma tarefa grande em várias solicitações. Os resultados serão melhores quando o mesmo modelo for usado em todas as gerações. Caso previous_text e previous_request_ids sejam enviados, previous_text será ignorado. É possível enviar no máximo 3 request_ids.
- `next_request_ids` (list of string, optional, nullable) — Uma lista de request_id das amostras geradas após esta geração. next_request_ids é especialmente útil para manter a continuidade da fala ao regenerar uma amostra que apresentou problemas de qualidade de áudio. Por exemplo, se você gerou 3 clipes de fala e quer melhorar o clipe 2, passar o ID da solicitação do clipe 3 como next_request_id, e o do clipe 1 como previous_request_id, ajudará a manter um fluxo natural na fala combinada. Os resultados serão melhores quando o mesmo modelo for usado em todas as gerações. Caso next_text e next_request_ids sejam enviados, next_text será ignorado. É possível enviar no máximo 3 request_ids.
- `use_pvc_as_ivc` (boolean, optional, default: false) — Se deve usar a versão IVC de uma voz profissional. Isso pode melhorar a expressividade e reduzir a latência.
- `apply_text_normalization` (enum, optional, default: auto) — Este parâmetro controla a normalização de texto com três modos: 'auto', 'on' e 'off'. Quando definido como 'auto', o sistema decidirá automaticamente se aplicará a normalização de texto, por exemplo, escrever números por extenso. Com 'on', a normalização de texto será sempre aplicada; com 'off', ela será ignorada.
  - Allowed values: `auto`, `on`, `off`
- `apply_language_text_normalization` (boolean, optional, default: false) — Este parâmetro controla a normalização de texto do idioma. Isso ajuda na pronúncia correta do texto em alguns idiomas compatíveis. AVISO: este parâmetro pode aumentar significativamente a latência da solicitação. No momento, é compatível apenas com japonês.
- `audio_effects` (EffectsSpec-Input, optional, nullable) — Efeitos de áudio aplicados ao áudio gerado. IDs desconhecidos retornam 404 com `param` indicando o campo. Reverberação (`environment_id` com `send_level` acima de 0) e um `pan` diferente de zero produzem áudio estéreo e são rejeitados com 400 para os formatos de saída `ulaw_*`, `alaw_*` e `pcm_*`. Os efeitos não alteram o custo da solicitação.

## Response

### 200

Fluxo de trechos de transcrição

- Streaming response of `StreamingAudioChunkWithTimestampsResponseModel`.
- `audio_base64` (string, required) — Dados de áudio codificados em Base64
- `alignment` (CharacterAlignmentResponseModel, optional, nullable) — Informações de timestamp para cada caractere do texto original
- `normalized_alignment` (CharacterAlignmentResponseModel, optional, nullable) — Informações de timestamp para cada caractere do texto normalizado

## Errors

### 422 Unprocessable Entity Error

Erro de validação

- `detail` (list of ValidationError, optional)

## Types

### VoiceSettingsResponseModel

- `stability` (double, optional, nullable, default: 0.5) — Determina a estabilidade da voz e a aleatoriedade entre cada geração. Valores menores introduzem uma gama emocional mais ampla na voz. Valores maiores podem resultar em uma voz monótona e com emoção limitada.
- `use_speaker_boost` (boolean, optional, nullable, default: true) — Esta configuração aumenta a semelhança com o locutor original. Seu uso exige uma carga computacional um pouco maior, o que, por sua vez, aumenta a latência.
- `similarity_boost` (double, optional, nullable, default: 0.75) — Determina o quanto a IA deve se manter fiel à voz original ao tentar replicá-la.
- `style` (double, optional, nullable, default: 0) — Determina a exageração de estilo da voz. Essa configuração tenta amplificar o estilo do falante original. Ela consome recursos computacionais adicionais e pode aumentar a latência se for definida como um valor diferente de 0.
- `speed` (double, optional, nullable, default: 1) — Ajusta a velocidade da voz. O valor padrão é 1.0; valores menores que 1.0 desaceleram a fala, e valores maiores que 1.0 a aceleram.

### PronunciationDictionaryVersionLocatorRequestModel

- `pronunciation_dictionary_id` (string, required) — O ID do dicionário de pronúncia.
- `version_id` (string, optional, nullable) — O ID da versão do dicionário de pronúncia. Se não for informado, a versão mais recente será usada.

### EffectsSpec-Input

Efeitos de áudio aplicados à fala gerada: uma predefinição de filtro, distância percebida, um ambiente de reverberação, uma camada de ruído de fundo e panoramização estéreo. Deixe todos os campos com os valores padrão para obter áudio sem processamento.

- `filter_preset_id` (string, optional, nullable) — ID de uma predefinição de filtro que modifica o timbre da voz, como `phone` ou `old_radio`. Liste IDs válidos com `GET /v1/audio-effects/catalog`.
- `distance` (double, optional, default: 0) — A distância em que o falante parece estar do microfone, de 0 (próximo, sem alteração) a 1 (distante). Valores mais altos atenuam as frequências graves e agudas e, quando um ambiente é definido, deslocam o equilíbrio da voz seca para a reverberação.
- `environment_id` (string, optional, nullable) — ID de um ambiente de reverberação que insere a voz em um espaço, como `small_room` ou `hall`. Liste IDs válidos com `GET /v1/audio-effects/catalog`. A reverberação é renderizada em estéreo e adiciona uma cauda de até vários segundos após o fim da fala.
- `background_noise_id` (string, optional, nullable) — ID de uma camada de ruído de fundo reproduzida em loop sob a voz, como `cafe` ou `keyboard`. Liste IDs válidos com `GET /v1/audio-effects/catalog`.
- `send_level` (double, optional, default: 1) — Quanto da voz é enviado para a reverberação, de 0 (nada) a 1 (total). Só se aplica quando `environment_id` está definido; 0 desativa a reverberação.
- `pan` (double, optional, default: 0) — Posição estéreo da voz, de -1 (totalmente à esquerda), passando por 0 (centro), até 1 (totalmente à direita). Apenas a voz é panoramizada; a reverberação e o ruído de fundo permanecem centralizados.

### CharacterAlignmentResponseModel

- `characters` (list of string, required)
- `character_start_times_seconds` (list of double, required)
- `character_end_times_seconds` (list of double, required)

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)

### ValidationErrorLocItems

## Examples

**Request**

```json
{
  "text": "The first move is what sets everything in motion.",
  "model_id": "eleven_multilingual_v2"
}
```

**SDK Code**

```python
import requests

url = "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb/stream/with-timestamps"

querystring = {"output_format":"mp3_44100_128"}

payload = {
    "text": "The first move is what sets everything in motion.",
    "model_id": "eleven_multilingual_v2"
}
headers = {
    "xi-api-key": "xi-api-key",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb/stream/with-timestamps?output_format=mp3_44100_128';
const options = {
  method: 'POST',
  headers: {'xi-api-key': 'xi-api-key', 'Content-Type': 'application/json'},
  body: '{"text":"The first move is what sets everything in motion.","model_id":"eleven_multilingual_v2"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb/stream/with-timestamps?output_format=mp3_44100_128"

	payload := strings.NewReader("{\n  \"text\": \"The first move is what sets everything in motion.\",\n  \"model_id\": \"eleven_multilingual_v2\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("xi-api-key", "xi-api-key")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb/stream/with-timestamps?output_format=mp3_44100_128")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["xi-api-key"] = 'xi-api-key'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"The first move is what sets everything in motion.\",\n  \"model_id\": \"eleven_multilingual_v2\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb/stream/with-timestamps?output_format=mp3_44100_128")
  .header("xi-api-key", "xi-api-key")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"The first move is what sets everything in motion.\",\n  \"model_id\": \"eleven_multilingual_v2\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb/stream/with-timestamps?output_format=mp3_44100_128', [
  'body' => '{
  "text": "The first move is what sets everything in motion.",
  "model_id": "eleven_multilingual_v2"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'xi-api-key' => 'xi-api-key',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb/stream/with-timestamps?output_format=mp3_44100_128");
var request = new RestRequest(Method.POST);
request.AddHeader("xi-api-key", "xi-api-key");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"text\": \"The first move is what sets everything in motion.\",\n  \"model_id\": \"eleven_multilingual_v2\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "xi-api-key": "xi-api-key",
  "Content-Type": "application/json"
]
let parameters = [
  "text": "The first move is what sets everything in motion.",
  "model_id": "eleven_multilingual_v2"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb/stream/with-timestamps?output_format=mp3_44100_128")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```