Voz e mídia

Os endpoints de voz e mídia expõem as ferramentas de voz e de mídia do Nodaro como REST simples. Eles cobrem catálogo de vozes, modificação de voz e troca de voz de vários falantes, dublagem, design de voz, importação de vídeo, legendas, cortes, ferramentas de áudio, transcrição e publicação em redes sociais. A maioria funciona como job: o POST retorna { jobId } na hora, você consulta periodicamente GET /v1/jobs/:id/status até o status ser completed e lê o resultado em output_data.

As rotas funcionam em todas as edições, com as exceções indicadas abaixo, e recebem um bearer token. Veja Autenticação e, para consultar periodicamente vários jobs de uma vez, Jobs. Para enviar arquivos locais, faça o upload deles primeiro; veja Envio de arquivos.

Vozes

Sempre que uma rota aceita uma voz, passe o voice_id de uma voz do catálogo, o nome de uma voz pronta, como Rachel, ou o elevenlabsVoiceId de um clone. Os clones feitos antes da descontinuação continuam funcionando em todo lugar.

Um resultado da Biblioteca de vozes pode trazer recommendedProvider: o modelo de texto para fala em que a voz foi verificada. Quando o seu app não tem um seletor de modelo, envie esse valor como provider no Texto para fala (Text to Speech), para que a voz soe como na prévia. verifiedProviders lista todos os modelos em que a voz foi verificada; quando o seu app tem um seletor, substitua a escolha do usuário só quando ela não estiver nessa lista. hasMore, na resposta, controla o “carregar mais”.

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

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 } : {}),
})

Criar uma voz ou falar com uma voz descrita

No Design de voz (Voice Design), text é uma frase de prévia de 100 a 1.000 caracteres, loudness vai de -1 a 1 e guidanceScale, de 0 a 100. No Remix de voz (Voice Remix), text tem de 1 a 5.000 caracteres. Os dois retornam um job.

Mudar a voz de uma gravação

POST /v1/voice-changer substitui a voz de uma faixa de áudio, ou de um vídeo inteiro com fala, por uma voz de destino. Envie exatamente um entre audioUrl e videoUrl; quando você envia os dois, o vídeo prevalece. Em um vídeo, o Nodaro extrai o áudio, muda a voz e coloca o áudio de volta na imagem original, e o output_data do job traz videoUrl e audioUrl.

curl -X POST https://app.nodaro.ai/v1/voice-changer \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "videoUrl": "https://cdn.nodaro.ai/uploads/talking.mp4", "voiceId": "Aria", "removeBackgroundNoise": false }'

const { jobId } = await client.voices.change({
  videoUrl: 'https://cdn.nodaro.ai/uploads/talking.mp4',
  voiceId: 'Aria',
})

nodaro voice changer --voice Aria --video https://cdn.nodaro.ai/uploads/talking.mp4 --watch

Veja Modificador de voz (Voice Changer) para preços e dicas.

Trocar a voz de vários falantes

O Modificador de voz Pro (Voice Changer Pro) detecta cada falante de uma gravação e dá a cada um uma voz diferente, mantendo as palavras e o timing. Ele roda no Nodaro Cloud. Uma instalação self-hosted conectada ao Nodaro Cloud pode fazer a troca de voz em uma única chamada por meio dessa conexão; as etapas analyze e export exigem o próprio Nodaro Cloud. Veja Conectar ao Nodaro Cloud.

Mapear vozes para os falantes

orderedVoices mapeia os falantes pela ordem de detecção: o falante 0 recebe a entrada 0, o falante 1 recebe a entrada 1, e assim por diante, com 1 a 8 entradas. Os falantes que passam do fim da lista mantêm a própria voz. Cada entrada é uma destas:

• Um ID de voz, como "Rachel".
• null, uma posição que mantém a voz original: esse falante mantém a própria voz, e os falantes seguintes ainda têm a voz trocada. Essas posições não custam nada, mas pelo menos uma entrada precisa ser uma voz.
• Um objeto com configurações por falante: { voiceId, engine?, stability?, similarityBoost?, style?, useSpeakerBoost?, seed?, volumeMode?, volume? }. engine é sts (o padrão, fala para fala) ou v3, que interpreta a fala de novo a partir da transcrição com o ElevenLabs v3 e só aceita os valores 0; 0,5 e 1 em stability. volumeMode é match (o padrão), normalize ou manual, com volume de 0 a 200 por cento.

Antes de trocar as vozes, o Nodaro sempre separa as vozes da música e dos efeitos. O resto do corpo controla o resultado:

A troca de voz é cobrada por falante mapeado; analyze e export têm preços fixos. Veja os preços em Modificador de voz Pro.

