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

Voz e mídia

Vozes, troca de voz de um ou vários falantes, dublagem, importação de vídeo, legendas, cortes, ferramentas de áudio e publicação social via REST no Nodaro.

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 tarefa: 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árias tarefas de uma vez, Tarefas. Para enviar arquivos locais, faça o upload deles primeiro; veja Envio de arquivos.

Vozes

MétodoCaminhoO que faz
GET/v1/voicesO catálogo de vozes prontas: nome, voice_id, gênero, sotaque e idade. Com ?model= definido como um modelo de fala Gemini, as vozes próprias desse modelo.
GET/v1/voices/libraryBusca na Biblioteca de vozes compartilhada, com search, gender, age, accent, language, category, use_cases, descriptives, featured, sort, page e page_size.
GET/v1/voices/library/facetsQuantas vozes da biblioteca cada grupo, tom, idioma, gênero, idade, sotaque e categoria tem, para os filtros que você envia.
GET/v1/voices/:voiceId/previewA prévia de uma voz, servida pelo próprio host da implantação, em uma implantação que serve prévias assim.
GET/v1/voices/favoritesAs suas vozes favoritas, das mais recentes para as mais antigas.
PUT/v1/voices/favorites/:voiceIdMarca uma voz como favorita.
DELETE/v1/voices/favorites/:voiceIdRemove uma voz dos seus favoritos.
GET/v1/voice-clonesOs clones de voz que você fez antes de a clonagem ser descontinuada.
PATCH/v1/voice-clones/:idRenomeia ou edita um desses clones.
DELETE/v1/voice-clones/:idExclui um desses clones.
POST/v1/voice-clones, /v1/voice-clones/from-urlDescontinuadas. As duas retornam 410 voice_cloning_retired.
POST/v1/voice-clone/consentRegistra o consentimento do usuário conectado para um clone de voz único: { sourceAudioUrl, consentAudioUrl } → { userId, signature }. Nada é baixado, guardado nem cobrado.

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.

Os modelos de fala Gemini (gemini-3-8-flash-lite-tts, gemini-3-8-flash-tts, gemini-3-1-flash-tts e gemini-2-5-pro-tts) falam só as próprias vozes nomeadas. GET /v1/voices?model=<model> as lista: voice_id e name são o nome da voz, e nos modelos 3.8 use_case diz para que a voz serve. Qualquer outro modelo, ou nenhum model, lista o catálogo de vozes prontas.

Um clone único da sua própria voz, para uma única requisição e nunca salvo, é o campo replica de /v1/text-to-speech e de um falante de /v1/text-to-dialogue no gemini-3-8-flash-tts, com consent: true. Veja Texto para fala. Um app publicado nunca leva as gravações do autor: quem executa o app envia as próprias duas gravações WAV e o próprio consentimento de POST /v1/voice-clone/consent nos inputOverrides da execução. Uma execução sem eles é recusada com 400 clone_recordings_required ou 400 clone_consent_required, antes de qualquer cobrança.

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

Filtrar a Biblioteca de vozes

  • use_cases agrupa a biblioteca do jeito que um seletor mostra as categorias: advertisement, characters_animation, conversational, entertainment_tv, informative_educational, narrative_story ou social_media. Envie um valor por chamada.
  • descriptives é uma palavra de tom, como calm, deep ou cute. Envie um valor por chamada.
  • Cada voz traz o seu descriptive (o tom da biblioteca em uma palavra, "" quando não há) e o language e o locale principais ("" quando não informados). Ela também traz verifiedLanguages: todos os códigos de idioma em que a voz foi verificada, o principal primeiro. language é comparado com verifiedLanguages, então uma voz em inglês verificada em espanhol aparece em language=es.

GET /v1/voices/library/facets recebe os mesmos filtros, sem paginação nem ordenação, e responde { total, use_cases, languages, descriptives, genders, ages, accents, categories, approximate, updatedAt }. Cada faceta é uma lista de { value, count }, ordenada pela contagem, sem os valores de contagem zero.

  • total aplica todos os filtros. As contagens de cada faceta aplicam todos os filtros, menos o da própria faceta, então um seletor pode mostrar a contagem de todas as categorias com uma delas escolhida.
  • 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.
  • A rota é pública e gratuita, e pode ficar em cache por 5 minutos. Nos primeiros minutos depois que uma implantação lê a biblioteca pela primeira vez, ela responde 503 voice_library_warming com Retry-After. Uma implantação sem chave de fala responde contagens zero com keyMissing: true.

Vozes favoritas

As suas vozes favoritas valem em todos os clientes que você usa: uma voz pronta, uma voz da Biblioteca de vozes ou um dos seus clones, marcada uma vez e lida em todo lugar.

  • GET /v1/voices/favorites responde { favorites: [{ voiceId, voiceType, name, previewUrl, createdAt }] }, das mais recentes para as mais antigas. voiceId e voiceType são o que o nó Texto para fala recebe como voice e voiceType. name e previewUrl são o instantâneo de quando você marcou a voz.
  • PUT /v1/voices/favorites/:voiceId recebe { voiceType: "premade" | "library" | "custom", name, previewUrl? } e responde { favorite }. Marcar a voz de novo atualiza o instantâneo. Acima de 500 favoritos, a resposta é 409 limit_reached.
  • DELETE /v1/voices/favorites/:voiceId responde { success: true }, também para uma voz que não estava marcada.
  • Escopos: um token de app OAuth precisa de assets:read para a lista e de assets:write para as duas gravações.

Prévias de voz servidas pelo próprio host da implantação

Uma implantação pode servir as prévias de voz pelo próprio host. Nela, GET /v1/voices e GET /v1/voices/library dão cada preview_url como um endereço assinado de GET /v1/voices/:voiceId/preview, em vez do endereço do provedor de fala. Reproduza o endereço como ele veio.

  • A rota não precisa de token Bearer, porque um elemento <audio> não envia nenhum. A assinatura é a credencial.
  • Ela responde com o áudio, com 206 para um intervalo de bytes. Um endereço que as listas não deram responde 404, uma voz que o bloqueio de vozes da implantação recusa responde 400 voice_not_available, e um arquivo que o provedor não consegue servir responde 502 preview_unavailable.
  • Em qualquer outra implantação, a rota responde 404.

