קולות ואודיו

client.voices עובד עם הקולות של ElevenLabs: הוא מחזיר רשימות של קולות ומחפש ביניהם, מחליף את הקול בהקלטה, נותן קול חדש לכל דובר, מעצב קולות חדשים ומדבב אודיו ווידאו לשפות אחרות. המשאב client.audio מציע את אבני הבניין של האודיו כל אחת בנפרד: הפרדה, בידוד קול, אפקטים, מיקס, עוצמה, איחוד ותמלול. כל מתודת יצירה מחזירה jobId; בדקו את הסטטוס של המשימה מדי כמה שניות עם client.jobs.getStatus(). המתודות קוראות לנקודות הקצה שבדף ה-API קול ומדיה.

מתודות

client.voices: קולות

voices.list()‎

מחזירה את רשימת הקולות המוכנים מראש של ElevenLabs (GET /v1/voices). כשלא מוגדר בשרת מפתח של ElevenLabs, המתודה מחזירה במקום זאת קבוצת קולות שנבחרה בקפידה.

list(): Promise<Voice[]>

const voices = await client.voices.list()

voices.searchLibrary(params?)‎

מחפשת בספריית הקולות של הקהילה (GET /v1/voices/library). כל הפרמטרים הם אופציונליים, וערכים ריקים לא נשלחים, כדי שברירות המחדל של השרת יחולו. השדה hasMore בתשובה מציין אם יש עמוד נוסף.

searchLibrary(params?: VoiceLibraryParams): Promise<{ voices: Voice[]; hasMore: boolean }>

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

כל קול יכול לכלול שני רמזים על מודלי הדיבור שהוא אומת עליהם:

• recommendedProvider הוא המודל הטוב ביותר לקול. אפליקציות בלי תפריט בחירת מודל צריכות לשלוח אותו כ-provider לרכיב טקסט לדיבור, כדי שהקול יישמע כמו בדוגמה שלו בספרייה.
• verifiedProviders מפרט את כל המודלים שהקול אומת עליהם. אפליקציות עם תפריט בחירת מודל צריכות להחליף את הבחירה של המשתמש רק כשהיא לא ברשימה הזו.

בשני הרמזים המודלים מופיעים לפי הסדר ElevenLabs v4, ElevenLabs v3, ElevenLabs v4 Turbo, Turbo v2.5 ובסוף Multilingual v2. הערך של recommendedProvider הוא הפריט הראשון ב-verifiedProviders. בדקו אם מודל נמצא ברשימה, ולעולם אל תשוו לקבוצה קבועה של ערכים: מודל דיבור שיתווסף בעתיד ייכנס לרשימה מרגע שהוא זמין. שני הרמזים מציינים רק מודלים שההתקנה מציעה. קול שאין לו בהתקנה מודל מאומת לא כולל אף אחד משני השדות, ולכן השאירו את המודל הנוכחי של המשתמש.

voices.listClones()‎

מחזירה את רשימת הקולות המשוכפלים שלכם (GET /v1/voice-clones). קולות משוכפלים שנוצרו לפני ששכפול הקולות הוצא משימוש עדיין עובדים כמזהי קול בכל מקום שמקבל קול.

listClones(): Promise<VoiceClone[]>

const clones = await client.voices.listClones()

voices.deleteClone(id)‎

מוחקת אחד הקולות המשוכפלים שלכם (DELETE /v1/voice-clones/:id).

deleteClone(id: string): Promise<void>

await client.voices.deleteClone(cloneId)

voices.createClone()‎ ו-createCloneFromFile()‎

Nodaro כבר לא מציע שכפול קולות. שכפול הקולות הוצא משימוש בספטמבר 2026. שתי המתודות עדיין קיימות בלקוח ומסומנות כמיושנות. הן נכשלות עם NodaroError שה-code שלה הוא voice_cloning_retired, עם סטטוס 410. כדי ליצור קול חדש משלכם, קראו למתודה design().

client.voices: החלפת קול

voices.change(input)‎

מחליפה את הקול בהקלטה, או בסרטון שלם עם דיבור, בקול אחר (POST /v1/voice-changer), כמו רכיב משנה קול. עם videoUrl, השרת מחלץ את האודיו מהסרטון, מחליף את הקול ומחזיר את הקול החדש לסרטון, עם התמונה המקורית.