O fluxo interativo: analyze, troca de voz em stems, export

A troca de voz em uma única chamada renderiza um vídeo pronto de uma vez. O fluxo interativo permite verificar os falantes antes de pagar pela troca de voz e mixar o resultado antes de renderizá-lo.

AUTH="Authorization: Bearer $NODARO_API_KEY"
VIDEO="https://cdn.nodaro.ai/uploads/panel.mp4"

# 1. Detect the speakers
JOB=$(curl -s -X POST https://app.nodaro.ai/v1/voice-changer-pro/analyze -H "$AUTH" \
  -H 'Content-Type: application/json' -d "{\"videoUrl\":\"$VIDEO\",\"suggestTitle\":true}" | jq -r .jobId)
# ...poll until completed, then keep the analysis
ANALYSIS=$(curl -s "https://app.nodaro.ai/v1/jobs/$JOB/status" -H "$AUTH" | jq .data.output_data)

# 2. Recast to stems: speaker 2 keeps their own voice
JOB=$(curl -s -X POST https://app.nodaro.ai/v1/voice-changer-pro -H "$AUTH" -H 'Content-Type: application/json' \
  -d "{\"videoUrl\":\"$VIDEO\",\"orderedVoices\":[\"Rachel\",null,\"Aria\"],\"output\":\"stems\",\"analysis\":$ANALYSIS}" | jq -r .jobId)

# 3. Export your mix
curl -s -X POST https://app.nodaro.ai/v1/voice-changer-pro/export -H "$AUTH" -H 'Content-Type: application/json' -d "{
  \"videoUrl\": \"$VIDEO\",
  \"tracks\": [
    { \"url\": \"<voice stem 0>\", \"gain\": 100, \"muted\": false },
    { \"url\": \"<voice stem 1>\", \"gain\": 90, \"muted\": false },
    { \"url\": \"<background stem>\", \"gain\": 70, \"muted\": false, \"kind\": \"background\" }
  ],
  \"voiceFx\": { \"preset\": \"hall\", \"wetDryMix\": 25 }
}"

const { jobId: analyzeJob } = await client.voices.analyze({ videoUrl, suggestTitle: true })
const analysis = (await client.jobs.get(analyzeJob)).output_data // once completed

const { jobId: recastJob } = await client.voices.recast({
  videoUrl,
  orderedVoices: ['Rachel', null, 'Aria'],
  output: 'stems',
  analysis,
})
const stems = (await client.jobs.get(recastJob)).output_data // once completed

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 },
})

nodaro voice analyze --video https://cdn.nodaro.ai/uploads/panel.mp4 --watch --json > analyze.json
jq .output_data analyze.json > analysis.json

nodaro voice recast --video https://cdn.nodaro.ai/uploads/panel.mp4 --voices Rachel,keep,Aria \
  --analysis-file analysis.json --output stems --watch

nodaro voice export --source https://cdn.nodaro.ai/uploads/panel.mp4 --tracks-file mix.json \
  --voice-fx hall --voice-fx-mix 25 --watch

Na CLI, a palavra keep em --voices cria uma posição que mantém a voz original.

Dublar para outro idioma

POST /v1/dubbing traduz e dubla uma faixa de áudio ou um vídeo inteiro, mantendo a voz de cada falante. Envie exatamente uma origem: audioUrl, videoUrl ou sourceUrl (um link público, como uma página do YouTube ou do TikTok, que o próprio modelo de dublagem busca). Um vídeo volta como vídeo dublado: output_data.videoUrl, mais a faixa dublada sozinha em output_data.audioUrl.

Uma dublagem é cobrada por minuto do trecho dublado, com mínimo de 1 minuto. O trecho pode ter até 30 minutos; um trecho mais longo retorna 413, então duble uma janela com startTime e endTime. Veja Dublagem (Dubbing).

Importar um vídeo de um link

POST /v1/download-video importa para o seu armazenamento um vídeo de rede social (YouTube, TikTok, Instagram, X ou Facebook) ou um link direto para um arquivo de vídeo. A rota retorna { downloadId }, não um ID de job. O arquivo pronto vai para a sua biblioteca.

Acompanhe o download com GET /v1/download-video/progress/:downloadId, um fluxo de server-sent events. Mais ou menos a cada 500 ms, ele envia { phase, percent, videoUrl?, thumbnailUrl?, error? }, e termina em completed, com o videoUrl armazenado, ou em failed, com o error. Comece a ouvir assim que a importação começar, porque o progresso só fica guardado por pouco tempo depois que o download termina. No máximo 4 downloads ficam em andamento ao mesmo tempo por conta; um quinto retorna 429 too_many_downloads.