Criar uma voz ou falar com uma voz descrita

MétodoCaminhoCorpoResultado
POST/v1/voice-design{ text, voiceDescription, model?, loudness?, guidanceScale?, seed?, quality?, shouldEnhance? }Uma prévia e um ID de voz reutilizável.
POST/v1/voice-remix{ text, voiceDescription }Fala na voz descrita, sem clonagem.

No Design de voz, 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, text tem de 1 a 5.000 caracteres. Os dois retornam uma tarefa.

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 da tarefa 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
CampoO que faz
voiceIdObrigatório. A voz de destino.
audioUrl ou videoUrlObrigatório, um dos dois. A gravação a modificar.
modelO modelo de fala para fala.
stability, similarityBoostDe 0 a 1. O quanto a interpretação é estável e o quanto a voz se aproxima da voz de destino.
styleDe 0 a 1, padrão 0. Exagera a interpretação, com algum custo em velocidade e estabilidade.
useSpeakerBoostAumenta a semelhança com a voz de destino, um pouco mais devagar.
seedUm inteiro que torna a saída repetível.
removeBackgroundNoisetrue retorna só a voz limpa; false mantém a música e os efeitos sob a nova voz.

Veja Modificador de voz para preços e dicas.

Trocar a voz de vários falantes

O Modificador de voz 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 auto-hospedada 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.

MétodoCaminhoO que faz
POST/v1/voice-changer-proTroca a voz de cada falante mapeado, como um vídeo pronto ou como stems separados.
POST/v1/voice-changer-pro/analyzeDetecta os falantes sem trocar as vozes. Só no Nodaro Cloud.
POST/v1/voice-changer-pro/exportRenderiza um vídeo pronto a partir da sua própria mixagem dos stems. Só no Nodaro Cloud.
POST/v1/voice-changer-pro/translateTraduz a transcrição detectada para outro idioma, para falar o vídeo de novo nesse idioma. Só no 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?, languageCode? }. engine é sts (o padrão, fala para fala), v3 ou v4. v3 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. v4 faz o mesmo com o ElevenLabs v4, aceita qualquer stability de 0 a 1 e aplica similarityBoost. languageCode só é aceito com v4, para falar uma fala traduzida, como descrito abaixo. 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:

CampoO que faz
audioUrl ou videoUrlObrigatório, um dos dois. Em um vídeo, o áudio com as vozes trocadas volta para a imagem original.
preserveBackgroundMistura a música e os efeitos de volta sob as novas vozes. Padrão true.
separationQualityfast (o padrão, preserva mais da voz) ou best (uma separação mais fina).
removeBackgroundNoiseTambém remove o ruído do resultado.
musicVolumeMode, musicVolumeO nível do fundo mantido: match (o padrão), normalize ou manual, com 0 a 200 por cento.
voiceFxUma reverberação ou um eco só nas vozes: { preset, wetDryMix?, delayMs?, decay? }. As predefinições de reverberação, como room, hall ou church, usam wetDryMix; echo e custom usam delayMs e decay.
outputvideo (o padrão, o resultado pronto) ou stems (faixas secas, sem nivelamento, para a sua própria mixagem).
analysisO output_data de uma tarefa de análise anterior. A troca de voz reutiliza os falantes e os stems dessa análise, em vez de detectá-los de novo.

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.

Falar de novo em outro idioma. POST /v1/voice-changer-pro/translate traduz os falantes de uma análise para um idioma de destino, segmento por segmento. Cada fala recebe um limite de tamanho, para que a fala nova caiba no espaço dela. O corpo é { speakers, targetLanguage, sourceLanguage?, tier? }, em que speakers vem da análise e tier é economy, standard ou premium. O output_data.speakers da tarefa mantém cada falante, segmento e tempo, com o text traduzido, o original em sourceText e untranslated, os IDs das falas que ficaram no idioma de origem. Revise o texto e depois envie esses falantes como o analysis.speakers da troca de voz, com engine: "v4" e languageCode com o idioma de destino em cada voz nova. languageCode com sts ou v3, ou um idioma que o modelo não oferece, responde 400. A tradução é cobrada pelo tamanho do texto, com um preço mínimo e um máximo por 1.000 caracteres iniciados que dependem do nível. Fora do Nodaro Cloud, as quatro rotas voice-changer-pro respondem 404.

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.

Detectar os falantes

POST /v1/voice-changer-pro/analyze com audioUrl ou videoUrl e, opcionalmente, separationQuality e suggestTitle. O output_data da tarefa concluída traz vocalsUrl e backgroundUrl, já separados, e languageCode e languageProbability, detectados. A lista speakers dá, para cada falante, id, segments, firstStartSec, wordCount e um snippet. Ele também traz um suggestedTitle quando você pede um. Procure “falantes” que não são pessoas, como aplausos.

Trocar as vozes em stems

POST /v1/voice-changer-pro com output: "stems" e todo o output_data da análise como analysis. A troca de voz pula a detecção, então você pode trocar as vozes de novo, com outras vozes, sem pagar pela detecção outra vez.

Mixar e exportar

Defina o nível de cada stem na sua própria interface; isso não custa nada. Depois, envie POST /v1/voice-changer-pro/export com o videoUrl de origem e até 16 tracks, cada uma { url, gain, muted, kind? }. gain vai de 0 a 200, kind é voice ou background, e pelo menos uma faixa precisa estar com som. Um voiceFx opcional se aplica só às faixas de voz. O fluxo de vídeo é copiado, nunca codificado de novo, então a exportação corresponde à sua prévia. O output_data.videoUrl da tarefa concluída é o resultado.

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 para onde está um vídeo, ou um link direto de mídia, que o próprio modelo de dublagem busca). Um sourceUrl é uma importação desse link: envie o confirmationId confirmado para ele. Veja Direitos de conteúdo. Um vídeo volta como vídeo dublado: output_data.videoUrl, mais a faixa dublada sozinha em output_data.audioUrl.