change(input: {
  voiceId: string
  audioUrl?: string
  videoUrl?: string
  model?: string
  stability?: number
  similarityBoost?: number
  style?: number
  useSpeakerBoost?: boolean
  seed?: number
  removeBackgroundNoise?: boolean
}): Promise<{ jobId: string }>

const { jobId } = await client.voices.change({
  videoUrl: "https://example.com/talking.mp4",
  voiceId: "Aria",
})
// the finished job's output_data has videoUrl and audioUrl

voices.recast(input)‎

נותנת לכל דובר שזוהה בהקלטה קול אחר (POST /v1/voice-changer-pro), כמו רכיב משנה קול Pro. החלפת הקולות רצה ב-Nodaro Cloud כמשימה, ועולה קרדיטים.

recast(input: VoiceChangerProInput): Promise<{ jobId: string }>

כל פריט ב-orderedVoices הוא אחד מאלה:

• מזהה קול: שם של קול מוכן מראש, כגון "Rachel", או מזהה קול של ElevenLabs.
• null: פריט שמירת מקור. הדובר הזה שומר על הקול שלו, והקולות של הדוברים שאחריו עדיין מוחלפים. פריטי שמירת מקור לא עולים כלום, כי משלמים רק על דוברים שהקול שלהם מוחלף.
• אובייקט עם voiceId ועם הגדרות לדובר הזה: stability, similarityBoost ו-style מ-0 עד 1, useSpeakerBoost ו-seed מ-0 עד 4,294,967,295. השדה volumeMode הוא "match" (ברירת המחדל, העוצמה של הדובר המקורי), "normalize" או "manual" עם volume באחוזים, מ-0% עד 200%. עם engine: "v3", ElevenLabs v3 מקריא את השורה מחדש מהתמלול שלה, עם תמיכה בתגי אודיו ([audio tags]), במקום להמיר את הדיבור המוקלט. עם engine: "v4", ElevenLabs v4 עושה את אותו הדבר, מקבל כל ערך של stability מ-0 עד 1 ומחיל את similarityBoost.

דובר 0 מקבל את orderedVoices[0], דובר 1 מקבל את orderedVoices[1], וכן הלאה. דוברים שמעבר לפריט האחרון שומרים על הקול שלהם. הקול והמוזיקה תמיד מופרדים קודם. הפרמטר preserveBackground קובע רק אם המוזיקה חוזרת למיקס.

השדה voiceFx.preset הוא חלל ריוורב (room, bathroom, car, hall, concert-hall, church, cave, arena או outdoor), telephone, megaphone, echo או custom. ערכות הריוורב משתמשות ב-wetDryMix מ-0 עד 100. הערכות echo ו-custom משתמשות ב-delayMs מ-20 עד 2,000 וב-decay מ-0 עד 1.

// Recast speakers 0 and 2, and keep speaker 1's own voice
const { jobId } = await client.voices.recast({
  audioUrl: "https://example.com/panel.mp3",
  orderedVoices: ["Rachel", null, "Aria"],
})

// Repeatable voices, a hall reverb, and finer separation
const { jobId: tuned } = await client.voices.recast({
  audioUrl: "https://example.com/dialogue.mp3",
  orderedVoices: [
    { voiceId: "Rachel", seed: 12345, stability: 0.6 },
    { voiceId: "Aria", seed: 67890, volumeMode: "manual", volume: 120 },
  ],
  voiceFx: { preset: "hall", wetDryMix: 35 },
  separationQuality: "best",
})

במצב וידאו, ב-output_data של המשימה שהסתיימה נמצאים videoUrl ו-audioUrl.

voices.analyze(input)‎

מזהה את הדוברים בקליפ בלי להחליף את הקולות (POST /v1/voice-changer-pro/analyze). המתודה מפרידה את הקול מהמוזיקה פעם אחת ומוצאת מי מדבר ומתי. הניתוח רץ ב-Nodaro Cloud כמשימה, במחיר קבוע.

analyze(input: {
  audioUrl?: string
  videoUrl?: string
  separationQuality?: "fast" | "best"
  suggestTitle?: boolean
}): Promise<{ jobId: string }>

השדה output_data של המשימה שהסתיימה הוא VcpAnalysis: הרצועות המופרדות vocalsUrl ו-backgroundUrl, הדוברים שזוהו ב-speakers (לכל אחד id, מקטעי זמן ב-segments, firstStartSec, wordCount וקטע טקסט ב-snippet), languageCode עם languageProbability, ובנוסף suggestedTitle כשמבקשים אותו. העבירו את התוצאה הזו כ-analysis לכל קריאה מאוחרת יותר ל-recast(), כדי שהחלפת הקולות תשתמש שוב ברצועות המופרדות, בלי לשלם שוב על הזיהוי.