DL=$(curl -s -X POST https://app.nodaro.ai/v1/download-video \
  -H "Authorization: Bearer $NODARO_API_KEY" -H 'Content-Type: application/json' \
  -d '{ "url": "https://www.youtube.com/watch?v=VIDEO_ID", "maxHeight": 720 }' | jq -r .downloadId)

curl -sN https://app.nodaro.ai/v1/download-video/progress/$DL \
  -H "Authorization: Bearer $NODARO_API_KEY"

const { downloadId } = await client.media.downloadVideo({
  url: 'https://www.youtube.com/watch?v=VIDEO_ID',
  maxHeight: 720,
})
for await (const event of client.media.downloadVideoProgress(downloadId)) {
  console.log(`${event.phase} ${event.percent}%`)
  if (event.phase === 'completed') console.log('stored at', event.videoUrl)
}

nodaro media download "https://www.youtube.com/watch?v=VIDEO_ID" --max-height 720 --watch
nodaro media metadata "https://www.youtube.com/watch?v=VIDEO_ID"

Duas rotas relacionadas respondem na hora:

• POST /v1/video-metadata com { url } lê a duração, o tamanho, o título e o status de transmissão ao vivo de um vídeo sem baixá-lo. Use essa rota para decidir se vale importar só um trecho.
• POST /v1/save-to-storage com { mediaUrl, filename?, mediaType? } copia qualquer URL de mídia externa para o seu armazenamento, no servidor. A rota retorna um job.

Editar vídeo

Cortar um vídeo

POST /v1/trim-video recebe videoUrl e o intervalo na unidade que você preferir: startTime e endTime em segundos, trimStartFrames e trimEndFrames, trimStartSeconds e trimEndSeconds, ou keepFirstSeconds ou keepLastSeconds.

Embutir legendas

POST /v1/add-captions recebe videoUrl e as palavras da primeira fonte que encontra, nesta ordem: captions (entradas com tempo por palavra), transcript, text no estilo subtitle e, por fim, a transcrição automática da fala.

Uma subtitle de texto simples, sem estilização, é a renderização barata. Um estilo cinético, qualquer campo de estilização, legendas com tempo, a transcrição automática ou segments renderizam pelo preço mais alto e mantêm a taxa de quadros da origem. Veja todas as opções e os dois preços em Adicionar legendas.

Transformar imagens fixas em vídeo

• POST /v1/still-to-video recebe { imageUrl, audioUrl, motion?, intensity?, resolution?, aspectRatio?, fps?, fit?, padColor? }. O vídeo dura o mesmo que o áudio; não existe campo de duração. motion é none (o padrão), zoom-in, zoom-out, pan-left, pan-right ou ken-burns, com intensity de 1 a 10. Veja Imagem fixa para vídeo (Still to Video).
• POST /v1/slideshow recebe imageUrls (de 2 a 100), um audioUrl opcional, imageDurations (segundos por imagem, null para automático) ou perImageDuration, uma transition e os mesmos campos de aparência. Com áudio, a apresentação dura o mesmo que o áudio; as durações fixadas que não somam esse total são ajustadas proporcionalmente, e a saída do job avisa isso. Sem áudio, ela dura o número de imagens vezes perImageDuration, em silêncio. Veja Apresentação de slides (Slideshow).

As duas rotas renderizam no servidor, sem modelo de IA, e custam 0 créditos. resolution é 720p, 1080p ou 4K, fps é 24 ou 30, e fit: "contain" adiciona faixas com padColor em vez de cortar a imagem.

Sobrepor imagens a um vídeo

POST /v1/video-overlay coloca de 1 a 20 camadas de imagem sobre um vídeo em uma única renderização e mantém o áudio original intacto. Cada camada é { imageUrl, start, end?, preset?, corner?, anchor?, x?, y?, width?, height?, fit?, opacity?, animate?, zIndex? }. start e end são segundos; sem end, a camada dura até o fim do vídeo. preset é card, corner-badge ou full-frame, e uma posição ou um tamanho explícito o substitui. Uma camada sem nenhum dos dois é um selo de canto, no canto inferior direito, a menos que corner indique outro.

outputAspect (16:9, 9:16, 1:1 ou 4:5) muda o quadro, com baseFit e backgroundColor. O job retorna { videoUrl, thumbnailUrl, width, height, durationSec, warnings }. A rota custa 22 créditos por execução, qualquer que seja o número de camadas, e cada usuário pode enviar 30 requisições por minuto. Veja Sobreposição em vídeo (Video Overlay).

Cortar ou recortar um arquivo armazenado na hora

