Vozes e áudio
Navegue pelas vozes, troque e substitua vozes, crie novas vozes, duble vídeos e separe, mixe e transcreva áudio em TypeScript com o SDK do Nodaro.
client.voices trabalha com vozes da ElevenLabs: lista e pesquisa vozes, troca a voz de uma gravação, dá uma nova voz a cada falante, cria novas vozes e dubla áudio e vídeo para outros idiomas. client.audio oferece os blocos de áudio separadamente: separação, isolamento de voz, efeitos, mixagem, volume, junção e transcrição. Todo método de geração retorna um jobId; consulte-o periodicamente com client.jobs.getStatus(). Os métodos chamam a API REST de voz e mídia.
Métodos
| Método | O que faz |
|---|---|
voices.list() | Lista as vozes prontas |
voices.searchLibrary(params?) | Pesquisa a Biblioteca de vozes da comunidade |
voices.libraryFacets(params?) | Conta as vozes da Biblioteca de vozes para cada valor de filtro |
voices.listFavorites(), favorite(input) e unfavorite(voiceId) | Lista, marca e desmarca as suas vozes favoritas |
voices.listClones() | Lista seus clones de voz existentes |
voices.deleteClone(id) | Exclui um dos seus clones de voz |
voices.createClone() e createCloneFromFile() | Descontinuados |
voices.change(input) | Substitui a voz em uma gravação ou em um vídeo |
voices.recast(input) | Dá uma voz diferente a cada falante |
voices.analyze(input) | Detecta os falantes antes de uma troca de vozes |
voices.exportMix(input) | Renderiza um vídeo a partir de stems de voz mixados |
voices.design(input) | Cria uma nova voz a partir de uma descrição |
voices.remix(input) | Fala um texto em uma voz que você descreve |
voices.dub(input) | Dubla áudio ou vídeo para outro idioma |
voices.textToDialogue(input) | Dá voz a um roteiro com vários falantes em um único arquivo de áudio |
dubbing.get(jobId) | Lê uma dublagem pronta: as falas, os idiomas e os falantes |
dubbing.captions(jobId, options) | Exporta as legendas de uma dublagem como SRT ou WebVTT |
dubbing.addLanguage(jobId, input) | Adiciona um idioma a uma dublagem pronta |
audio.separate(input) | Divide uma faixa em stems |
audio.isolate(input) | Mantém a voz principal e remove o ruído |
audio.applyFx(input) | Adiciona reverberação, eco, telefone ou megafone |
audio.mix(input) | Sobrepõe várias faixas em uma só |
audio.adjustVolume(input) | Muda o nível, normaliza ou aplica fade |
audio.pitchTempo(input) | Muda o tom, ou altera o andamento sem mudar o tom |
audio.combine(input) | Junta segmentos de áudio em sequência |
audio.transcribe(input) | Transforma fala em texto, com os tempos das palavras |
client.voices: vozes
voices.list()
Lista as vozes prontas da ElevenLabs (GET /v1/voices). Quando o servidor não tem uma chave da ElevenLabs configurada, ele retorna, em vez disso, um conjunto selecionado.
list(params?: { model?: string }): Promise<Voice[]>Com model definido como um modelo de fala Gemini (gemini-3-8-flash-lite-tts, gemini-3-8-flash-tts, gemini-3-1-flash-tts ou gemini-2-5-pro-tts), ele lista as vozes próprias desse modelo. Um modelo Gemini fala só essas vozes, então a voice em text-to-speech precisa ser uma delas. O voice_id e o name de cada linha são o nome da voz. Nos modelos 3.8, use_case diz para que a voz serve, por exemplo podcast ou storyteller. Qualquer outro modelo, ou nenhum, lista as vozes prontas.
const voices = await client.voices.list()
const geminiVoices = await client.voices.list({ model: "gemini-3-8-flash-tts" })Em uma implantação que serve as prévias de voz pelo próprio host, o preview_url de cada voz, aqui e em searchLibrary(), é um caminho do mesmo site (/v1/voices/<id>/preview?…), em vez do endereço do provedor. Resolva-o a partir da origem da API para reproduzi-lo. Veja Prévias de voz servidas pelo próprio host da implantação.
voices.searchLibrary(params?)
Pesquisa a Biblioteca de vozes da comunidade (GET /v1/voices/library). Todos os parâmetros são opcionais, e valores vazios são omitidos para que os padrões do servidor se apliquem. hasMore, na resposta, indica se existe outra página.
searchLibrary(params?: VoiceLibraryParams): Promise<{ voices: Voice[]; hasMore: boolean }>Propriedade
Tipo
const { voices, hasMore } = await client.voices.searchLibrary({ search: "deep", language: "en" })
const voice = voices[0]
await client.nodes.run("text-to-speech", {
text: "Hello!",
voice: voice.voice_id,
voiceType: "library",
...(voice.recommendedProvider ? { provider: voice.recommendedProvider } : {}),
})Cada voz pode trazer duas indicações sobre os modelos de fala em que foi verificada:
recommendedProvideré o melhor modelo para a voz. Apps sem um seletor de modelo devem enviá-lo comoproviderpara o Texto para fala, para que a voz soe como a prévia dela na biblioteca.verifiedProviderslista todos os modelos em que a voz foi verificada. Apps com um seletor de modelo devem substituir a escolha do usuário só quando ela não estiver nessa lista.
As duas dicas seguem a ordem ElevenLabs v4, ElevenLabs v3, ElevenLabs v4 Turbo, Turbo v2.5 e, por fim, Multilingual v2. recommendedProvider é a primeira entrada de verifiedProviders. Verifique se um modelo está na lista, nunca compare com um conjunto fixo de valores: um modelo de fala adicionado depois entra na lista quando é lançado. As duas dicas só citam modelos que a instalação oferece. Uma voz sem nenhum modelo verificado ali não traz nenhum dos dois campos, então mantenha o modelo atual do usuário.
Cada voz também traz o que a biblioteca diz sobre o som e os idiomas dela, então um cartão pode mostrar “Cute · Spanish” sem uma segunda chamada:
descriptiveé o tom da biblioteca em uma palavra, comocalm,deepoucute, ou""quando ela não informa nenhum. É o valor que um filtrodescriptivesrecebe. Os valores conhecidos sãoVOICE_LIBRARY_DESCRIPTIVES, em@nodaro/shared/pipeline.languageelocalesão o idioma principal no código da biblioteca (en,he) e a sua localidade (en-US), ou""quando não informados.verifiedLanguageslista todos os códigos de idioma em que a voz foi verificada, o principal primeiro. O filtrolanguageé comparado com essa lista: uma voz em inglês verificada em espanhol aparece emlanguage: "es".
Os valores de use_cases são VOICE_LIBRARY_USE_CASES, em @nodaro/shared/pipeline. Os dois filtros repassam o valor como foi enviado, então um valor que a biblioteca adicionar depois funciona antes de entrar na lista. Servidores mais antigos não enviam os campos novos.
voices.libraryFacets(params?)
Conta as vozes da Biblioteca de vozes para cada grupo (use_cases), tom (descriptives), idioma, gênero, idade, sotaque e categoria, para os filtros que você tem (GET /v1/voices/library/facets). Uma chamada pública, sem créditos, preenche uma tela inteira de seleção: uma contagem em cada grupo, e só os tons e os idiomas que têm vozes.
libraryFacets(params?: VoiceLibraryFacetsParams): Promise<VoiceLibraryFacets>params são os filtros de searchLibrary(), sem paginação nem ordenação: search, gender, age, accent, language, category, use_cases, descriptives e featured.
{
total: 681, // voices matching every filter sent
use_cases: [{ value: "characters_animation", count: 681 }, { value: "social_media", count: 930 }, …],
languages: [{ value: "en", count: 681 }, { value: "es", count: 496 }, …],
descriptives: [{ value: "confident", count: 73 }, { value: "casual", count: 64 }, …],
genders: […], ages: […], accents: […], categories: […],
approximate: false,
updatedAt: "2026-11-09T06:00:00.000Z",
}totalaplica todos os filtros. As contagens de cada faceta aplicam todos os filtros, menos o da própria faceta, então um cliente pode mostrar a contagem de todos os grupos com um deles escolhido. Os valores sem vozes ficam de fora. As listas são ordenadas pela contagem e depois pelo valor, e os valores têm a grafia da própria biblioteca: envie-os de volta como filtros.languagesconta uma voz em cada idioma em que ela foi verificada, então essas contagens somam mais quetotal.- As contagens vêm da cópia da biblioteca que a própria plataforma lê periodicamente.
updatedAtdiz quando, então uma contagem pode ficar algumas vozes atrás da listagem. Comsearch, as contagens são uma estimativa mínima eapproximateétrue. - Nos primeiros minutos depois que uma implantação lê a biblioteca pela primeira vez, o método lança um erro com
503 voice_library_warming. Tente de novo depois dos segundos deRetry-After. Uma implantação sem chave de fala responde contagens zero comkeyMissing: true.
const facets = await client.voices.libraryFacets({ use_cases: "characters_animation", language: "en" })
const tones = facets.descriptives // only tones that have voices, most first
const hebrew = facets.languages.find((l) => l.value === "he")?.count ?? 0voices.listClones()
Lista seus clones de voz (GET /v1/voice-clones). Os clones feitos antes de a clonagem ser descontinuada continuam funcionando como IDs de voz em qualquer lugar que aceite uma voz. A única exceção à descontinuação é um clone único para uma única requisição no Gemini 3.8 Flash (replica em nodes.textToSpeech e em um falante de textToDialogue), que nunca é salvo como voz.
listClones(): Promise<VoiceClone[]>const clones = await client.voices.listClones()voices.deleteClone(id)
Exclui um dos seus clones de voz (DELETE /v1/voice-clones/:id).
deleteClone(id: string): Promise<void>Propriedade
Tipo
await client.voices.deleteClone(cloneId)voices.listFavorites(), favorite(input) e unfavorite(voiceId)
Lista, marca e desmarca as suas vozes favoritas (GET /v1/voices/favorites, PUT e DELETE /v1/voices/favorites/:voiceId). Uma favorita é uma voz pronta, uma voz da Biblioteca de vozes ou um dos seus clones. Ela é marcada em qualquer cliente e lida por todos eles, das mais recentes para as mais antigas.
listFavorites(): Promise<VoiceFavorite[]>
favorite(input: VoiceFavoriteInput): Promise<VoiceFavorite>
unfavorite(voiceId: string): Promise<void>Propriedade
Tipo
- Uma favorita traz o
voiceIde ovoiceTypeque uma execução de texto para fala recebe comovoiceevoiceType, e onamee opreviewUrlde quando foi marcada. Uma lista de favoritos aparece sem uma segunda consulta. - As duas gravações são idempotentes. Marcar de novo uma voz já marcada atualiza o instantâneo, e desmarcar uma voz que não está lá dá certo.
- Acima de 500 favoritas,
favorite()lança um erro com409 limit_reached. - Apps OAuth precisam de
assets:readpara a lista e deassets:writepara as gravações.
const { voices } = await client.voices.searchLibrary({ search: "calm narrator", language: "en" })
const pick = voices[0]
await client.voices.favorite({ voiceId: pick.voice_id, voiceType: "library", name: pick.name, previewUrl: pick.preview_url })
const favorites = await client.voices.listFavorites()
await client.nodes.run("text-to-speech", { text: "Hello!", voice: favorites[0].voiceId, voiceType: favorites[0].voiceType })
await client.voices.unfavorite(pick.voice_id)voices.createClone() e createCloneFromFile()
A clonagem de voz não é mais oferecida no Nodaro. Ela foi descontinuada em setembro de 2026. Os dois métodos continuam no cliente e estão marcados como obsoletos. Eles falham com um NodaroError cujo code é voice_cloning_retired, com status 410. Para uma nova voz personalizada, use design().
client.voices: modificador de voz
voices.change(input)
Substitui a voz de uma gravação, ou de um vídeo inteiro com fala, por outra voz (POST /v1/voice-changer), como faz o nó Modificador de voz. Com videoUrl, o servidor extrai o áudio do vídeo, troca a voz e coloca a nova voz de volta na imagem original.
change(input: {
voiceId: string
audioUrl?: string
videoUrl?: string
model?: string
stability?: number
similarityBoost?: number
style?: number
useSpeakerBoost?: boolean
seed?: number
removeBackgroundNoise?: boolean
}): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.voices.change({
videoUrl: "https://example.com/talking.mp4",
voiceId: "Aria",
})
// the finished job's output_data has videoUrl and audioUrlvoices.recast(input)
Dá uma voz diferente a cada falante detectado em uma gravação (POST /v1/voice-changer-pro), como faz o nó Modificador de voz Pro. O método roda no Nodaro Cloud, custa créditos e é executado como uma tarefa.
recast(input: VoiceChangerProInput): Promise<{ jobId: string }>Propriedade
Tipo
Cada entrada de orderedVoices é uma destas opções:
- Um ID de voz: o nome de uma voz pronta, como
"Rachel", ou um ID de voz da ElevenLabs. null: uma posição que mantém a voz original. Esse falante mantém a própria voz, enquanto os falantes seguintes continuam tendo a voz trocada. As posições que mantêm a voz original não custam nada, porque só os falantes com voz trocada são cobrados.- Um objeto com
voiceIde as configurações desse falante:stability,similarityBoostestyle, de 0 a 1,useSpeakerBooste umseedde 0 a 4.294.967.295.volumeModeé"match"(o padrão, o nível do falante original),"normalize"ou"manual", comvolumeem porcentagem de 0 a 200.engine: "v3"fala a linha de novo a partir da transcrição com o ElevenLabs v3, com suporte a[audio tags], em vez de converter a fala gravada.engine: "v4"faz o mesmo com o ElevenLabs v4, aceita qualquerstabilityde 0 a 1 e aplicasimilarityBoost.
O falante 0 recebe orderedVoices[0], o falante 1 recebe orderedVoices[1], e assim por diante. Os falantes depois da última entrada mantêm a própria voz. A voz e a música são sempre separadas primeiro. preserveBackground só decide se a música volta.
voiceFx.preset é um ambiente de reverberação (room, bathroom, car, hall, concert-hall, church, cave, arena ou outdoor), telephone, megaphone, echo ou custom. As predefinições de reverberação usam wetDryMix de 0 a 100. echo e custom usam delayMs de 20 a 2.000 e decay de 0 a 1.
// Recast speakers 0 and 2, and keep speaker 1's own voice
const { jobId } = await client.voices.recast({
audioUrl: "https://example.com/panel.mp3",
orderedVoices: ["Rachel", null, "Aria"],
})
// Repeatable voices, a hall reverb, and finer separation
const { jobId: tuned } = await client.voices.recast({
audioUrl: "https://example.com/dialogue.mp3",
orderedVoices: [
{ voiceId: "Rachel", seed: 12345, stability: 0.6 },
{ voiceId: "Aria", seed: 67890, volumeMode: "manual", volume: 120 },
],
voiceFx: { preset: "hall", wetDryMix: 35 },
separationQuality: "best",
})No modo de vídeo, o output_data da tarefa concluída tem videoUrl e audioUrl.
voices.analyze(input)
Detecta os falantes de um clipe sem trocar as vozes (POST /v1/voice-changer-pro/analyze). O método separa a voz da música uma vez e descobre quem fala quando. Ele roda no Nodaro Cloud, com preço fixo, como uma tarefa.
analyze(input: {
audioUrl?: string
videoUrl?: string
separationQuality?: "fast" | "best"
suggestTitle?: boolean
}): Promise<{ jobId: string }>Propriedade
Tipo
O output_data da tarefa concluída é um VcpAnalysis: os vocalsUrl e backgroundUrl separados, os speakers detectados (cada um com id, os segments de tempo, firstStartSec, wordCount e um snippet de texto), languageCode com languageProbability e suggestedTitle, quando pedido. Passe-o como analysis para cada recast() seguinte, para que a troca de vozes reaproveite as faixas separadas e não pague de novo pela detecção.
voices.exportMix(input)
Renderiza o vídeo final a partir de um conjunto mixado de stems (POST /v1/voice-changer-pro/export). É a última etapa depois de recast({ output: "stems" }). O método roda no Nodaro Cloud, com preço fixo, como uma tarefa.
exportMix(input: {
videoUrl: string
tracks: Array<{ url: string; gain: number; muted: boolean; kind?: "voice" | "background" }>
voiceFx?: { preset: AudioFxPreset; wetDryMix?: number; delayMs?: number; decay?: number }
}): Promise<{ jobId: string }>Propriedade
Tipo
O fluxo interativo analisa uma vez, troca as vozes gerando stems e depois mixa e renderiza. Veja o fluxo com uma pequena função auxiliar de consulta periódica:
import type { VcpAnalysis } from "@nodaro/sdk"
async function outputOf(jobId: string): Promise<any> {
for (;;) {
const { data } = await client.jobs.getStatus(jobId)
if (data.status === "completed") return data.output_data
if (data.status === "failed" || data.status === "cancelled") throw new Error(data.error_message ?? data.status)
await new Promise((resolve) => setTimeout(resolve, 2_000))
}
}
const { jobId: analyzeJob } = await client.voices.analyze({ videoUrl })
const analysis = (await outputOf(analyzeJob)) as VcpAnalysis
const { jobId: recastJob } = await client.voices.recast({
videoUrl,
orderedVoices: ["Rachel", null, "Aria"],
output: "stems",
analysis,
})
const stems = await outputOf(recastJob)
const { jobId: exportJob } = await client.voices.exportMix({
videoUrl,
tracks: [
{ url: stems.tracks[0].url, gain: 100, muted: false },
{ url: stems.tracks[1].url, gain: 90, muted: false },
{ url: stems.backgroundUrl, gain: 70, muted: false, kind: "background" },
],
voiceFx: { preset: "hall", wetDryMix: 25 },
})
const { videoUrl: finalVideo } = await outputOf(exportJob)Os ganhos, os mudos e o efeito são aplicados quando o vídeo é renderizado, e a imagem é copiada como está. Por isso, a exportação corresponde à sua prévia, e você pode mudar a mixagem quantas vezes quiser antes de exportar. Uma mixagem com todas as faixas no mudo é recusada com um 400.
client.voices: criar e traduzir
voices.design(input)
Cria uma nova voz sintética a partir de uma descrição em texto (POST /v1/voice-design), como faz o nó Design de voz. A tarefa concluída traz uma prévia em áudio e o ID da nova voz, que você pode usar em qualquer lugar que aceite uma voz.
design(input: {
text: string
voiceDescription: string
model?: string
loudness?: number
guidanceScale?: number
seed?: number
quality?: number
shouldEnhance?: boolean
userPrompt?: string
}): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.voices.design({
text: "Welcome back. Tonight we follow the river north, into the mountains where the story began.",
voiceDescription: "A calm, deep voice of an older male narrator with a slight British accent",
})voices.remix(input)
Fala um texto em uma voz descrita em palavras simples, sem criar uma voz (POST /v1/voice-remix), como faz o nó Remix de voz.
remix(input: { text: string; voiceDescription: string; userPrompt?: string }): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.voices.remix({
text: "Your order is on its way.",
voiceDescription: "A cheerful young woman, fast and upbeat",
})voices.dub(input)
Dubla um áudio, ou um vídeo inteiro, para outro idioma, mantendo a voz de cada falante (POST /v1/dubbing), como faz o nó Dublagem. A dublagem de um vídeo retorna output_data.videoUrl, o clipe dublado, e output_data.audioUrl, só a faixa dublada.
dub(input: DubbingInput): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.voices.dub({
videoUrl: "https://example.com/interview.mp4",
targetLanguage: "es",
numSpeakers: 2,
})O preço depende dos minutos do trecho dublado, com um mínimo de 1 minuto. Um trecho tem no máximo 30 minutos; por isso, use startTime e endTime em fontes mais longas.
client.dubbing.create() é a mesma chamada. Quando a dublagem terminar, leia-a de volta com client.dubbing.
Um sourceUrl é buscado para você pelo serviço de dublagem, então é uma importação desse link, sob a declaração de direitos de conteúdo. Passe o confirmationId que contentRights.confirm() respondeu para ele. Sem ele, uma implantação que exige uma confirmação recusa a dublagem com 403 antes de a tarefa ser criada. Uma chave ou um agente cuja conta tem uma autorização permanente (contentRights.authorize()) não precisa de nenhuma.
voices.textToDialogue(input)
Dá voz a um roteiro com vários falantes em um único arquivo de áudio (POST /v1/text-to-dialogue), como faz o nó Texto para diálogo com o ElevenLabs Dialogue v3 ou o ElevenLabs Dialogue v4.
textToDialogue(input: {
dialogue: Array<{ text: string; voice: string; styleDirection?: string }>
provider?: DialogueProvider
speakers?: Array<{ voice: string; styleDirection?: string; pace?: string; accent?: string; audioProfile?: string }>
fillerWords?: boolean
outputFormat?: TtsOutputFormat
stability?: number
similarityBoost?: number
languageCode?: string
seed?: number
applyTextNormalization?: "auto" | "on" | "off"
}): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.voices.textToDialogue({
dialogue: [
{ text: "Did you hear that?", voice: "Rachel" },
{ text: "[whispers] Stay behind me.", voice: "Callum" },
],
})Diálogo com Gemini. provider também pode ser um modelo de fala Gemini (gemini-3-8-flash-lite-tts, gemini-3-8-flash-tts, gemini-3-1-flash-tts ou gemini-2-5-pro-tts), para um ou dois falantes. A voice de cada fala é uma das vozes próprias do modelo (voices.list({ model })), com no máximo duas vozes diferentes e 10.000 caracteres no total. No 3.8, o styleDirection de uma fala diz como ela é falada, e fillerWords: true adiciona palavras de preenchimento entre dois falantes. No 3.1 e no 2.5, speakers dá a cada voz o estilo, o ritmo, o sotaque e o perfil de áudio. Uma voz ou direção que o modelo recusa é um 400 antes de qualquer cobrança. Um diálogo com Gemini é cobrado pela tarifa por caractere do modelo sobre todas as falas e não retorna transcript. outputFormat escolhe o arquivo: mp3_44100_128 (o padrão), mp3_44100_192 ou wav_24000.
Um roteiro pode ter no máximo 5.000 caracteres no Dialogue v3 e 10.000 no Dialogue v4, e menos de 2.000 dão a melhor qualidade. Ele pode usar no máximo 10 vozes diferentes. Vozes da biblioteca, vozes criadas com design de voz e clones existentes funcionam, combinados como você quiser. O output_data.audioUrl da tarefa concluída é o arquivo. Nos dois modelos, output_data.transcript traz os tempos: words[] com startMs, endMs e speaker, e uma entrada de segments[] por fala, em que speaker é a voice da fala. Passe transcript.words para addCaptions com autoTranscribe: false para legendar o diálogo sem uma segunda transcrição.
client.dubbing
Lê uma dublagem depois de pronta: as falas do áudio original, cada idioma com as falas dele, os falantes e as legendas de cada idioma. Você também pode adicionar um idioma a ela. Só a conta que fez uma dublagem pode lê-la; o id de tarefa de qualquer outra pessoa é um NotFoundError. As leituras são gratuitas. Um app OAuth precisa de assets:read para elas, e de assets:write para adicionar um idioma, o que é cobrado. Uma recusa é um NodaroError cujo code é um DubbingErrorCode. client.dubbing.create(input) começa uma dublagem, a mesma chamada que voices.dub(). Também pode ser importado como @nodaro/sdk/dubbing. As rotas estão descritas em Voz e mídia.
dubbing.get(jobId)
A estrutura da dublagem (GET /v1/dubbing/:jobId). jobId é a tarefa que criou a dublagem, ou a tarefa de um idioma adicionado depois.
get(jobId: string): Promise<DubbingStructure>
interface DubbingStructure {
jobId: string
durationSec: number | null
source: { language: string | null; segments: DubbingSourceSegment[] } | null
languages: DubbingLanguage[] // { code, jobId, status, segments }
speakers: DubbingSpeaker[] // { id, name, voice, segmentCount }
capabilities: DubbingCapabilities // { editSegments, regenerate, setSpeakerVoice, render, addLanguage, captions }
addLanguage: DubbingAddLanguagePrice // { billableMinutes, creditId, creditIdByLanguage }
}O status de um idioma é processing, completed, stale ou failed, e os segments dele só são preenchidos quando ele está completed ou stale. Cada segmento tem start e end em segundos, text, e sourceSegmentId e sourceText onde a dublagem os guarda. Ofereça uma ação só quando a flag dela em capabilities for true; editSegments, regenerate, setSpeakerVoice e render são false hoje. A chamada recusa com dubbing_not_ready (409) até a dublagem terminar, dubbing_failed (422) quando ela não foi feita, not_a_dubbing_job (422) para outro tipo de tarefa e dubbing_unavailable (410) quando o serviço de dublagem não a guarda mais.
dubbing.captions(jobId, options)
As legendas de um idioma, ou da fala original com language: "source", como o texto de um arquivo SubRip ("srt", o padrão) ou WebVTT ("vtt") (GET /v1/dubbing/:jobId/captions).
captions(jobId: string, options: { language: string; format?: "srt" | "vtt" }): Promise<string>Um idioma é exportado quando o status dele é completed ou stale. A chamada recusa com dubbing_language_not_found (404), dubbing_language_processing (409) ou dubbing_captions_unavailable (422).
const { jobId } = await client.dubbing.create({ videoUrl, targetLanguage: "es" })
// poll client.jobs.get(jobId) until the job completes, then:
const dub = await client.dubbing.get(jobId)
for (const language of dub.languages) {
if (language.status !== "completed") continue
const srt = await client.dubbing.captions(jobId, { language: language.code })
}
const original = await client.dubbing.captions(jobId, { language: "source" })dubbing.addLanguage(jobId, input)
Adiciona um idioma a uma dublagem pronta (POST /v1/dubbing/:jobId/languages) e responde a tarefa que o entrega.
addLanguage(jobId: string, input: { targetLanguage: string; confirmationId?: string }): Promise<{ jobId: string }>Ofereça a chamada só quando get(jobId).capabilities.addLanguage for true. Ela é cobrada por minuto iniciado da dublagem, pelo preço que get(jobId).addLanguage indica. Uma dublagem em hebraico recebe o idioma no mesmo projeto, então nada é enviado de novo. Qualquer outra dublagem o recebe como uma nova dublagem da mesma origem, com as mesmas configurações. A chamada recusa com dubbing_language_exists (409) para um idioma que a dublagem já tem ou está fazendo, e unreadable_dubbing_source (422) quando a origem não pode mais ser lida.
const dub = await client.dubbing.get(jobId)
if (dub.capabilities.addLanguage) {
const added = await client.dubbing.addLanguage(jobId, { targetLanguage: "de" })
// poll client.jobs.get(added.jobId); get(jobId) then lists "de".
}client.audio
Os blocos de áudio que o Modificador de voz Pro usa internamente, disponíveis um a um. Todo método retorna um jobId.
audio.separate(input)
Divide uma faixa em stems (POST /v1/audio-separation), como faz o nó Separação de áudio.
separate(input: { audioUrl: string; mode?: "vocal_instrumental" | "stems"; quality?: "auto" | "fast" | "best" }): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.audio.separate({ audioUrl: songUrl })
// output: vocalUrl and instrumentalUrl, or one URL per stem in stems modeaudio.isolate(input)
Mantém a voz principal e remove o ruído de fundo (POST /v1/audio-isolation), como faz o nó Extrator de voz.
isolate(input: { audioUrl: string }): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.audio.isolate({ audioUrl: interviewUrl })audio.applyFx(input)
Adiciona um efeito de reverberação, eco, telefone ou megafone (POST /v1/audio-fx), como faz o nó Efeitos de áudio. As predefinições são as mesmas do voiceFx da troca de vozes.
applyFx(input: {
audioUrl: string
preset?: AudioFxPreset
mix?: number
delayMs?: number
decay?: number
eqLow?: number
eqHigh?: number
}): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.audio.applyFx({ audioUrl: lineUrl, preset: "telephone" })audio.mix(input)
Sobrepõe várias faixas em uma só (POST /v1/mix-audio), como faz o nó Mixar áudio.
mix(input: {
audioUrls: string[]
trackVolumes?: number[]
duck?: { under: number; amount?: number; thresholdDb?: number; ratio?: number; attackMs?: number; releaseMs?: number }
endAt?: "longest" | "voice"
}): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.audio.mix({ audioUrls: [voiceUrl, musicUrl], trackVolumes: [100, 35] })
// The music dips under the voice (track 0) while it speaks.
const ducked = await client.audio.mix({ audioUrls: [voiceUrl, musicUrl], duck: { under: 0, amount: 80 } })audio.adjustVolume(input)
Muda o nível de um arquivo de áudio, ou do áudio de um vídeo (POST /v1/adjust-volume), como faz o nó Ajustar volume.
adjustVolume(input: {
audioUrl?: string
videoUrl?: string
volume?: number
normalize?: boolean
fadeIn?: number
fadeOut?: number
}): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.audio.adjustVolume({ audioUrl: musicUrl, volume: 60, fadeOut: 3 })audio.pitchTempo(input)
Muda o tom, ou altera o andamento sem mudar o tom (POST /v1/pitch-tempo), como faz o nó Tom e andamento. Informe exatamente um entre audioUrl e videoUrl. Um vídeo mantém a imagem, e o andamento dele fica em 1.
pitchTempo(input: {
audioUrl?: string
videoUrl?: string
semitones?: number
tempo?: number
preserveFormants?: boolean
}): Promise<{ jobId: string }>Propriedade
Tipo
A execução custa 22 créditos por minuto iniciado da entrada, até 30 minutos.
const { jobId } = await client.audio.pitchTempo({ audioUrl: voiceUrl, semitones: -3 })audio.combine(input)
Junta segmentos de áudio em sequência (POST /v1/combine-audio), como faz o nó Combinar áudio.
combine(input: { segments: Array<{ url: string; startTime?: number; endTime?: number }> }): Promise<{ jobId: string }>Propriedade
Tipo
const { jobId } = await client.audio.combine({
segments: [{ url: introUrl }, { url: episodeUrl, startTime: 4 }, { url: outroUrl }],
})audio.transcribe(input)
Transforma em texto a fala de um arquivo de áudio ou de vídeo (POST /v1/transcribe), como faz o nó Transcrever.
transcribe(input: {
audioUrl: string
provider?: "elevenlabs-stt" | "incredibly-fast-whisper" | "whisper" | "nemotron-3-5-transcribe"
language?: string
diarize?: boolean
tagAudioEvents?: boolean
wordTimestamps?: boolean
targetLanguage?: string
confirmationId?: string
}): Promise<{ jobId: string }>Propriedade
Tipo
Um audioUrl que aponta para a página de um vídeo em uma plataforma social é uma importação desse link: o som dele é buscado primeiro. Passe o confirmationId que contentRights.confirm() respondeu para esse link. Sem ele, uma implantação que exige uma confirmação recusa a requisição com 403 antes de a tarefa ser criada. Uma chave ou um agente cuja conta tem uma autorização permanente (contentRights.authorize()) não precisa de nenhuma. Um link direto de arquivo não precisa de nenhuma.
provider | Tempos das palavras | Observações |
|---|---|---|
elevenlabs-stt | Sempre | O único mecanismo que respeita diarize e tagAudioEvents. |
incredibly-fast-whisper | Só com wordTimestamps: true | Sem a opção, a tarefa é concluída e cobrada, com segmentos de frase e uma lista words vazia. |
whisper | Nunca | Só segmentos de frase. wordTimestamps: true é recusado com 400 validation_error antes de qualquer gasto de créditos. |
nemotron-3-5-transcribe | Só com wordTimestamps: true | O Nemotron 3.5 Transcribe detecta o idioma sozinho (language não é usado) e acrescenta um speaker por palavra. O único mecanismo que traduz: targetLanguage retorna uma tradução, sem os tempos das palavras. Junto com wordTimestamps: true, ou em outro mecanismo, é um 400 validation_error. Cobrado por minuto iniciado do áudio: medido antes e cobrado pela duração que o modelo decodificou. Aceita um link https direto para o arquivo, de até 60 minutos e 200 MB. |
Omitir provider usa whisper; por isso, wordTimestamps: true sem um provider também recebe o 400. Para obter os tempos das palavras, indique elevenlabs-stt, ou incredibly-fast-whisper ou nemotron-3-5-transcribe com wordTimestamps: true. As legendas cinéticas precisam deles.
const { jobId } = await client.audio.transcribe({ audioUrl: talkUrl, provider: "elevenlabs-stt" })O output_data da tarefa concluída é um TranscribeJobOutput:
| Campo | Unidade | Conteúdo |
|---|---|---|
text | A transcrição inteira em uma única string. | |
language | O código do idioma detectado ou pedido. | |
words | milissegundos | Uma entrada por palavra: { text, startMs, endMs, speaker? }. Fica vazia quando os tempos das palavras não foram pedidos ao mecanismo. |
json | milissegundos | A transcrição normalizada, { version, language, words, segments? }, que client.edit aceita. |
segments | segundos | Os intervalos brutos das frases, só dos mecanismos mais antigos. elevenlabs-stt não retorna nenhum; por isso, leia words. |
words tem exatamente o formato das captions que client.media.addCaptions() aceita; assim, você pode corrigir uma transcrição e gravá-la como legendas no vídeo.
Perguntas frequentes
Como troco a voz de um vídeo com o SDK do Nodaro?
Chame client.voices.change com o videoUrl e um voiceId. O servidor substitui a voz e a coloca de volta no vídeo original. Consulte a tarefa periodicamente até obter output_data.videoUrl.
Como dou uma voz diferente a cada falante de uma gravação?
Chame client.voices.recast com orderedVoices, uma entrada por falante detectado, em ordem. Use null para um falante que mantém a própria voz. O método roda no Nodaro Cloud.
Ainda posso clonar uma voz com o SDK?
Não. A clonagem de voz foi descontinuada em setembro de 2026, e createClone agora falha com 410 voice_cloning_retired. Os clones existentes continuam funcionando. Em vez disso, crie uma nova voz com client.voices.design.
Qual mecanismo de transcrição retorna os tempos das palavras?
elevenlabs-stt sempre retorna os tempos das palavras. incredibly-fast-whisper só os retorna com wordTimestamps definido como true, e whisper nunca os retorna.
Páginas relacionadas
Mídia e uploads
Edição
Voz e mídia
Modificador de voz Pro
Transcrever
Última atualização
Mídia e uploads
Envie arquivos ao Nodaro, liste sua biblioteca, importe vídeos de links, corte clipes, embuta legendas e componha imagens e vídeos em TypeScript.
Edição
Edite podcasts e vídeos longos em TypeScript. Enxugue um episódio, corte clipes, capítulos ou um trailer, sincronize e troque câmeras e renderize uma EDL.