voices.exportMix(input)‎

מרנדרת את הסרטון הסופי ממיקס של סטמים (POST /v1/voice-changer-pro/export). זה השלב האחרון אחרי recast({ output: "stems" }). הייצוא רץ ב-Nodaro Cloud כמשימה, במחיר קבוע.

exportMix(input: {
  videoUrl: string
  tracks: Array<{ url: string; gain: number; muted: boolean; kind?: "voice" | "background" }>
  voiceFx?: { preset: AudioFxPreset; wetDryMix?: number; delayMs?: number; decay?: number }
}): Promise<{ jobId: string }>

בזרימה האינטראקטיבית מנתחים פעם אחת, מחליפים את הקולות לסטמים, ואז עושים מיקס ומרנדרים. כך היא נראית עם פונקציית עזר קטנה לתשאול:

import type { VcpAnalysis } from "@nodaro/sdk"

async function outputOf(jobId: string): Promise<any> {
  for (;;) {
    const { data } = await client.jobs.getStatus(jobId)
    if (data.status === "completed") return data.output_data
    if (data.status === "failed" || data.status === "cancelled") throw new Error(data.error_message ?? data.status)
    await new Promise((resolve) => setTimeout(resolve, 2_000))
  }
}

const { jobId: analyzeJob } = await client.voices.analyze({ videoUrl })
const analysis = (await outputOf(analyzeJob)) as VcpAnalysis

const { jobId: recastJob } = await client.voices.recast({
  videoUrl,
  orderedVoices: ["Rachel", null, "Aria"],
  output: "stems",
  analysis,
})
const stems = await outputOf(recastJob)

const { jobId: exportJob } = await client.voices.exportMix({
  videoUrl,
  tracks: [
    { url: stems.tracks[0].url, gain: 100, muted: false },
    { url: stems.tracks[1].url, gain: 90, muted: false },
    { url: stems.backgroundUrl, gain: 70, muted: false, kind: "background" },
  ],
  voiceFx: { preset: "hall", wetDryMix: 25 },
})
const { videoUrl: finalVideo } = await outputOf(exportJob)

ערכי ה-gain, ההשתקות והאפקט מוחלים ברינדור של הסרטון, והתמונה מועתקת כמו שהיא. לכן הייצוא תואם את התצוגה המקדימה שלכם, ואפשר לשנות את המיקס כמה פעמים שרוצים לפני הייצוא. מיקס שכל הרצועות בו מושתקות נדחה עם 400.

client.voices: יצירה ותרגום

voices.design(input)‎

יוצרת קול סינתטי חדש מתיאור כתוב (POST /v1/voice-design), כמו רכיב עיצוב קול. המשימה שהסתיימה כוללת האזנה מקדימה ואת המזהה של הקול החדש, שאפשר להשתמש בו בכל מקום שמקבל קול.

design(input: {
  text: string
  voiceDescription: string
  model?: string
  loudness?: number
  guidanceScale?: number
  seed?: number
  quality?: number
  shouldEnhance?: boolean
  userPrompt?: string
}): Promise<{ jobId: string }>

const { jobId } = await client.voices.design({
  text: "Welcome back. Tonight we follow the river north, into the mountains where the story began.",
  voiceDescription: "A calm, deep voice of an older male narrator with a slight British accent",
})

voices.remix(input)‎

מקריאה טקסט בקול שמתואר במילים פשוטות, בלי ליצור קול (POST /v1/voice-remix), כמו רכיב רמיקס קול.

remix(input: { text: string; voiceDescription: string; userPrompt?: string }): Promise<{ jobId: string }>

const { jobId } = await client.voices.remix({
  text: "Your order is on its way.",
  voiceDescription: "A cheerful young woman, fast and upbeat",
})

voices.dub(input)‎

מדבבת אודיו, או סרטון שלם, לשפה אחרת ושומרת על הקול של כל דובר (POST /v1/dubbing), כמו רכיב דיבוב. דיבוב של סרטון מחזיר את output_data.videoUrl, הקליפ המדובב, ואת output_data.audioUrl, רצועת האודיו המדובבת לבדה.