POST /v1/media/process corta ou recorta um arquivo que você armazenou e responde na mesma requisição, de graça. O corpo é { sourceUrl, type, trim?, crop?, format?, deleteSource? }: type é video ou audio, trim é { startTime, endTime }, crop é { x, y, width, height }, e format é mp4, webm, mp3, wav, m4a ou aac. A rota retorna { data: { url, thumbnailUrl, assetId, sizeBytes, mimeType, metadata } }. deleteSource: true exclui a origem depois, quando ela é sua e nada mais a usa.

Editar áudio

Cada rota retorna um job.

silence-detect usa por padrão thresholdDb: -35, minSilenceMs: 700 e padMs: 120, e aceita áudio ou vídeo. O output_data.json dela é { version, ranges: [{ startMs, endMs }], durationMs }.

audio-sync custa 11 créditos por origem depois da primeira: 11 para 2 origens, 33 para 4, 55 para 6. Os IDs precisam ser únicos, e reference precisa ser um deles (por padrão, a primeira origem). O output_data.json dela é { version, reference, offsets: [{ sourceId, offsetMs, confidence, driftMsPerHour }], notes }, em que um tempo na referência é igual ao tempo na origem mais offsetMs. O desvio (drift) é medido e anotado, nunca corrigido.

Transcrever fala

POST /v1/transcribe transforma fala em texto e retorna um job. O corpo é { audioUrl, provider?, language?, diarize?, tagAudioEvents?, wordTimestamps? }, e audioUrl também pode ser um vídeo.

Omitir provider executa whisper, então indique um mecanismo sempre que precisar de marcações de tempo por palavra. O output_data do job concluído guarda text, language, words (um { text, startMs, endMs, speaker? } por palavra, em milissegundos), json (a transcrição normalizada, também em milissegundos) e, só nos mecanismos mais antigos, segments em segundos. words entra direto em captions no POST /v1/add-captions.

curl -X POST https://app.nodaro.ai/v1/transcribe \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audioUrl": "https://cdn.nodaro.ai/uploads/talk.mp3", "provider": "elevenlabs-stt", "diarize": true }'

const { jobId } = await client.audio.transcribe({
  audioUrl: 'https://cdn.nodaro.ai/uploads/talk.mp3',
  provider: 'elevenlabs-stt',
})
// once completed, burn the words in as kinetic captions
const words = (await client.jobs.get(jobId)).output_data.words
await client.media.addCaptions({
  videoUrl: 'https://cdn.nodaro.ai/uploads/talk.mp4',
  captions: words,
  style: 'word-highlight',
  autoTranscribe: false,
})

nodaro audio transcribe --audio https://cdn.nodaro.ai/uploads/talk.mp3 --provider elevenlabs-stt --watch
nodaro jobs get <jobId> --json | jq '.output_data.words' > words.json
nodaro media add-captions https://cdn.nodaro.ai/uploads/talk.mp4 \
  --captions-file words.json --style word-highlight --no-auto-transcribe --watch

Publicar em redes sociais

Os fluxos de conexão abrem janelas pop-up e foram feitos para o app web. A publicação funciona com um token de API pessoal. Os tokens de app OAuth não podem gerenciar conexões.

GET /v1/social/providers lista todas as redes com { id, label, connectKind, editor, category, capabilities, available }. category é social (um feed em que você posta) ou publishing (um site em que você publica artigos). Uma rede que a implantação não configurou aparece com available: false, nunca fica oculta. As redes que se conectam com campos (Bluesky, Dev.to, Hashnode, Medium, WordPress e Lemmy) descrevem os campos em customFields, e o Nodaro verifica a credencial com a rede antes de salvá-la.

POST /v1/social/publish recebe { platform, action, connectionId?, caption?, mediaUrl or mediaItems, … }. Duas falhas exigem tratamentos diferentes:

• 503 publish_retryable: nada foi postado. Enviar a mesma requisição de novo é seguro.
• 500 publish_failed: o resultado é desconhecido. Enviar de novo pode postar duas vezes, então verifique a rede primeiro.

Um post agendado recebe { connectionId, action, scheduledAt, caption?, media? }, em que cada item de mídia é { type, r2Key or url }. A mídia precisa ser de arquivos armazenados nesta implantação, que o Nodaro transforma em links novos quando o post sai; links para outros sites são recusados. Editar um post que já está sendo publicado retorna 409 not_editable. Veja Publicar nas redes (Publish to Social) e Publicar nas redes sociais.

Equivalentes no SDK e na CLI

Pelo MCP, as mesmas rotas são ferramentas como voice_changer, voice_changer_pro, voice_changer_pro_analyze, voice_changer_pro_export, dubbing, transcribe, add_captions e separate_audio. Veja a Referência das ferramentas MCP.

Erros