音声とメディア

音声とメディアのエンドポイントは、Nodaro の音声とメディアのツールを、そのまま REST として提供します。ボイスカタログ、ボイスチェンジャーと複数話者の声質変換、吹き替え、ボイスデザイン、動画のインポート、字幕、トリミング、オーディオツール、文字起こし、SNS への公開が含まれます。そのほとんどはジョブです。POST はすぐに { jobId } を返すので、ステータスが completed になるまで GET /v1/jobs/:id/status をポーリングし、結果を output_data から読み取ります。

これらのルートは、下記で示す例外を除き、すべてのエディションで動作し、ベアラートークンを使います。認証を参照してください。複数のジョブを一括でポーリングする方法は、ジョブを参照してください。ローカルファイルを送るには、先にアップロードしてください。アップロードを参照してください。

ボイス

ボイスを受け付けるルートでは、カタログのボイスの voice_id、Rachel のような標準ボイスの名前、またはクローンの elevenlabsVoiceId のいずれかを渡します。廃止より前に作成したクローンは、どこでもそのまま使えます。

ボイスライブラリの結果には recommendedProvider が含まれることがあります。これは、そのボイスの動作が確認されているテキスト読み上げモデルです。アプリにモデルピッカーがない場合は、これをテキストから音声（Text to Speech）の provider として送ると、プレビューと同じ声になります。verifiedProviders には、そのボイスの動作が確認されているモデルがすべて挙げられます。アプリにピッカーがある場合は、ユーザーの選択がこのリストにないときだけ上書きしてください。レスポンスの hasMore は、「さらに読み込む」の表示に使います。

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

ボイスを設計する、または説明どおりのボイスで話す

ボイスデザイン（Voice Design）では、text は 100〜1,000 文字のプレビュー用の文で、loudness は -1〜1、guidanceScale は 0〜100 です。ボイスリミックス（Voice Remix）では、text は 1〜5,000 文字です。どちらもジョブを返します。

録音の声を変更する

POST /v1/voice-changer は、オーディオトラック、または話者が話している動画全体の声を、1 つのターゲットボイスに置き換えます。audioUrl か videoUrl のどちらか 1 つだけを送ってください。両方送った場合は、動画が優先されます。動画の場合、Nodaro は音声を取り出して声を変更し、元の映像に戻します。ジョブの output_data には videoUrl と 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

料金とコツについては、ボイスチェンジャー（Voice Changer）を参照してください。

複数の話者の声を差し替える

ボイスチェンジャー Pro（Voice Changer Pro）は、録音の中の話者をそれぞれ検出し、言葉とタイミングを保ったまま、話者ごとに異なるボイスを割り当てます。Nodaro Cloud 上で動作します。Nodaro Cloud に接続したセルフホスティング環境では、その接続を通じてワンショットでの声質変換を実行できますが、analyze と export のステップには Nodaro Cloud 自体が必要です。Nodaro Cloud への接続を参照してください。

ボイスを話者にマッピングする

orderedVoices は、検出順に話者をマッピングします。話者 0 にはエントリー 0、話者 1 にはエントリー 1 が対応し、以降も同様です。エントリーは 1〜8 個です。リストの範囲を超えた話者は、自分の声のままになります。各エントリーは、次のいずれかです。

• ボイス ID："Rachel" のような ID です。
• null：声を維持するスロットです。その話者は自分の声のままになり、後に続く話者はそれでも声が差し替えられます。声を維持するスロットは無料ですが、少なくとも 1 つのエントリーはボイスを指定する必要があります。
• オブジェクト：話者ごとの設定です。{ voiceId, engine?, stability?, similarityBoost?, style?, useSpeakerBoost?, seed?, volumeMode?, volume? }。engine は sts（デフォルト、speech-to-speech）または v3 のいずれかです。v3 は、文字起こしからそのセリフを ElevenLabs v3 でもう一度発話し直すもので、stability は 0、0.5、1 のいずれかしか指定できません。volumeMode は match（デフォルト）、normalize、manual のいずれかで、manual では volume を 0〜200% で指定します。

声を差し替える前に、Nodaro は必ず、声を音楽や効果音から分離します。残りのボディフィールドで、結果を調整します。

声質変換は、マッピングした話者ごとに課金されます。analyze と export は、一律料金です。料金については、ボイスチェンジャー Pro を参照してください。

インタラクティブなフロー：analyze、ステムへの声質変換、export

ワンショットの声質変換は、1 回の呼び出しで完成した動画をレンダリングします。インタラクティブなフローでは、声質変換の料金を払う前に話者を確認し、レンダリングする前に結果をミックスできます。

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

CLI では、--voices の中の keep という単語が、声を維持するスロットです。

別の言語に吹き替える