CampoO que faz
targetLanguageObrigatório. Um código ISO, por exemplo es ou pt-BR.
sourceLanguageO idioma falado. É detectado quando você o omite.
numSpeakers0 (o padrão) detecta os falantes; de 1 a 20 melhora a separação quando você sabe o número.
startTime, endTimeDubla só essa janela da origem, em segundos.
disableVoiceCloning, dropBackgroundAudioNão reproduz a voz própria de cada falante, ou descarta a música e os efeitos.
highestResolutionMantém a resolução de origem em um vídeo.
useProfanityFilter, targetAccent, watermarkUm filtro de palavrões, um sotaque para o idioma de destino e a marca-d’água do modelo de dublagem em um vídeo.

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.

Ler uma dublagem depois de pronta

Uma dublagem continua legível depois que a tarefa termina: as falas do áudio original, cada idioma com as falas dele, os falantes e as legendas de cada idioma. As duas leituras são gratuitas. Também é possível adicionar um idioma à dublagem depois.

MétodoCaminhoO que faz
GET/v1/dubbing/:jobIdA estrutura da dublagem: { jobId, durationSec, source, languages, speakers, capabilities, addLanguage }.
GET/v1/dubbing/:jobId/captionsAs legendas de um idioma, ou da fala original, como o texto de um arquivo SubRip ou WebVTT. Envie ?language= (um código que a dublagem lista, ou source) e ?format= (srt, o padrão, ou vtt).
POST/v1/dubbing/:jobId/languagesAdiciona um idioma: { "targetLanguage": "de" } responde { jobId }, a tarefa que entrega o idioma.

jobId é a tarefa que criou a dublagem, ou a tarefa de um idioma adicionado depois. Só o dono pode ler uma dublagem: a tarefa de qualquer outra pessoa responde 404 not_found. Apps OAuth precisam de assets:read para as leituras e de assets:write para adicionar um idioma. Cada leitura é limitada a 60 requisições por minuto, e a chamada de adicionar, a 10 por minuto.

  • languages tem uma entrada por idioma. O status dela é processing, completed, stale (as falas mudaram depois que a mídia foi feita) ou failed. Os segments só são preenchidos quando o idioma está completed ou stale.
  • Cada fala dublada traz start e end em segundos, o text e, onde a dublagem os guarda, sourceSegmentId (a fala do áudio original que ela traduz) e sourceText.
  • speakers são listados na ordem em que falam pela primeira vez, cada um com o número de falas.
  • capabilities diz o que você pode fazer com a dublagem agora. Ofereça uma ação só quando a flag dela for true. addLanguage e captions são as flags que podem ser true hoje.
  • addLanguage dá o preço de adicionar um idioma como um id de preço: creditIdByLanguage[language] quando ele está listado, ou creditId nos outros casos. Calcule o preço com POST /v1/credits/model-costs. billableMinutes são os minutos inteiros cobrados por um idioma adicionado.

Adicionar um idioma é cobrado por minuto iniciado da dublagem, e a execução reserva esse preço antes de começar. 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. Um idioma que a dublagem já tem, ou um que está sendo feito, responde 409 dubbing_language_exists; um idioma que falhou pode ser adicionado de novo.

As leituras respondem 409 dubbing_not_ready enquanto a dublagem está sendo feita, 422 dubbing_failed para uma dublagem que falhou, 422 not_a_dubbing_job para outro tipo de tarefa e 410 dubbing_unavailable quando o serviço de dublagem não guarda mais a dublagem. As legendas respondem 404 dubbing_language_not_found, 409 dubbing_language_processing ou 422 dubbing_captions_unavailable para um idioma que não conseguem exportar. O SDK chama as mesmas rotas com client.dubbing.get, client.dubbing.captions e client.dubbing.addLanguage.

POST /v1/download-video importa para o seu armazenamento o vídeo por trás de um link, seja a página do vídeo ou um link direto para um arquivo de vídeo. A rota retorna { downloadId }, não um ID de tarefa. O arquivo pronto vai para a sua biblioteca.

CampoO que faz
urlObrigatório. A página ou o arquivo a importar.
maxHeightLimita a resolução, por exemplo 720. Omita para obter a melhor disponível.
sectionStartSec, sectionEndSecImporta só esse intervalo, em segundos, com alguns segundos a mais em cada ponta, porque o corte cai nos quadros-chave. Envie os dois ou nenhum, e corte o resultado para ter um corte exato.
exactSectiontrue corta o trecho exatamente no intervalo pedido, sem margem.
requireAudioPor padrão, um resultado sem som falha, porque isso geralmente indica uma origem degradada. Envie false para aceitar um clipe sem som.
confirmationIdA confirmação de direitos de conteúdo deste link, de POST /v1/content-rights/confirm. Veja Direitos de conteúdo.

Um link direto para um arquivo de vídeo pode ter no máximo 30 minutos e no máximo 10 GiB. Um arquivo cujo cabeçalho mostra que ele passa de um dos limites responde 422 na hora, com media_too_long, media_too_large ou media_bitrate_implausible. O arquivo baixado é verificado de novo, e um arquivo que falha não é guardado: a transmissão do progresso termina failed, com o motivo. Um link para a página de um vídeo em uma rede social não tem esse limite de duração. Veja os limites em Envio de arquivos.

Uma importação de link passa pela verificação de direitos de conteúdo antes que qualquer coisa seja buscada. Uma confirmação que não sirva, ou um site que a implantação não permite, responde 403 com o código que diz o motivo. Veja Direitos de conteúdo.

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 uma tarefa.

Editar vídeo

