NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
SDK para TypeScript

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étodoO 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 como provider para o Texto para fala, para que a voz soe como a prévia dela na biblioteca.
  • verifiedProviders lista 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, como calm, deep ou cute, ou "" quando ela não informa nenhum. É o valor que um filtro descriptives recebe. Os valores conhecidos são VOICE_LIBRARY_DESCRIPTIVES, em @nodaro/shared/pipeline.
  • language e locale são o idioma principal no código da biblioteca (en, he) e a sua localidade (en-US), ou "" quando não informados.
  • verifiedLanguages lista todos os códigos de idioma em que a voz foi verificada, o principal primeiro. O filtro language é comparado com essa lista: uma voz em inglês verificada em espanhol aparece em language: "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",
}
  • total aplica 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.
  • languages conta uma voz em cada idioma em que ela foi verificada, então essas contagens somam mais que total.
  • As contagens vêm da cópia da biblioteca que a própria plataforma lê periodicamente. updatedAt diz quando, então uma contagem pode ficar algumas vozes atrás da listagem. Com search, as contagens são uma estimativa mínima e approximate é 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 de Retry-After. Uma implantação sem chave de fala responde contagens zero com keyMissing: 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 ?? 0

voices.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 voiceId e o voiceType que uma execução de texto para fala recebe como voice e voiceType, e o name e o previewUrl de 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 com 409 limit_reached.
  • Apps OAuth precisam de assets:read para a lista e de assets:write para 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 audioUrl

voices.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 voiceId e as configurações desse falante: stability, similarityBoost e style, de 0 a 1, useSpeakerBoost e um seed de 0 a 4.294.967.295. volumeMode é "match" (o padrão, o nível do falante original), "normalize" ou "manual", com volume em 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 qualquer stability de 0 a 1 e aplica similarityBoost.

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 mode

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

providerTempos das palavrasObservações
elevenlabs-sttSempreO único mecanismo que respeita diarize e tagAudioEvents.
incredibly-fast-whisperSó com wordTimestamps: trueSem a opção, a tarefa é concluída e cobrada, com segmentos de frase e uma lista words vazia.
whisperNuncaSó segmentos de frase. wordTimestamps: true é recusado com 400 validation_error antes de qualquer gasto de créditos.
nemotron-3-5-transcribeSó com wordTimestamps: trueO 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:

CampoUnidadeConteúdo
textA transcrição inteira em uma única string.
languageO código do idioma detectado ou pedido.
wordsmilissegundosUma entrada por palavra: { text, startMs, endMs, speaker? }. Fica vazia quando os tempos das palavras não foram pedidos ao mecanismo.
jsonmilissegundosA transcrição normalizada, { version, language, words, segments? }, que client.edit aceita.
segmentssegundosOs 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.

Última atualização

Nesta página