dub(input: DubbingInput): Promise<{ jobId: string }>

const { jobId } = await client.voices.dub({
  videoUrl: "https://example.com/interview.mp4",
  targetLanguage: "es",
  numSpeakers: 2,
})

המחיר נקבע לפי הדקות של הקטע המדובב, עם מינימום של דקה אחת. אורך הקטע הוא 30 דקות לכל היותר, ולכן במקורות ארוכים יותר השתמשו ב-startTime וב-endTime.

שירות הדיבוב מושך בשבילכם את sourceUrl, ולכן שליחה שלו היא ייבוא של הקישור הזה, שחלה עליו הצהרת זכויות התוכן. העבירו את ה-confirmationId שהמתודה contentRights.confirm() החזירה עבורו. בלי מזהה כזה, פריסה שדורשת אישור דוחה את הדיבוב עם 403, עוד לפני שהמשימה נוצרת. מפתח או סוכן שבחשבון שלו יש הרשאה קבועה (contentRights.authorize()) לא צריכים מזהה כזה.

voices.textToDialogue(input)‎

מקריאה תסריט עם כמה דוברים כקובץ אודיו אחד (POST /v1/text-to-dialogue), כמו רכיב טקסט לדיאלוג עם ElevenLabs Dialogue v3 או עם ElevenLabs Dialogue v4.

textToDialogue(input: {
  dialogue: Array<{ text: string; voice: string }>
  provider?: "elevenlabs-dialogue" | "elevenlabs-dialogue-v4"
  stability?: number
  similarityBoost?: number
  languageCode?: string
  seed?: number
  applyTextNormalization?: "auto" | "on" | "off"
}): Promise<{ jobId: string }>

const { jobId } = await client.voices.textToDialogue({
  dialogue: [
    { text: "Did you hear that?", voice: "Rachel" },
    { text: "[whispers] Stay behind me.", voice: "Callum" },
  ],
})

תסריט יכול להיות באורך של עד 5,000 תווים ב-Dialogue v3 ועד 10,000 ב-Dialogue v4, והאיכות הטובה ביותר מתקבלת בפחות מ-2,000 תווים. בתסריט אפשר להשתמש ב-10 קולות שונים לכל היותר. קולות מספריית הקולות, קולות שעוצבו וקולות משוכפלים קיימים עובדים כולם, בכל שילוב. הקובץ נמצא ב-output_data.audioUrl של המשימה שהסתיימה. בשני המודלים, ב-output_data.transcript נמצאים התזמונים: המערך words[] עם startMs, endMs ו-speaker, ופריט אחד ב-segments[] לכל שורה, שבו השדה speaker הוא ה-voice של השורה. העבירו את transcript.words ל-addCaptions עם autoTranscribe: false כדי להוסיף כתוביות לדיאלוג בלי תמלול נוסף.

client.audio

כאן נמצאות, כל אחת בנפרד, אבני הבניין של האודיו שרכיב משנה קול Pro משתמש בהן מאחורי הקלעים. כל מתודה מחזירה jobId.

audio.separate(input)‎

מפצלת רצועה לסטמים (POST /v1/audio-separation), כמו רכיב הפרדת אודיו.

separate(input: { audioUrl: string; mode?: "vocal_instrumental" | "stems"; quality?: "auto" | "fast" | "best" }): Promise<{ jobId: string }>

const { jobId } = await client.audio.separate({ audioUrl: songUrl })
// output: vocalUrl and instrumentalUrl, or one URL per stem in stems mode

audio.isolate(input)‎

שומרת על הקול הראשי ומסירה רעשי רקע (POST /v1/audio-isolation), כמו רכיב מחלץ קול.

isolate(input: { audioUrl: string }): Promise<{ jobId: string }>

const { jobId } = await client.audio.isolate({ audioUrl: interviewUrl })

audio.applyFx(input)‎

מוסיפה אפקט של ריוורב, הד, טלפון או מגפון (POST /v1/audio-fx), כמו רכיב אפקטי אודיו. הערכות זהות לאלה של voiceFx בהחלפת הקול.

applyFx(input: {
  audioUrl: string
  preset?: AudioFxPreset
  mix?: number
  delayMs?: number
  decay?: number
  eqLow?: number
  eqHigh?: number
}): Promise<{ jobId: string }>

const { jobId } = await client.audio.applyFx({ audioUrl: lineUrl, preset: "telephone" })

audio.mix(input)‎