MétodoCaminhoO que fazPreço
POST/v1/trim-videoCorta um vídeo em um intervalo.Cortar vídeo
POST/v1/combine-videosJunta de 2 a 100 vídeos em ordem.Combinar vídeos
POST/v1/add-captionsEmbute legendas em um vídeo.Adicionar legendas
POST/v1/still-to-videoUma imagem e uma faixa de áudio viram um MP4.0 créditos
POST/v1/slideshowDe 2 a 100 imagens e uma faixa de áudio opcional viram um MP4.0 créditos
POST/v1/video-overlayColoca de 1 a 20 camadas de imagem ou de vídeo com tempo definido sobre um vídeo.22 créditos só com camadas de imagem; a cada 5 segundos iniciados do vídeo base com uma camada de vídeo
POST/v1/media/processCorta ou recorta um arquivo armazenado e responde na hora.Grátis
POST/v1/edit-planPlaneja a edição de uma gravação a partir da transcrição: enxugar, encontrar clipes, marcar capítulos ou cortar um trailer. O resultado é uma lista de decisões de edição, não mídia.Plano de edição
POST/v1/camera-switchColoca cada corte de uma edição na câmera de quem está falando. O som nunca muda.Troca de câmeras
POST/v1/apply-edlRenderiza uma lista de decisões de edição em um arquivo de vídeo ou de áudio, em final ou como uma prévia proxy.Aplicar EDL
POST/v1/tighten-episodeEnxuga um podcast ou uma entrevista em uma só chamada: transcreve, remove silêncios e vícios de linguagem, renderiza o episódio e, se você quiser, adiciona legendas e uma trilha musical de fundo.Enxugar episódio
POST/v1/episode-chaptersEncontra os capítulos de uma gravação em uma só chamada e os escreve como notas do episódio. Nada é renderizado.As etapas mais uma taxa por execução. Veja Índice de capítulos.
POST/v1/episode-trailerCorta um trailer de 20 a 40 segundos de uma gravação, em cada formato de rede social que você escolher.As etapas mais uma taxa por execução. Veja Trailer do episódio.
POST/v1/clip-packCorta uma gravação em um pacote de clipes curtos, enquadrados e legendados.As etapas mais uma taxa por execução. Veja Pacote de clipes.
POST/v1/speaker-layoutEnquadra uma gravação inteira por falante, com a mesma duração e sem cortes.As etapas mais uma taxa por execução. Veja Layout de locutores.
POST/v1/shot-cutsEncontra onde cada plano de um vídeo começa e termina, medido a partir do arquivo.Um preço fixo por execução. Veja Cortes de plano.
POST/v1/speaker-viewRenderiza uma edição com os falantes na tela, em um layout, com uma troca a cada mudança de falante. Cobrado por minuto de saída.Visão de falantes
POST/v1/split-mediaCorta um vídeo, um arquivo de áudio ou ambos em partes entre uma duração mínima e uma máxima, ou um vídeo em uma parte por tomada.22 créditos por execução
POST/v1/video-maskRastreia um objeto descrito em texto e retorna um vídeo de máscara em preto e branco. Cobrado pela duração do clipe.Máscara de vídeo
POST/v1/mask-compositeColoca um vídeo de primeiro plano sobre um vídeo de fundo através de um vídeo de máscara.11 créditos a cada 5 segundos iniciados
POST/v1/video-depthTransforma um vídeo em um vídeo de profundidade, o que está perto claro e o que está longe escuro. Cobrado pela duração do clipe.Profundidade de vídeo

O Plano de edição, a Troca de câmeras e a Visão de falantes rodam no Nodaro Cloud. As etapas de planejamento do Enxugar episódio, do Índice de capítulos, do Trailer do episódio, do Pacote de clipes e do Layout de locutores também. Uma instalação auto-hospedada os executa pela conexão com o Nodaro Cloud e responde 503 nodaro_connection_required sem ela.

