POST/api/v1/generate/voice-change

Alterar voz

Bearer tokenescopo generate:audio

Conversão de voz (Speech-to-Speech): transforma o timbre do áudio de origem para a voz escolhida, preservando entonação e emoção originais. Responde 202 Accepted com um taskId. Acompanhe o resultado por polling em GET /api/v1/tasks/:id ou via webhook.

Escopo necessário: generate:audio.

Body

Campo	Tipo	Obrigatório?	Valores / restrições	Padrão
`audioUrl`	string	sim	URL HTTPS pública do áudio de origem (MP3 ou WAV)	—
`voice`	string	sim	Slug da voz (mesma lista de `/generate/voice`); case-insensitive	—
`stability`	number	não	0.0–1.0 (estabilidade da voz)	`0.5`
`similarityBoost`	number	não	0.0–1.0 (fidelidade ao timbre)	`0.75`
`callbackUrl`	string	não	HTTPS, host não-privado	—

Vozes disponíveis

aria, roger, sarah, laura, charlie, george, callum, river, liam, charlotte, alice, matilda, will, jessica, eric, chris, brian, daniel, lily, bill

Mesma lista de /generate/voice. Slugs são case-insensitive ("Roger", "ROGER" e "roger" são equivalentes). Valores fora da lista retornam 400 VALIDATION_ERROR.

Detecção de duração

A duração do áudio de origem — base do custo — é detectada automaticamente a partir do arquivo. Se a duração não puder ser determinada (arquivo inacessível, formato não suportado ou cabeçalho inválido), a requisição retorna 400 VALIDATION_ERROR.

Exemplo de request

cURL

curl -X POST https://avatrix.io/api/v1/generate/voice-change \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c-vc-001" \
  -d '{
    "audioUrl": "https://storage.avatrix.io/generated/AMABB58D/audio-769bcb5d-349c-42ed-8532-c5ceacff3230.mp3",
    "voice": "sarah",
    "stability": 0.5,
    "similarityBoost": 0.75
  }'

Resposta — 202

JSON

{ "success": true, "data": { "taskId": "...", "status": "queued" } }

O status: "queued" é só o rótulo de criação. No polling (GET /api/v1/tasks/:id) a task evolui por pending → submitted → processing → completed (com resultUrl do áudio) ou failed. Ver Ciclo de vida da task.

Idempotência

Envie o header Idempotency-Key (opcional, ≤128 chars, TTL 24h) — repetir a mesma chave retorna a resposta original sem novo débito. Concorrência limitada a 20 tasks simultâneas por usuário. Ver Idempotência.

Custo

Cobrança por segundo de áudio: o custo é proporcional à duração detectada do áudio de origem.

Erros relevantes

Código	HTTP	Quando
`VALIDATION_ERROR`	400	campos obrigatórios ausentes, URL não-HTTPS ou privada, formato de áudio não detectável, `voice` inválido, `stability`/`similarityBoost` fora de 0–1
`INSUFFICIENT_CREDITS`	402	saldo insuficiente
`FORBIDDEN`	403	token sem `generate:audio`
`RATE_LIMITED` / `MAX_CONCURRENT_TASKS`	429	rate limit ou 20 tasks simultâneas
`INTERNAL_ERROR`	500	erro interno ao processar a cobrança
`GENERATION_FAILED`	502	falha do provider
`PROVIDER_UNAVAILABLE`	503	provider indisponível

Ver Códigos de erro e Escopos.