משלבת כמה רצועות בשכבות לרצועה אחת (POST /v1/mix-audio), כמו רכיב מיקס אודיו.

mix(input: {
  audioUrls: string[]
  trackVolumes?: number[]
  duck?: { under: number; amount?: number; thresholdDb?: number; ratio?: number; attackMs?: number; releaseMs?: number }
  endAt?: "longest" | "voice"
}): Promise<{ jobId: string }>

const { jobId } = await client.audio.mix({ audioUrls: [voiceUrl, musicUrl], trackVolumes: [100, 35] })

// The music dips under the voice (track 0) while it speaks.
const ducked = await client.audio.mix({ audioUrls: [voiceUrl, musicUrl], duck: { under: 0, amount: 80 } })

audio.adjustVolume(input)‎

משנה את העוצמה של קובץ אודיו, או של הסאונד של סרטון (POST /v1/adjust-volume), כמו רכיב כוונון עוצמה.

adjustVolume(input: {
  audioUrl?: string
  videoUrl?: string
  volume?: number
  normalize?: boolean
  fadeIn?: number
  fadeOut?: number
}): Promise<{ jobId: string }>

const { jobId } = await client.audio.adjustVolume({ audioUrl: musicUrl, volume: 60, fadeOut: 3 })

audio.pitchTempo(input)‎

מזיזה את גובה הצליל, או משנה את הטמפו בלי לשנות את גובה הצליל (POST /v1/pitch-tempo), כמו רכיב גובה צליל וטמפו. שלחו בדיוק אחד מהשניים, audioUrl או videoUrl. כשהמקור הוא סרטון, התמונה שלו נשמרת, והטמפו שלו נשאר 1.

pitchTempo(input: {
  audioUrl?: string
  videoUrl?: string
  semitones?: number
  tempo?: number
  preserveFormants?: boolean
}): Promise<{ jobId: string }>

ההרצה עולה 22 קרדיטים לכל דקה של הקלט, או חלק ממנה, עד 30 דקות.

const { jobId } = await client.audio.pitchTempo({ audioUrl: voiceUrl, semitones: -3 })

audio.combine(input)‎

מאחדת מקטעי אודיו ברצף, זה אחרי זה (POST /v1/combine-audio), כמו רכיב שילוב אודיו.

combine(input: { segments: Array<{ url: string; startTime?: number; endTime?: number }> }): Promise<{ jobId: string }>

const { jobId } = await client.audio.combine({
  segments: [{ url: introUrl }, { url: episodeUrl, startTime: 4 }, { url: outroUrl }],
})

audio.transcribe(input)‎

הופכת את הדיבור בקובץ אודיו או וידאו לטקסט (POST /v1/transcribe), כמו רכיב תמלול.

transcribe(input: {
  audioUrl: string
  provider?: "elevenlabs-stt" | "incredibly-fast-whisper" | "whisper"
  language?: string
  diarize?: boolean
  tagAudioEvents?: boolean
  wordTimestamps?: boolean
  confirmationId?: string
}): Promise<{ jobId: string }>

שליחת audioUrl שמקשר לדף של סרטון ברשת חברתית היא ייבוא של הקישור הזה: Nodaro מוריד קודם את הסאונד שלו. העבירו את ה-confirmationId שהמתודה contentRights.confirm() החזירה לקישור הזה. בלי מזהה כזה, פריסה שדורשת אישור דוחה את הבקשה עם 403, עוד לפני שהמשימה נוצרת. מפתח או סוכן שבחשבון שלו יש הרשאה קבועה (contentRights.authorize()) לא צריכים מזהה כזה. גם קישור ישיר לקובץ לא צריך מזהה כזה.

בקשה בלי provider רצה על whisper, ולכן גם בקשה עם wordTimestamps: true ובלי provider נדחית עם 400. כדי לקבל תזמון לכל מילה, ציינו את elevenlabs-stt, או את incredibly-fast-whisper עם wordTimestamps: true. כתוביות מונפשות צריכות את התזמון הזה.

const { jobId } = await client.audio.transcribe({ audioUrl: talkUrl, provider: "elevenlabs-stt" })

השדה output_data של המשימה שהסתיימה הוא TranscribeJobOutput:

המבנה של words זהה בדיוק למבנה של captions שהמתודה client.media.addCaptions() מקבלת, כך שאפשר לתקן תמלול ולצרוב אותו ככתוביות.