POST /v1/dubbing は、オーディオトラックや動画全体を、各話者の声を保ったまま翻訳して吹き替えます。ソースは audioUrl、videoUrl、sourceUrl（YouTube や TikTok のページなど、吹き替えモデル自身が取得できる公開リンク）のいずれか 1 つだけを送ります。動画の場合、output_data.videoUrl に吹き替え済みの動画が返り、output_data.audioUrl には吹き替えたトラックだけが入ります。

吹き替えの料金は、吹き替えた区間の分数単位で、最低 1 分からです。区間は最大 30 分で、それより長い場合は 413 が返されるため、startTime と endTime で区間を指定してください。吹き替え（Dubbing）を参照してください。

リンクから動画をインポートする

POST /v1/download-video は、SNS の動画（YouTube、TikTok、Instagram、X、Facebook）や、動画ファイルへの直接リンクを、あなたのストレージにインポートします。返るのはジョブ ID ではなく { downloadId } です。完成したファイルは、ライブラリに保存されます。

ダウンロードの進行状況は、サーバー送信イベントのストリームである GET /v1/download-video/progress/:downloadId で追跡します。約 500 ミリ秒ごとに { phase, percent, videoUrl?, thumbnailUrl?, error? } が送られ、completed（保存された videoUrl を伴う）または failed（error を伴う）で終わります。ダウンロードが終わった後、進行状況はごく短い間しか保持されないため、インポートが始まったらすぐに待ち受けを開始してください。1 アカウントにつき同時に実行できるダウンロードは最大 4 件で、5 件目は 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"

関連する 2 つのルートは、すぐに応答します。

• POST /v1/video-metadata に { url } を送ると、動画をダウンロードせずに、長さ、サイズ、タイトル、ライブ配信中かどうかを読み取れます。一部の区間だけをインポートするかどうかを判断するのに使えます。
• POST /v1/save-to-storage に { mediaUrl, filename?, mediaType? } を送ると、外部のメディア URL をサーバー上であなたのストレージにコピーします。ジョブを返します。

動画を編集する

動画をトリミングする

POST /v1/trim-video には videoUrl と、好きな単位での範囲を指定します。秒単位の startTime と endTime、trimStartFrames と trimEndFrames、trimStartSeconds と trimEndSeconds、または keepFirstSeconds か keepLastSeconds のいずれかです。

字幕を焼き込む

POST /v1/add-captions には videoUrl を指定し、単語は次の順序で最初に見つかったソースから取得します。captions（単語ごとのタイミング付きエントリー）、transcript、subtitle スタイルの場合は text、それもなければ音声の自動文字起こしです。

スタイルを指定しないプレーンテキストの subtitle は、安価なレンダリングです。キネティックスタイル、いずれかのスタイル関連フィールド、タイミング付きのキャプション、自動文字起こし、segments のいずれかを使うと、より高い料金でレンダリングされ、ソースのフレームレートが保たれます。すべてのオプションと両方の料金については、字幕を追加を参照してください。

静止画を動画にする

• POST /v1/still-to-video は { imageUrl, audioUrl, motion?, intensity?, resolution?, aspectRatio?, fps?, fit?, padColor? } を受け取ります。動画の長さはオーディオと同じで、長さを指定するフィールドはありません。motion は none（デフォルト）、zoom-in、zoom-out、pan-left、pan-right、ken-burns のいずれかで、intensity は 1〜10 です。静止画から動画（Still to Video）を参照してください。
• POST /v1/slideshow は imageUrls（2〜100 枚）、任意の audioUrl、imageDurations（画像ごとの秒数、自動の場合は null）または perImageDuration、transition、そして同じ見た目のフィールドを受け取ります。オーディオがある場合、スライドショーの長さはオーディオと同じになります。指定した長さの合計が一致しない場合は自動的に調整され、ジョブの出力にその旨が示されます。オーディオがない場合は、画像の枚数に perImageDuration を掛けた長さになり、無音になります。スライドショー（Slideshow）を参照してください。

どちらも、AI モデルを使わずにサーバー上でレンダリングされ、0 クレジットです。resolution は 720p、1080p、4K のいずれか、fps は 24 または 30、fit: "contain" にすると、クロップの代わりに padColor でレターボックスにします。

動画に画像を重ねる

POST /v1/video-overlay は、1 回のレンダリングで動画の上に 1〜20 個の画像レイヤーを配置し、元のオーディオには手を加えません。各レイヤーは { imageUrl, start, end?, preset?, corner?, anchor?, x?, y?, width?, height?, fit?, opacity?, animate?, zIndex? } です。start と end は秒単位で、end を省略すると、そのレイヤーは動画の終わりまで続きます。preset は card、corner-badge、full-frame のいずれかで、明示的な位置やサイズを指定すると、それが優先されます。どちらも指定しないレイヤーは、corner で指定しない限り、右下のコーナーバッジになります。