POST /v1/camera-switch recebe leadMs e lagMs (milissegundos inteiros, de 0 a 5.000, padrão 0): leadMs adianta cada corte, e lagMs o atrasa. POST /v1/speaker-view recebe accentColor (#RRGGBB), a cor da ênfase de borda. Sem switch, a Visão de falantes corta entre os falantes, e sem emphasis não desenha nenhuma ênfase. Uma renderização da Visão de falantes a partir de videoUrl recusa um arquivo acima de 500 MB com 422 video_too_large.

POST /v1/shot-cuts recebe { videoUrl, frames? }: um vídeo MP4, MOV, MKV ou WebM de até 30 minutos e cerca de 10,7 GiB. Ele avalia cada quadro decodificado, e cada corte seco começa um novo plano. Fusões e fades não são cortes. O output_data.json da tarefa é { shotCount, cutsSec, durationSec, shots: [{ index, startSec, endSec, durationSec, firstFrameUrl?, lastFrameUrl? }] }, em segundos com precisão de milissegundo. Com frames: true, o primeiro e o último quadro exatos de cada plano são salvos como PNG, para até 1.000 planos. Um arquivo que não é um vídeo legível, ou que passa de um limite, falha e é reembolsado. O preço é o mesmo com ou sem quadros.

POST /v1/split-media recebe videoUrl, audioUrl ou ambos, chunkDuration (a duração máxima de uma parte, de pelo menos 1 segundo), minPartDuration (padrão 4, nunca acima de chunkDuration) e audioFormat (mp3, wav ou aac). O output_data da tarefa concluída tem videoUrls, audioUrls, chunkCount e partDurationsSec.

{ videoUrl, mode: "shots" } corta, em vez disso, um vídeo em uma parte por tomada, nos cortes medidos a partir do arquivo. Esse modo não recebe duração de parte e aceita só um vídeo: um audioUrl separado é um 400 validation_error. Cada parte mantém o som do próprio vídeo. Os vídeos podem ter até 30 minutos, com no máximo 200 tomadas, pelo mesmo preço. A saída então inclui também shotCount e shots: [{ index, startSec, endSec, durationSec }]. Veja Dividir em partes para saber como as partes são cortadas.

GET /v1/edit-plan/capabilities lista os modos do Plano de edição que este servidor sabe planejar: { modes, source, perMinute }. tighten, clips e chapters sempre aparecem, e trailer só quando o servidor sabe planejar um trailer. perMinute é true quando o Plano de edição é cobrado por minuto iniciado da gravação principal. Caso contrário, ele é cobrado pela faixa de 15, 30, 60, 90, 120 ou 180 minutos para a qual a gravação é arredondada para cima. O SDK lê a rota com client.edit.editPlanCapabilities(), e a CLI com nodaro edit capabilities. Um modo que o servidor não lista responde 400 mode_not_available em POST /v1/edit-plan, antes de qualquer cobrança.

No Nodaro Cloud, POST /v1/edit-plan também recusa estes casos antes de qualquer cobrança: uma requisição sem mode (422 unknown_mode), nenhuma fonte com URL de mídia (422 no_source), uma fonte principal cuja duração não pode ser lida ou é zero (422 probe_failed, 422 invalid_duration), uma fonte acima de 180 minutos (422 source_too_long) e uma transcrição sem palavras com tempo (400 empty_transcript). planTier tem standard como padrão. A ferramenta MCP plan_edit só é oferecida no Nodaro Cloud, não em uma instalação auto-hospedada.

Enxugar um episódio

POST /v1/tighten-episode executa o Enxugar episódio em uma gravação. O corpo é { mediaUrls, masterAudioUrl?, cameras?, musicUrl?, output?, framing?, framingSource?, captions?, captionStyle?, reviewBeforeRender?, planTier?, instructions?, styleGuide?, musicDuckAmount? }. mediaUrls traz uma gravação de vídeo ou de áudio de até 3 horas, com som, ou até seis gravações de uma mesma conversa. Veja Várias câmeras. framing é { aspect, layout } ou null. A rota responde 202 com { jobId, executionId }.

  • Acompanhe a tarefa com GET /v1/jobs/:id/status. O output_data dela traz o episódio (videoUrl, ou audioUrl para um episódio em áudio), a edição (json), a transcrição (transcript) e quality: proxy para a prévia de uma execução com revisão, final nos outros casos. Uma execução com várias gravações ou um áudio principal adiciona cameras, quem foi colocado em cada câmera. Uma execução que falha mantém o que foi concluído e informa a etapa que falhou em failedStep.
  • Repita com segurança. Um cabeçalho Idempotency-Key faz uma nova tentativa da mesma requisição responder com o mesmo jobId e "deduped": true, sem iniciar nada.
  • Veja o preço antes. POST /v1/tighten-episode/estimate aceita o mesmo corpo e responde { data: { totalCredits, stepsCredits, feeCredits, durationSec } } sem iniciar nada. Ela acrescenta estimate: true quando uma etapa é a estimativa de uma chamada de LLM medida: mostre o total como ≈N. A estimativa calcula o preço da renderização com a duração completa da gravação, então a execução costuma custar menos.
  • Continue uma execução. POST /v1/tighten-episode/continue com { jobId, mode } continua uma das suas execuções. "mode": "from-failed" executa apenas o que uma execução com falha não concluiu. "mode": "render-final", com um editedEdl opcional que contém a sua edição do plano, renderiza a versão final de uma execução com revisão.

Uma Renderização final de uma execução que não era uma prévia responde render_final_not_preview, e uma de uma edição que já foi renderizada responde render_final_already_rendered em todas as rotas, exceto no Índice de capítulos. Continuar uma execução que não falhou responde 409 continuation_not_failed.

Índice de capítulos, Trailer do episódio, Pacote de clipes e Layout de locutores

Outras quatro rotas executam uma edição de podcast ou de entrevista em uma só chamada, como POST /v1/tighten-episode. São as rotas dos nós Índice de capítulos, Trailer do episódio, Pacote de clipes e Layout de locutores. Cada uma responde 202 com { jobId, executionId }, e cada uma executa as etapas como tarefas próprias. Uma execução custa as etapas pelos preços delas mais uma taxa por execução. Cada rota tem uma rota /estimate, que recebe o mesmo corpo e responde { data: { totalCredits, stepsCredits, feeCredits, durationSec } }, e uma rota /continue. Um Idempotency-Key faz uma nova tentativa responder com a mesma execução.

RotaCorpoResultado em output_data
POST /v1/episode-chapters{ mediaUrls: [<one recording>], planTier?, instructions?, styleGuide? }. planTier tem economy como padrão.text: as notas do episódio, uma linha M:SS Title por capítulo (H:MM:SS quando um capítulo começa em 1:00:00 ou depois). json: os mesmos capítulos como [{ startMs, title }], o primeiro em 0.
POST /v1/episode-trailer{ mediaUrls, masterAudioUrl?, cameras?, introCardUrl?, formats?, reviewBeforeRender?, planTier?, instructions?, styleGuide? }. formats é uma lista de 9:16, 1:1, 4:5 e 16:9, por padrão os três primeiros. introCardUrl é um vídeo de no máximo 15 segundos.formats: [{ format, url }]. videoUrl: o primeiro formato. failedFormats: os formatos que não puderam ser renderizados. json: a edição do trailer.
POST /v1/clip-pack{ mediaUrls, masterAudioUrl?, cameras?, count?, targetDurationSec?, framing?, framingSource?, captions?, captionStyle?, reviewBeforeRender?, planTier?, instructions?, styleGuide? }. count vai de 1 a 50 (padrão 8) e targetDurationSec de 5 a 180 (padrão 60).clips: [{ url, title?, hook?, clipKey, thumbnailUrl?, captionsFailed? }]. videoUrl (ou audioUrl): o primeiro clipe. failedClips e failedCaptions: quantos clipes ficaram sem renderização ou sem legendas. json: o conjunto de clipes.
POST /v1/speaker-layout{ mediaUrls, masterAudioUrl?, cameras?, targetAspect?, layout?, switchType?, emphasisStyle?, framingSource?, reviewBeforeRender? }. targetAspect tem 9:16 como padrão.videoUrl: o vídeo enquadrado, com a duração da gravação. durationSec, json (a edição), transcript e quality.

mediaUrls traz uma gravação de até 3 horas, com som, ou até seis gravações de uma mesma conversa. O Trailer do episódio e o Layout de locutores precisam de um vídeo, e uma execução só de áudio é recusada com 400 media_needs_video. O Layout de locutores aceita no máximo cinco câmeras: um sexto lugar é para o som, um áudio principal ou uma gravação só de som. Uma execução com várias gravações ou um áudio principal adiciona cameras ao output_data.

  • Recusado antes de qualquer criação ou cobrança: uma gravação que não pode ser lida (400 media_unreadable), que não tem som (400 media_has_no_audio) ou que passa de 3 horas (400 media_too_long), e um áudio principal que não pode ser lido (400 master_audio_unreadable). Veja Erros.
  • Uma execução que mantém parte do trabalho é concluída. Um Trailer do episódio com alguns formatos, ou um Pacote de clipes com alguns clipes, é concluído e mantém a taxa. Um clipe que falhou não é cobrado. Sem nada renderizado, a execução falha e a taxa é reembolsada.
  • Uma execução do Índice de capítulos que não encontra capítulos falha, e a taxa é reembolsada. Todas as etapas dela foram concluídas, então /continue responde 409 continuation_not_failed. Execute de novo, por exemplo com outras instruções.
  • Continue uma execução com { jobId, mode }. "mode": "from-failed" executa o que uma execução que falhou não concluiu. "mode": "render-final" renderiza a versão final de uma execução com revisão, sem taxa. No Trailer do episódio, ela aceita um editedEdl opcional, e no Pacote de clipes um editedEdl que mantém alguns clipes. Uma revisão do Pacote de clipes que descarta todos os clipes responde 409 use_case_nothing_kept. O Layout de locutores não aceita editedEdl: um enviado responde 400 use_case_no_plan. O Índice de capítulos não renderiza nada, então uma renderização final dele responde 409 render_final_not_preview.

Cobrar só a taxa. POST /v1/use-case-fee com { type, workflowId? } cobra sozinha a taxa por execução de um nó de caso de uso, para um cliente que planeja a edição por conta própria e monta o resultado no próprio editor. O painel Editar com IA da Edição manual faz clipes curtos, um trailer e capítulos assim. type é um tipo de nó de caso de uso, como clip-pack, episode-trailer, episode-chapters, tighten-episode ou speaker-layout. A taxa é a mesma cobrada por uma execução do nó no canvas, liquidada na hora em uma tarefa própria, e a rota responde 200 { jobId }. Chame a rota depois que o resultado estiver pronto, para que uma execução que não fez nada nunca seja cobrada. Ela é recusada antes de qualquer reserva: 400 validation_error para um tipo que não é um nó de caso de uso, 403 node_not_available para um nó que esta implantação não oferece a você, e 402 insufficient_credits. Só no Nodaro Cloud.

No SDK, as rotas são client.edit.episodeChapters, episodeTrailer, clipPack e speakerLayout, cada uma com um método estimate…, e continueUseCase continua qualquer uma delas. Na CLI, são nodaro edit episode-chapters, episode-trailer, clip-pack e speaker-layout. Pelo MCP, use make_chapters, make_trailer, make_clip_pack, speaker_layout e continue_use_case.

Dentro de um workflow, um nó Enxugar episódio com Revisar antes de renderizar ativado precisa que uma pessoa o revise, no editor ou na página do próprio app. Em uma execução de workflow iniciada pela API, pelo SDK, pelo run_workflow do MCP ou por um gatilho, os nós antes dele são executados e cobrados, e o nó então falha com preview_review_required, sem nenhuma cobrança por ele. Desative Revisar antes de renderizar nessas execuções. Um nó com revisão ativada alimentado por uma Lista é recusado antes de qualquer execução dele começar, com use_case_review_list_driven. O SDK chama as mesmas rotas com client.edit.tightenEpisode, client.edit.estimateTightenEpisode e client.edit.continueUseCase, e a CLI com nodaro edit tighten-episode e nodaro edit continue-use-case. Pelo MCP, use tighten_episode e continue_use_case.

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. Deixe endTime de fora para cortar de startTime até o fim do clipe; um endTime que você envia precisa vir depois de startTime.

O clipe é medido antes da cobrança. Um clipe que não pode ser lido responde 400 invalid_video_duration. Uma medição que estoura o tempo responde 503 probe_timeout, e um host que não pode ser encontrado naquele momento responde 503 source_unreachable. Um clipe que o servidor não conseguiu ler naquele momento responde 503 probe_unavailable. Nos três casos, execute a requisição de novo. Um link para uma playlist de transmissão contínua, ou para um arquivo em um formato que o servidor não lê, responde 400 media_link_not_a_file. Veja Links de mídia. POST /v1/combine-videos mede cada um dos clipes da mesma forma, e mais de 100 clipes é um 400 validation_error antes de qualquer clipe ser lido.

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.

CampoO que faz
stylesubtitle (um bloco estático) ou um estilo cinético: word-highlight, karaoke, tiktok-words, word-pop ou bouncy.
textEm subtitle: a própria legenda, embutida como um bloco estático durante todo o vídeo. Em um estilo cinético: só o texto de reserva, usado quando a transcrição não encontra nada.
captionsEntradas com tempo por palavra, { text, startMs, endMs }, uma por palavra nos estilos cinéticos. As words de uma transcrição servem como estão.
auto_transcribe, transcribe_providerTranscreve a fala quando nada mais fornece as palavras. Um estilo cinético precisa de marcações de tempo por palavra: incredibly-fast-whisper (o padrão), elevenlabs-stt ou nemotron-3-5-transcribe.
lookoutline (o padrão nos estilos cinéticos) ou clean (o padrão em subtitle).
maxWordsPerLineDe 1 a 20 palavras por linha, além do limite imposto pela largura do quadro. Com 1 ou 2, a leitura fica mais impactante.
highlightColor, animateSó nos estilos cinéticos; 400 em subtitle.
position, positionY, fontSize, fontFamily, fontWeight, color, backgroundColor, strokeColor, strokeWidth, uppercaseA aparência do texto.
segmentsDá a trechos do vídeo um estilo, um visual e uma posição próprios.

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.
  • 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 da tarefa avisa isso. Sem áudio, ela dura o número de imagens vezes perImageDuration, em silêncio. Veja Apresentação de slides.

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 e vídeos a um vídeo

POST /v1/video-overlay coloca de 1 a 20 camadas de imagem ou de vídeo sobre um vídeo em uma única renderização. Cada camada é { imageUrl | videoUrl, sound?, start, end?, preset?, corner?, anchor?, x?, y?, width?, height?, fit?, opacity?, animate?, zIndex? }, com exatamente um entre imageUrl e videoUrl. 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. animate vem ativado por padrão em uma camada de imagem e desativado em uma camada de vídeo.

  • Camadas de vídeo. Uma requisição pode trazer no máximo 2 camadas de vídeo. Uma camada de vídeo toca a partir do primeiro quadro em start e mantém o último quadro até o fim da janela dela. Ela fica sem som, a menos que tenha sound: { volume }, de 0 a 1. O som dela é então mixado com o áudio do vídeo base. Sem som ativado, o áudio base fica intacto.
  • baseBox posiciona o vídeo base no quadro: { anchor, width, x?, y?, height?, fit? }. Ele exige outputAspect, e a parte descoberta do quadro mostra backgroundColor.
  • layout posiciona o vídeo base, a primeira camada de vídeo ou os dois: video-bottom, video-top, stack-whole, stack-filled ou pip. Todo layout, exceto pip, exige outputAspect. As duas pilhas e pip exigem uma camada de vídeo, e uma pilha não aceita baseBox. Caso contrário, a requisição responde 400 validation_error.

outputAspect (16:9, 9:16, 1:1 ou 4:5) muda o quadro, com baseFit e backgroundColor. A tarefa retorna { videoUrl, thumbnailUrl, width, height, durationSec, warnings }. Cada usuário pode enviar 30 requisições por minuto. Veja Sobreposição em vídeo.

Preço. Uma execução só com camadas de imagem custa 22 créditos, qualquer que seja o número de camadas. Uma execução com uma camada de vídeo é cobrada a cada 5 segundos iniciados do vídeo base. Nesse caso, o servidor mede o vídeo base primeiro. Ele recusa estas requisições antes de qualquer cobrança:

ErroQuando
400 video_overlay_too_longO vídeo base tem mais de 60 segundos.
400 invalid_media_durationA duração do vídeo base não pode ser lida.
400 video_overlay_starts_after_endTodas as camadas, ou a primeira camada de vídeo de uma pilha, começam depois do fim do vídeo base.

Uma execução só com camadas de imagem, cujas camadas começam todas depois do fim, falha na renderização e é reembolsada.

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 uma tarefa.

MétodoCaminhoCorpoO que faz
POST/v1/audio-separation{ audioUrl, mode?, quality? }Divide uma faixa: vocal_instrumental (o padrão) ou stems completos, com qualidade auto, fast ou best. Veja Separação de áudio.
POST/v1/audio-isolation{ audioUrl }Mantém a voz principal e remove o fundo. Veja Extrator de voz.
POST/v1/audio-fx{ audioUrl, preset?, mix?, delayMs?, decay?, eqLow?, eqHigh? }Um efeito de reverberação, eco, telefone ou megafone. Veja Efeitos de áudio.
POST/v1/mix-audio{ audioUrls, trackVolumes?, duck?, endAt? }Sobrepõe de 2 a 20 faixas, cada uma de 0 a 200 por cento. duck é { under, amount?, thresholdDb?, ratio?, attackMs?, releaseMs? }: todas as faixas, exceto audioUrls[under], baixam enquanto essa faixa está alta. O preço é o mesmo com ou sem duck. endAt é "longest" (o padrão) ou "voice", que termina a mixagem quando a faixa duck.under termina e exige duck. Veja Mixar áudio.
POST/v1/adjust-volume{ audioUrl or videoUrl, volume?, normalize?, fadeIn?, fadeOut? }Muda o nível, normaliza ou aplica fade. Veja Ajustar volume.
POST/v1/pitch-tempo{ audioUrl or videoUrl, semitones?, tempo?, preserveFormants? }Muda o tom de -12 a 12 semitons, ou altera o andamento de 0,5 a 2 sem mudar o tom. Um vídeo mantém a imagem, e o andamento dele fica em 1. 22 créditos por minuto iniciado da entrada, até 30 minutos. Veja Tom e andamento.
POST/v1/combine-audio{ segments: [{ url, startTime?, endTime? }] }Junta segmentos um após o outro. Veja Combinar áudio.
POST/v1/trim-audio{ audioUrl or videoUrl, startTime?, endTime?, audioFormat? }Corta áudio, ou extrai o áudio de um vídeo, como mp3 (o padrão), wav ou aac. Veja Cortar áudio.
POST/v1/silence-detect{ audioUrl, thresholdDb?, minSilenceMs?, padMs? }Encontra os intervalos de silêncio de uma gravação. 11 créditos. Veja Detectar silêncio.
POST/v1/audio-sync{ sources: [{ id, url }], reference? }Mede as defasagens entre as gravações (de 2 a 6) de uma mesma conversa. Veja Sincronizar áudio.
POST/v1/speaker-map{ sources: [{ id, url, kind? }], transcript, offsets?, masterSourceId?, wideSourceId?, marginDb? }Descobre em qual câmera cada falante está, a partir dos microfones das próprias câmeras. Um preço fixo por execução. Veja Mapa de falantes.

speaker-map recebe de 2 a 6 fontes com ids únicos. kind: "audio" marca uma gravação só de som, que nunca é a câmera de ninguém, assim como a principal e o plano aberto. A transcrição precisa de rótulos de falante, e offsets é um resultado de audio-sync. Enquanto um falante fala, a câmera que o ouve mais alto por pelo menos marginDb (de 0 a 30, padrão 3) é a dele. Caso contrário, o falante recebe "" e aparece no plano aberto. Uma lista de fontes inválida responde 400 validation_error, e uma transcrição sem falantes 422 no_speakers, antes de qualquer reserva. O output_data.json dele é { version, speakerMap, confidence, notes, edl? }. Envie speakerMap para POST /v1/camera-switch.

silence-detect recebe um arquivo de áudio ou de vídeo. thresholdDb vai de -90 a 0 (padrão -35), minSilenceMs de 1 a 600.000 (padrão 700) e padMs de 0 a 60.000 (padrão 120). O output_data.json dele é { 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 uma tarefa. O corpo é { audioUrl, provider?, language?, diarize?, tagAudioEvents?, wordTimestamps?, targetLanguage?, confirmationId? }, e audioUrl também pode ser um vídeo. Um audioUrl que aponta para a página de um vídeo é uma importação desse link: envie o confirmationId confirmado para ele. Veja Direitos de conteúdo.

providerTempo por palavraObservações
elevenlabs-sttSempreO único mecanismo que respeita diarize (quem falou cada palavra) e tagAudioEvents (risos, aplausos).
incredibly-fast-whisperCom wordTimestamps: trueSem a flag, a tarefa é bem-sucedida, é cobrada e retorna só frases.
whisperNuncaSó frases. wordTimestamps: true retorna 400 validation_error antes de qualquer crédito ser gasto.
nemotron-3-5-transcribe (Nemotron 3.5 Transcribe)Com wordTimestamps: trueAcrescenta um speaker por palavra. O único mecanismo que traduz: veja abaixo.

No Nemotron 3.5 Transcribe, targetLanguage (para o inglês ou a partir dele) retorna uma tradução no lugar, sem os tempos das palavras. Em outro mecanismo, ou junto com wordTimestamps: true, ele responde 400 validation_error. O Nemotron é cobrado por minuto iniciado do áudio. O arquivo é medido antes de qualquer reserva, e a execução é cobrada pela duração que o modelo decodificou. Um arquivo cuja duração não pode ser lida reserva o preço de 60 minutos. Ele só aceita um link https para um host público, de até 60 minutos e 200 MB. Qualquer outra coisa responde 400 antes de qualquer cobrança: invalid_media_url, media_duration_exceeds_limit, media_size_exceeds_limit ou media_page_link_unsupported. A saída pode trazer truncated. Veja Traduzir a fala.

Omitir provider executa whisper, então indique um mecanismo sempre que precisar de marcações de tempo por palavra. O output_data da tarefa concluída 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.

MétodoCaminhoO que faz
GET/v1/social/providersAs redes aceitas e se cada uma está disponível nesta implantação.
GET/v1/social/connectionsAs suas contas conectadas.
DELETE/v1/social/connections/:idDesconecta uma conta.
POST/v1/social/telegram/connectConecta o Telegram com um token de bot: { botToken }.
POST/v1/social/connect/customConecta uma rede que usa campos em vez de login: { platform, fields }.
POST/v1/social/publishPublica agora. Retorna uma tarefa. 11 créditos.
POST/v1/social/scheduled-postsAgenda um post. 11 créditos, cobrados quando ele é publicado.
GET/v1/social/scheduled-postsOs seus posts agendados, filtrados por from, to e status.
PATCH/v1/social/scheduled-posts/:idEdita um post enquanto ele está queued ou draft.
DELETE/v1/social/scheduled-posts/:idCancela um post na fila. O histórico dele é mantido.

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 e Publicar nas redes sociais.

Equivalentes no SDK e na CLI

ÁreaTypeScript SDKCLI
Vozes e modificação de vozclient.voices.list, searchLibrary, libraryFacets, listFavorites, favorite, unfavorite, listClones, deleteClone, change, recast, analyze, exportMix, design, remix, dubnodaro voice list, favorites, favorite, unfavorite, changer, recast, analyze, export, design, remix, dub, clones
Mídiaclient.media.downloadVideo, downloadVideoProgress, videoMetadata, trimVideo, trimAudio, addCaptions, stillToVideo, slideshow, videoOverlay, saveToStorage, processnodaro media download, metadata, trim-video, trim-audio, add-captions, still-to-video, slideshow, video-overlay, save
Áudioclient.audio.separate, isolate, applyFx, mix, adjustVolume, pitchTempo, combine, transcribenodaro audio separate, isolate, fx, mix, adjust-volume, pitch-tempo, combine, transcribe
Auxiliares de ediçãoclient.edit.silenceDetect, audioSync, speakerMap, editPlanCapabilities e client.media.shotCutsnodaro edit silence-detect, audio-sync, speaker-map, capabilities

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

StatusCódigoSignificado
400validation_errorUm campo está ausente ou é inválido, por exemplo wordTimestamps no whisper, um campo de estilo que exige um estilo de legenda cinético ou uma exportação com todas as faixas sem som.
400provider_not_configuredA implantação não configurou essa rede social.
401unauthorizedO token está ausente, é inválido ou foi revogado.
402insufficient_creditsSó no Nodaro Cloud. A conta não tem créditos para cobrir a tarefa.
404not_foundUma rota do Modificador de voz Pro foi chamada em uma implantação que não a oferece.
409limit_reachedVocê já tem 500 vozes favoritas.
409not_editableO post agendado já está sendo publicado.
410voice_cloning_retiredA clonagem de voz não é mais oferecida.
413—O trecho dublado tem mais de 30 minutos.
429too_many_downloadsJá há 4 importações de vídeo em andamento na sua conta.
500publish_failedO resultado do post é desconhecido. Verifique a rede antes de enviar de novo.
502preview_unavailableO arquivo de prévia do provedor não pode ser servido.
503publish_retryableNada foi postado. É seguro enviar a mesma requisição de novo.
503voice_library_warmingA implantação está lendo a Biblioteca de vozes pela primeira vez. Tente de novo depois dos segundos de Retry-After.

Perguntas frequentes

Como troco as vozes de vários falantes em um vídeo?

Use POST /v1/voice-changer-pro com orderedVoices, uma entrada por falante detectado, na ordem. Uma entrada null mantém a voz original desse falante. Para verificar os falantes antes, execute a etapa analyze, depois faça a troca de voz em stems e exporte a sua própria mixagem.

Posso clonar uma voz pela API?

Os clones salvos foram descontinuados, e as rotas de clonagem retornam 410 voice_cloning_retired. Os clones feitos antes continuam funcionando como IDs de voz. O Gemini 3.8 Flash pode clonar a sua própria voz para uma única requisição com o campo replica, e o clone nunca é salvo. Para uma nova voz salva, crie uma a partir de uma descrição com POST /v1/voice-design.

Qual mecanismo de transcrição retorna marcações de tempo por palavra?

elevenlabs-stt sempre retorna marcações de tempo por palavra, e incredibly-fast-whisper as retorna quando você envia wordTimestamps true. whisper retorna só frases. Omitir provider executa whisper, então indique um mecanismo quando precisar das palavras.

Qual pode ser a duração de um clipe dublado?

O trecho dublado pode ter até 30 minutos, e o preço é por minuto, com mínimo de 1 minuto. Para uma origem mais longa, duble uma janela com startTime e endTime.

Quais ferramentas de mídia são gratuitas?

Imagem fixa para vídeo, Apresentação de slides e a rota síncrona de corte e recorte POST /v1/media/process custam 0 créditos. Sobreposição em vídeo custa 22 créditos por execução só com camadas de imagem. Com uma camada de vídeo, o preço é calculado a cada 5 segundos iniciados do vídeo base. Detectar silêncio custa 11 créditos.

Última atualização

Nesta página