GUIA

Uma API de texto para fala em Python: salvar, transmitir e repetir

Uma API de texto para fala na nuvem é o caminho mais curto para dar voz a um script Python: sem baixar modelo, sem GPU, uma solicitação HTTP. Este guia mostra a API de voz da SuperClonica em Python com a biblioteca requests, do primeiro arquivo ao streaming de textos longos e ao tratamento de limites como um script em produção deve fazer.

Você precisa de uma chave: entre na SuperClonica com Google ou GitHub e crie uma na seção de API do seu espaço de trabalho. O plano gratuito dá um minuto de áudio por dia.

Escolher uma voz Ou rodar o motor localmente

Salvar um mp3

Guarde a chave numa variável de ambiente e envie o texto com uma voz e um idioma:

import os, requests; KEY = os.environ["SUPERCLONICA_KEY"]; r = requests.post("https://superclonica.com/api/v1/speech", headers={"Authorization": "Bearer " + KEY}, json={"text": "Olá do Python!", "voice": "F1", "language": "pt", "format": "mp3"}, timeout=120); r.raise_for_status(); open("hello.mp3", "wb").write(r.content)

Sem "format" a resposta vem em Ogg Vorbis, o arquivo menor; wav também está disponível. Uma solicitação aceita até 20 000 caracteres.

Transmitir um texto longo

Com "stream": true o servidor envia o áudio enquanto ele ainda está sendo gerado, então você pode gravá-lo no disco ou mandá-lo para um player desde a primeira parte:

with requests.post("https://superclonica.com/api/v1/speech", headers={"Authorization": "Bearer " + KEY}, json={"text": long_text, "voice": "M2", "language": "pt", "stream": True}, stream=True, timeout=120) as r: r.raise_for_status(); f = open("speech.ogg", "wb"); [f.write(chunk) for chunk in r.iter_content(8192)]; f.close()

Nas nossas medições o primeiro som chegou a partir de 300 ms seja qual for o tamanho do texto, e cerca de 16 000 caracteres foram convertidos em 25,6 segundos.

Vozes e limites

Liste as vozes que a sua chave pode usar; cada item tem um id, um nome, o tipo (stock, own, bought ou catalog) e um idioma:

voices = requests.get("https://superclonica.com/api/v1/voices", headers={"Authorization": "Bearer " + KEY}, timeout=30).json()["items"]

Confira o que resta do seu plano antes de um trabalho grande:

usage = requests.get("https://superclonica.com/api/v1/usage", headers={"Authorization": "Bearer " + KEY}, timeout=30).json(); print(usage["plan"], usage["available_seconds"])

Erros e novas tentativas

Envie um cabeçalho Idempotency-Key com cada solicitação, por exemplo um hash do texto: assim uma solicitação repetida depois de um timeout espera a mesma tarefa, em vez de converter e contar o texto duas vezes.

  • 429: a janela de 10 minutos do plano acabou; espere os segundos de Retry-After e envie de novo.
  • 503: a fila está cheia; espere Retry-After segundos e envie de novo com a mesma chave.
  • 413: o texto é maior do que o seu plano permite numa janela; divida-o.
  • 401: a chave está faltando, errada ou foi apagada.
  • Um texto que falhou não conta no plano.