voxcpm2-tts-endpoint

VoxCPM2 — Hugging Face Inference Endpoint (custom handler)

Deploy do openbmb/VoxCPM2 (TTS) como endpoint dedicado no HF, com clonagem de voz e voice design.

Arquivos

• handler.py — custom handler (carrega VoxCPM2, gera áudio, retorna WAV em base64).
• requirements.txt — dependências (voxcpm, soundfile, librosa).
• test_client.py — cliente de teste.

Passo a passo

1. Criar o repo do modelo no HF

Crie um repo Model (não Dataset/Space), ex.: seu-usuario/voxcpm2-tts-endpoint. Não precisa subir os pesos — o handler baixa o VoxCPM2 do Hub no startup.

Suba handler.py e requirements.txt na raiz:

pip install -U huggingface_hub
huggingface-cli login
huggingface-cli upload seu-usuario/voxcpm2-tts-endpoint ./handler.py handler.py
huggingface-cli upload seu-usuario/voxcpm2-tts-endpoint ./requirements.txt requirements.txt

(ou pela web: "Add file" → upload os dois arquivos)

2. Criar o endpoint

Em https://endpoints.huggingface.co/ → New endpoint:

• Model repository: seu-usuario/voxcpm2-tts-endpoint
• Instance: GPU — recomendado Nvidia L4 (24GB) ou A10G (24GB). VoxCPM2 (2B) usa ~6–8GB; sobra folga.
• Task / Container: deixe Default. O endpoint detecta o handler.py automaticamente (custom handler).
• Autoscaling: ative scale-to-zero após inatividade pra economizar (cold start ~2–4 min: instala deps + baixa o modelo).
• Deploy.

3. Testar

export HF_ENDPOINT_URL="https://xxxxx.endpoints.huggingface.cloud"
export HF_TOKEN="hf_..."
python test_client.py "Que noticia maravilhosa, conseguimos!" "energetic young Brazilian woman"
# -> out.wav

API

Request (POST, JSON):

{
  "inputs": "Texto em pt-BR.",
  "parameters": {
    "voice_instruction": "energetic young Brazilian woman",
    "cfg_value": 2.0,
    "inference_timesteps": 10,
    "normalize": false,
    "reference_audio_b64": "<wav base64 — opcional, p/ clonar voz>"
  }
}

Response:

{ "sample_rate": 48000, "format": "wav", "duration_sec": 5.1, "audio_b64": "<wav base64>" }

• Voice design: mande só voice_instruction (descrição da voz/emoção, melhor em inglês).
• Clonagem: mande reference_audio_b64 (um wav curto) — clona o timbre e aplica o estilo do voice_instruction.

Notas

• Licença do VoxCPM2: Apache-2.0 (uso comercial liberado).
• O torchcodec (dependência do voxcpm) pode falhar ao carregar no container, mas o VoxCPM usa librosa pra ler a referência — funciona mesmo assim.
• Cold start baixa o modelo (~alguns GB). Pra acelerar, dá pra "duplicar" o repo openbmb/VoxCPM2 e incluir os pesos + handler no mesmo repo (evita download no startup).