Voice and media

The voice and media endpoints expose Nodaro's voice and media tools as plain REST. They cover the voice catalog, voice changing and multi-speaker recasting, dubbing, voice design, video import, captions, trimming, audio tools, transcription and social publishing. Most of them are jobs: the POST returns { jobId } at once, you poll GET /v1/jobs/:id/status until the status is completed, and you read the result from output_data.

The routes work on every edition, with the exceptions marked below, and take a bearer token. See Authentication, and Jobs for polling many jobs at once. To send local files, upload them first; see Uploads.

Voices

Wherever a route accepts a voice, pass a catalog voice's voice_id, a premade voice's name such as Rachel, or a clone's elevenlabsVoiceId. Clones made before the retirement keep working everywhere.

A Voice Library result may carry recommendedProvider: the text-to-speech model the voice is verified on. When your app has no model picker, send it as provider on Text to Speech, so the voice sounds like its preview. verifiedProviders lists every model the voice is verified on; when your app has a picker, override the user's choice only when it is not in that list. hasMore in the response drives "load more".

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

Filter the Voice Library

• use_cases groups the library the way a picker shows categories: advertisement, characters_animation, conversational, entertainment_tv, informative_educational, narrative_story or social_media. Send one value per call.
• descriptives is one tone word, such as calm, deep or cute. Send one value per call.
• Each voice carries its descriptive (the library's one-word tone, "" when none), its primary language and locale ("" when unstated), and verifiedLanguages: every language code the voice is verified for, the primary first. language matches against verifiedLanguages, so a voice in English that is verified for Spanish is listed under language=es.

GET /v1/voices/library/facets takes the same filters without paging and sort, and answers { total, use_cases, languages, descriptives, genders, ages, accents, categories, approximate, updatedAt }. Each facet is a list of { value, count }, sorted by count, with zero counts left out.

• total applies every filter. Each facet's counts apply every filter except that facet's own, so a picker can show every category's count while one is chosen.
• languages counts a voice under every language it is verified for, so those counts add up to more than total.
• The counts come from the platform's own copy of the library, read on a schedule. updatedAt says when, so a count can trail the listing by a few voices. With search, the counts are a lower estimate and approximate is true.
• The route is public and free, and can be cached for 5 minutes. For a few minutes after a deployment first reads the library, it answers 503 voice_library_warming with Retry-After. A deployment without a speech key answers zero counts with keyMissing: true.

Favorite voices

Your favorite voices are shared by every client you use: a premade voice, a Voice Library voice or one of your clones, starred once and read back everywhere.

• GET /v1/voices/favorites answers { favorites: [{ voiceId, voiceType, name, previewUrl, createdAt }] }, newest first. voiceId and voiceType are what Text to Speech takes as voice and voiceType. name and previewUrl are the snapshot you starred the voice with.
• PUT /v1/voices/favorites/:voiceId takes { voiceType: "premade" | "library" | "custom", name, previewUrl? } and answers { favorite }. Starring a voice again refreshes its snapshot. Past 500 favorites it answers 409 limit_reached.
• DELETE /v1/voices/favorites/:voiceId answers { success: true }, also for a voice that was not starred.
• Scopes: an OAuth app token needs assets:read for the list and assets:write for the two writes.

Voice previews from the deployment's own host

A deployment can serve voice previews from its own host. There, both GET /v1/voices and GET /v1/voices/library give each preview_url as a signed address of GET /v1/voices/:voiceId/preview, instead of the speech provider's address. Play the address as it is given.

• The route needs no bearer token, because an <audio> element sends none. The signature is the credential.
• It answers the audio, with 206 for a byte range. An address the lists did not give answers 404, a voice the deployment's voice lock refuses answers 400 voice_not_available, and a file the provider cannot serve answers 502 preview_unavailable.
• On any other deployment the route answers 404.

Design a voice, or speak in a described voice

For Voice Design, text is a preview line of 100 to 1,000 characters, loudness runs from -1 to 1 and guidanceScale from 0 to 100. For Voice Remix, text is 1 to 5,000 characters. Both return a job.

Change the voice in a recording

POST /v1/voice-changer replaces the voice in an audio track, or in a whole talking video, with one target voice. Send exactly one of audioUrl or videoUrl; when you send both, the video wins. For a video, Nodaro takes the audio out, changes the voice and puts it back on the original picture, and the job's output_data carries both videoUrl and 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

See Voice Changer for prices and tips.

Recast several speakers

Voice Changer Pro detects each speaker in a recording and gives each one a different voice, keeping the words and the timing. It runs on Nodaro Cloud. A self-hosted install connected to Nodaro Cloud can run the one-shot recast through that connection; the analyze and export steps need Nodaro Cloud itself. See Cloud connect.

Map voices to speakers

orderedVoices maps speakers by detection order: speaker 0 gets entry 0, speaker 1 gets entry 1, and so on, with 1 to 8 entries. Speakers past the end of the list keep their own voice. Each entry is one of:

• A voice id, such as "Rachel".
• null, a keep-slot: that speaker keeps their own voice, and later speakers are still recast. Keep-slots cost nothing, but at least one entry must be a voice.
• An object with per-speaker settings: { voiceId, engine?, stability?, similarityBoost?, style?, useSpeakerBoost?, seed?, volumeMode?, volume?, languageCode? }. engine is sts (the default, speech-to-speech), v3 or v4. v3 performs the line again from the transcript with ElevenLabs v3 and takes a stability of 0, 0.5 or 1 only. v4 does the same with ElevenLabs v4, takes any stability from 0 to 1 and applies similarityBoost. languageCode is accepted with v4 only, to speak a translated line, as described below. volumeMode is match (the default), normalize or manual, with volume from 0 to 200 percent.

Before recasting, Nodaro always separates the voices from the music and effects. The rest of the body controls the result:

The recast is charged per mapped speaker; analyze and export have flat prices. See Voice Changer Pro for the prices.

Re-speak in another language. POST /v1/voice-changer-pro/translate translates the speakers of an analysis into one target language, segment by segment. Each line gets a length budget, so the re-spoken line fits its slot. The body is { speakers, targetLanguage, sourceLanguage?, tier? }, where speakers comes from the analysis and tier is economy, standard or premium. The job's output_data.speakers keeps every speaker, segment and timing, with the translated text, the original in sourceText, and untranslated, the ids of lines left in the source language. Review the text, then send these speakers as the recast's analysis.speakers, with engine: "v4" and languageCode set to the target language on each re-spoken voice. languageCode with sts or v3, or a language the model does not offer, answers 400. The translation is priced by the length of the text, with a minimum price and a maximum per started 1,000 characters that depend on the tier. Off Nodaro Cloud, the four voice-changer-pro routes answer 404.

The interactive flow: analyze, recast to stems, export

The one-shot recast renders a finished video in one call. The interactive flow lets you check the speakers before you pay for the recast, and mix the result before you render it.

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

In the CLI, the word keep in --voices is a keep-slot.

Dub into another language

POST /v1/dubbing translates and revoices an audio track or a whole video, keeping each speaker's voice. Send exactly one source: audioUrl, videoUrl, or sourceUrl (a public link to where a video is, or a direct media link, that the dubbing model fetches itself). A sourceUrl is an import of that link: send the confirmationId confirmed for it. See Content rights. A video comes back as a dubbed video: output_data.videoUrl, plus the dubbed track alone in output_data.audioUrl.

A dub is priced per minute of the dubbed span, with a 1-minute minimum. The span can be up to 30 minutes; a longer one answers 413, so dub a window with startTime and endTime. See Dubbing.

Import a video from a link

POST /v1/download-video imports the video behind a link, the video's page or a direct link to a video file, into your storage. It returns { downloadId }, not a job id. The finished file lands in your library.

An import of a link runs the content rights check before anything is fetched. A confirmation that does not fit, or a site that the deployment does not allow, answers 403 with the code that says why. See Content rights.

Follow the download with GET /v1/download-video/progress/:downloadId, a stream of server-sent events. About every 500 ms it sends { phase, percent, videoUrl?, thumbnailUrl?, error? }, and it ends at completed, with the stored videoUrl, or at failed, with the error. Start listening as soon as the import starts, because the progress is kept only briefly after the download ends. At most 4 downloads run per account at once; a fifth answers 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"

Two related routes answer at once:

• POST /v1/video-metadata with { url } reads a video's duration, size, title and live status without downloading it. Use it to decide whether to import only a section.
• POST /v1/save-to-storage with { mediaUrl, filename?, mediaType? } copies any external media URL into your storage, on the server. It returns a job.

Edit video

Edit Plan, Camera Switch, Speaker View and the planning steps of Tighten Episode, Chapters, Trailer, Clip Pack and Speaker Layout run on Nodaro Cloud. A self-hosted install runs them through its Nodaro Cloud connection, and answers 503 nodaro_connection_required without one.

POST /v1/camera-switch takes leadMs and lagMs (whole milliseconds, 0 to 5,000, default 0): leadMs moves each cut earlier, and lagMs delays it. POST /v1/speaker-view takes accentColor (#RRGGBB), the color of the Border emphasis. With no switch, Speaker View cuts between the speakers, and with no emphasis it draws none. A Speaker View render from videoUrl refuses a file over 500 MB with 422 video_too_large.

POST /v1/shot-cuts takes { videoUrl, frames? }: an MP4, MOV, MKV or WebM video up to 30 minutes and about 10.7 GiB. It scores every decoded frame, and each hard cut starts a new shot. Dissolves and fades are not cuts. The job's output_data.json is { shotCount, cutsSec, durationSec, shots: [{ index, startSec, endSec, durationSec, firstFrameUrl?, lastFrameUrl? }] }, in seconds to the millisecond. With frames: true, the exact first and last frame of each shot are saved as PNG, for up to 1,000 shots. A file that is not a readable video, or is over a limit, fails and is refunded. The price is the same with or without frames.

POST /v1/split-media takes videoUrl, audioUrl or both, chunkDuration (the longest a part may be, at least 1 second), minPartDuration (default 4, never above chunkDuration) and audioFormat (mp3, wav or aac). The finished job's output_data has videoUrls, audioUrls, chunkCount and partDurationsSec.

{ videoUrl, mode: "shots" } instead cuts a video into one part per shot, at the cuts measured from the file. It takes no part length and a video only: a separate audioUrl is a 400 validation_error. Each part keeps the video's own sound. Videos can be up to 30 minutes long, with at most 200 shots, at the same price. The output then adds shotCount and shots: [{ index, startSec, endSec, durationSec }]. See Split into Chunks for how the parts are cut.

GET /v1/edit-plan/capabilities lists the Edit Plan modes this server can plan: { modes, source, perMinute }. tighten, clips and chapters are always listed, and trailer only when the server can plan a trailer. perMinute is true when Edit Plan is charged per started minute of the master recording. Otherwise it is charged at the 15, 30, 60, 90, 120 or 180-minute step the recording rounds up to. The SDK reads the route with client.edit.editPlanCapabilities(), and the CLI with nodaro edit capabilities. A mode the server does not list answers 400 mode_not_available on POST /v1/edit-plan, before anything is charged.

On Nodaro Cloud, POST /v1/edit-plan also refuses these before anything is charged: a request with no mode (422 unknown_mode), no source with a media URL (422 no_source), a master source whose length cannot be read or is zero (422 probe_failed, 422 invalid_duration), a source over 180 minutes (422 source_too_long) and a transcript with no timed words (400 empty_transcript). planTier defaults to standard. The MCP tool plan_edit is offered on Nodaro Cloud only, not on a self-hosted install.

Tighten an episode

POST /v1/tighten-episode runs Tighten Episode on a recording. The body is { mediaUrls, masterAudioUrl?, cameras?, musicUrl?, output?, framing?, framingSource?, captions?, captionStyle?, reviewBeforeRender?, planTier?, instructions?, styleGuide?, musicDuckAmount? }. mediaUrls holds one video or audio recording, up to 3 hours long and with sound, or up to six recordings of one conversation. See Several cameras. framing is { aspect, layout } or null. The route answers 202 with { jobId, executionId }.

• Follow the job with GET /v1/jobs/:id/status. Its output_data carries the episode (videoUrl, or audioUrl for an audio episode), the edit (json), the transcript (transcript) and quality: proxy for the preview of a review run, final otherwise. A run of several recordings or a Master audio adds cameras, who was put on which camera. A failed run keeps what completed and names the step that failed in failedStep.
• Retry safely. An Idempotency-Key header makes a retry of the same request answer with the same jobId and "deduped": true, and start nothing.
• Price it first. POST /v1/tighten-episode/estimate takes the same body and answers { data: { totalCredits, stepsCredits, feeCredits, durationSec } } without starting anything. It adds estimate: true when a step is a metered LLM call's estimate: show the total as ≈N. The estimate prices the render at the recording's full length, so the run usually costs less.
• Continue a run. POST /v1/tighten-episode/continue with { jobId, mode } continues one of your runs. "mode": "from-failed" runs only what a failed run did not complete. "mode": "render-final", with an optional editedEdl that holds your edit of the plan, renders the final of a review run.

A Render final of a run that was not a preview answers render_final_not_preview, and one of an edit that was already rendered answers render_final_already_rendered on every route except Chapters. Continuing a run that did not fail answers 409 continuation_not_failed.

Chapters, Trailer, Clip Pack and Speaker Layout

Four more routes run a podcast or interview edit in one call, the way POST /v1/tighten-episode does. They are the routes of the Chapters, Trailer, Clip Pack and Speaker Layout nodes. Each answers 202 with { jobId, executionId }, and each runs its steps as jobs of their own. A run costs its steps at their own rates plus a per-run fee. Each route has an /estimate route that takes the same body and answers { data: { totalCredits, stepsCredits, feeCredits, durationSec } }, and a /continue route. An Idempotency-Key makes a retry answer the same run.

mediaUrls holds one recording up to 3 hours long, with sound, or up to six recordings of one conversation. Trailer and Speaker Layout need a video, and an audio-only run is refused with 400 media_needs_video. Speaker Layout takes at most five cameras: a sixth place is for the sound, a Master audio or one sound-only recording. A run of several recordings or a Master audio adds cameras to output_data.

• Refused before anything is created or charged: a recording that cannot be read (400 media_unreadable), has no sound (400 media_has_no_audio) or runs over 3 hours (400 media_too_long), and a Master audio that cannot be read (400 master_audio_unreadable). See Errors.
• A run that keeps part of its work completes. A Trailer with some formats, or a Clip Pack with some clips, completes and keeps its fee. A clip that failed is not charged. With nothing rendered, the run fails and its fee is refunded.
• A Chapters run that finds no chapters fails, and its fee is refunded. Every step of it completed, so /continue answers 409 continuation_not_failed. Run it again, for example with other instructions.
• Continue a run with { jobId, mode }. "mode": "from-failed" runs what a failed run did not complete. "mode": "render-final" renders a review run's final, with no fee. On Trailer it takes an optional editedEdl, and on Clip Pack an editedEdl that keeps some clips. A Clip Pack review that drops every clip answers 409 use_case_nothing_kept. Speaker Layout takes no editedEdl: one sent answers 400 use_case_no_plan. Chapters renders nothing, so a Render final of it answers 409 render_final_not_preview.

In the SDK, the routes are client.edit.episodeChapters, episodeTrailer, clipPack and speakerLayout, each with an estimate… method, and continueUseCase continues any of them. In the CLI they are nodaro edit episode-chapters, episode-trailer, clip-pack and speaker-layout. Over MCP, use make_chapters, make_trailer, make_clip_pack, speaker_layout and continue_use_case.

Inside a workflow, a Tighten Episode node with Review before render on needs a person to review it, in the editor or on an app's own page. In a workflow run started from the API, the SDK, MCP's run_workflow or a trigger, the nodes before it run and are charged, and the node then fails with preview_review_required, with nothing charged for it. Turn Review before render off for those runs. A review-on node fed by a List is refused before any of its runs starts, with use_case_review_list_driven. The SDK calls the same routes with client.edit.tightenEpisode, client.edit.estimateTightenEpisode and client.edit.continueUseCase, and the CLI with nodaro edit tighten-episode and nodaro edit continue-use-case. Over MCP, use tighten_episode and continue_use_case.

Trim a video

POST /v1/trim-video takes videoUrl and the range in the unit you prefer: startTime and endTime in seconds, trimStartFrames and trimEndFrames, trimStartSeconds and trimEndSeconds, or keepFirstSeconds or keepLastSeconds.

Burn in captions

POST /v1/add-captions takes videoUrl and the words from the first source it finds, in this order: captions (word-timed entries), transcript, text on the subtitle style, then automatic transcription of the speech.

A plain-text subtitle with no styling is the cheap render. A kinetic style, any styling field, timed captions, automatic transcription or segments renders at the higher price and keeps the source frame rate. See Add Captions for every option and both prices.

Turn stills into video

• POST /v1/still-to-video takes { imageUrl, audioUrl, motion?, intensity?, resolution?, aspectRatio?, fps?, fit?, padColor? }. The video lasts as long as the audio; there is no duration field. motion is none (the default), zoom-in, zoom-out, pan-left, pan-right or ken-burns, at an intensity from 1 to 10. See Still to Video.
• POST /v1/slideshow takes imageUrls (2 to 100), an optional audioUrl, imageDurations (seconds per image, null for automatic) or perImageDuration, a transition and the same look fields. With audio, the slideshow lasts as long as the audio; pinned durations that do not add up are scaled, and the job output says so. Without audio, it lasts the number of images times perImageDuration, in silence. See Slideshow.

Both render on the server with no AI model and cost 0 credits. resolution is 720p, 1080p or 4K, fps is 24 or 30, and fit: "contain" letterboxes with padColor instead of cropping.

Overlay images and videos on a video

POST /v1/video-overlay places 1 to 20 image or video layers over a video in one render. Each layer is { imageUrl | videoUrl, sound?, start, end?, preset?, corner?, anchor?, x?, y?, width?, height?, fit?, opacity?, animate?, zIndex? }, with exactly one of imageUrl and videoUrl. start and end are seconds; without end, the layer lasts until the video ends. preset is card, corner-badge or full-frame, and an explicit position or size overrides it. A layer with neither is a corner badge, bottom-right unless corner says otherwise. animate is on by default for an image layer and off for a video layer.

• Video layers. A request can carry at most 2 video layers. A video layer plays from its first frame at start, and holds its last frame until its window ends. It is silent unless it has sound: { volume }, from 0 to 1. Its sound is then mixed with the base video's audio. With no sound on, the base audio is untouched.
• baseBox places the base video on the frame: { anchor, width, x?, y?, height?, fit? }. It needs outputAspect, and the uncovered part of the frame shows backgroundColor.
• layout places the base video, the first video layer, or both: video-bottom, video-top, stack-whole, stack-filled or pip. Every layout except pip needs outputAspect. The two stacks and pip need a video layer, and a stack takes no baseBox. Otherwise the request answers 400 validation_error.

outputAspect (16:9, 9:16, 1:1 or 4:5) changes the frame, with baseFit and backgroundColor. The job returns { videoUrl, thumbnailUrl, width, height, durationSec, warnings }. Each user may send 30 requests per minute. See Video Overlay.

Price. A run with image layers only costs 22 credits, whatever the number of layers. A run with a video layer is priced per started 5 seconds of the base video. For such a run, the server measures the base video first. It refuses these requests before any charge:

A run with image layers only, whose layers all start after the end, fails at the render and is refunded.

Cut or crop a stored file at once

POST /v1/media/process cuts or crops a file you stored and answers in the same request, for free. The body is { sourceUrl, type, trim?, crop?, format?, deleteSource? }: type is video or audio, trim is { startTime, endTime }, crop is { x, y, width, height }, and format is mp4, webm, mp3, wav, m4a or aac. It returns { data: { url, thumbnailUrl, assetId, sizeBytes, mimeType, metadata } }. deleteSource: true deletes the source afterwards, when it is yours and nothing else uses it.

Edit audio

Each route returns a job.

speaker-map takes 2 to 6 sources with unique ids. kind: "audio" marks a sound-only recording, which is never anyone's camera, and neither are the master and the wide shot. The transcript needs speaker labels, and offsets is an audio-sync result. While a speaker talks, the camera that hears them loudest by at least marginDb (0 to 30, default 3) is theirs. Otherwise the speaker gets "", shown on the wide shot. A bad source list answers 400 validation_error, and a transcript without speakers 422 no_speakers, before anything is reserved. Its output_data.json is { version, speakerMap, confidence, notes, edl? }. Send speakerMap to POST /v1/camera-switch.

silence-detect takes an audio or video file. thresholdDb is -90 to 0 (default -35), minSilenceMs 1 to 600,000 (default 700) and padMs 0 to 60,000 (default 120). Its output_data.json is { version, ranges: [{ startMs, endMs }], durationMs }.

audio-sync costs 11 credits per source after the first: 11 for 2 sources, 33 for 4, 55 for 6. The ids must be unique, and reference must be one of them (the first source by default). Its output_data.json is { version, reference, offsets: [{ sourceId, offsetMs, confidence, driftMsPerHour }], notes }, where a time on the reference equals the time on the source plus offsetMs. Drift is measured and noted, never corrected.

Transcribe speech

POST /v1/transcribe turns speech into text and returns a job. The body is { audioUrl, provider?, language?, diarize?, tagAudioEvents?, wordTimestamps?, targetLanguage?, confirmationId? }, and audioUrl can also be a video. An audioUrl that links to a video's page is an import of that link: send the confirmationId confirmed for it. See Content rights.

On Nemotron 3.5 Transcribe, targetLanguage (to or from English) returns a translation instead, with no word timings. On another engine, or beside wordTimestamps: true, it answers 400 validation_error. Nemotron is priced per started minute of the audio. The file is measured before anything is held, and the run is charged for the length the model decoded. A file whose length cannot be read holds the price of 60 minutes. It takes only an https link to a public host, up to 60 minutes and 200 MB. Anything else answers 400 before anything is charged: invalid_media_url, media_duration_exceeds_limit, media_size_exceeds_limit or media_page_link_unsupported. The output may carry truncated. See Translate the speech.

Omitting provider runs whisper, so name an engine whenever you need word timings. The finished job's output_data holds text, language, words (one { text, startMs, endMs, speaker? } per word, in milliseconds), json (the normalized transcript, also in milliseconds) and, on the older engines only, segments in seconds. words drops straight into captions on 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

Publish to social networks

The connect flows open pop-up windows and are meant for the web app. Publishing works with a personal API token. OAuth app tokens cannot manage connections.

GET /v1/social/providers lists every network with { id, label, connectKind, editor, category, capabilities, available }. category is social (a feed you post to) or publishing (a site you publish articles on). A network the deployment has not set up is listed with available: false, never hidden. Networks that connect with fields (Bluesky, Dev.to, Hashnode, Medium, WordPress and Lemmy) describe their fields in customFields, and Nodaro checks the credential with the network before saving it.

POST /v1/social/publish takes { platform, action, connectionId?, caption?, mediaUrl or mediaItems, … }. Two failures need different handling:

• 503 publish_retryable: nothing was posted. Sending the identical request again is safe.
• 500 publish_failed: the outcome is unknown. Sending again may post twice, so check the network first.

A scheduled post takes { connectionId, action, scheduledAt, caption?, media? }, where each media item is { type, r2Key or url }. The media must be files stored on this deployment, which Nodaro turns into fresh links when the post goes out; links to other sites are refused. Editing a post that is already publishing answers 409 not_editable. See Publish to Social and Publishing to social.

SDK and CLI equivalents

Over MCP, the same routes are tools such as voice_changer, voice_changer_pro, voice_changer_pro_analyze, voice_changer_pro_export, dubbing, transcribe, add_captions and separate_audio. See the MCP tools reference.

Errors