outputAspect（16:9、9:16、1:1、4:5 のいずれか）で、baseFit と backgroundColor とともにフレームを変更できます。ジョブは { videoUrl, thumbnailUrl, width, height, durationSec, warnings } を返します。レイヤーの数にかかわらず、実行ごとに 20 クレジットで、1 ユーザーにつき 1 分あたり 30 リクエストまで送れます。動画オーバーレイ（Video Overlay）を参照してください。

保存済みのファイルを、その場でカットまたはクロップする

POST /v1/media/process は、保存済みのファイルをカットまたはクロップし、同じリクエストの中で無料で応答します。ボディは { sourceUrl, type, trim?, crop?, format?, deleteSource? } で、type は video または audio、trim は { startTime, endTime }、crop は { x, y, width, height }、format は mp4、webm、mp3、wav、m4a、aac のいずれかです。{ data: { url, thumbnailUrl, assetId, sizeBytes, mimeType, metadata } } を返します。deleteSource: true にすると、そのファイルが自分のものであり、ほかで使われていない場合に限り、処理の後にソースを削除します。

オーディオを編集する

各ルートは、ジョブを返します。

silence-detect のデフォルトは thresholdDb: -35、minSilenceMs: 700、padMs: 120 で、オーディオまたは動画を受け付けます。output_data.json は { version, ranges: [{ startMs, endMs }], durationMs } です。

audio-sync は、最初の 1 件を除くソースごとに 10 クレジットかかります。2 件で 10 クレジット、4 件で 30 クレジット、6 件で 50 クレジットです。ID は重複してはならず、reference はそのいずれか 1 つを指定します（デフォルトは最初のソースです）。output_data.json は { version, reference, offsets: [{ sourceId, offsetMs, confidence, driftMsPerHour }], notes } で、リファレンス上の時刻は、ソース上の時刻に offsetMs を加えたものと等しくなります。ドリフトは測定して記録されるだけで、補正はされません。

音声を文字起こしする

POST /v1/transcribe は、音声をテキストに変換し、ジョブを返します。ボディは { audioUrl, provider?, language?, diarize?, tagAudioEvents?, wordTimestamps? } で、audioUrl には動画も指定できます。

provider を省略すると whisper が実行されるため、単語単位のタイミングが必要な場合は、常にエンジンを指定してください。完了したジョブの output_data には、text、language、words（1 単語につき 1 つの { text, startMs, endMs, speaker? }、ミリ秒単位）、json（正規化された文字起こしで、同じくミリ秒単位）、そして古いエンジンでのみ、秒単位の segments が含まれます。words は、そのまま POST /v1/add-captions の 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

SNS に公開する

接続フローはポップアップウィンドウを開くため、Web アプリでの利用を想定しています。公開は、個人用 API トークンで行えます。OAuth アプリのトークンでは、接続を管理できません。

GET /v1/social/providers は、すべてのネットワークを { id, label, connectKind, editor, category, capabilities, available } で一覧表示します。category は、投稿先のフィードを表す social、または記事を公開するサイトを表す publishing のいずれかです。デプロイ環境で設定されていないネットワークも、非表示にはならず、available: false として一覧に含まれます。フィールドで接続するネットワーク（Bluesky、Dev.to、Hashnode、Medium、WordPress、Lemmy）は、そのフィールドを customFields に記述します。Nodaro は、保存する前にそのネットワークで認証情報を確認します。

POST /v1/social/publish は { platform, action, connectionId?, caption?, mediaUrl or mediaItems, … } を受け取ります。2 種類の失敗は、それぞれ異なる対応が必要です。

• 503 publish_retryable：何も投稿されていません。同一のリクエストを再送しても安全です。
• 500 publish_failed：結果が不明です。再送すると二重に投稿される可能性があるため、先にネットワーク側を確認してください。

スケジュール投稿は { connectionId, action, scheduledAt, caption?, media? } を受け取り、各メディア項目は { type, r2Key or url } です。メディアは、このデプロイ環境に保存されたファイルである必要があります。投稿が送信されるときに、Nodaro がこれを新しいリンクに変換します。ほかのサイトへのリンクは拒否されます。すでに公開処理中の投稿を編集すると、409 not_editable が返されます。SNS に公開（Publish to Social）と SNS への公開を参照してください。

SDK と CLI の対応表

MCP 経由では、同じルートが voice_changer、voice_changer_pro、voice_changer_pro_analyze、voice_changer_pro_export、dubbing、transcribe、add_captions、separate_audio のようなツールになります。MCP ツールリファレンスを参照してください。

エラー