NodaroAccount
Nodaro ドキュメント
ドキュメントノードリファレンスモデルテンプレートAI エージェント(MCP)開発者向けセルフホスティングリサーチ比較
REST API

音声とメディア

ボイスカタログ、ボイスチェンジャー、複数話者の声質変換、吹き替え、動画のインポート、字幕、トリミング、オーディオツール、SNS への公開を、Nodaro の REST エンドポイントとして提供します。

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

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

ボイス

メソッドパス説明
GET/v1/voices標準ボイスのカタログです。名前、voice_id、性別、アクセント、年齢が含まれます。?model= に Gemini の音声モデルを指定すると、代わりにそのモデル自身のボイスを返します。
GET/v1/voices/library共有のボイスライブラリを search、gender、age、accent、language、category、use_cases、descriptives、featured、sort、page、page_size で検索します。
GET/v1/voices/library/facets送ったフィルターに対して、グループ、トーン、言語、性別、年齢、アクセント、カテゴリーごとにライブラリのボイスがいくつあるかを返します。
GET/v1/voices/:voiceId/previewプレビューを自分のホストから配信するデプロイメントで、ボイスのプレビューをそのホストから返します。
GET/v1/voices/favoritesお気に入りのボイスを新しい順に返します。
PUT/v1/voices/favorites/:voiceIdボイスをお気に入りに追加します。
DELETE/v1/voices/favorites/:voiceIdボイスをお気に入りから外します。
GET/v1/voice-clonesクローン機能が廃止される前に作成したボイスクローンです。
PATCH/v1/voice-clones/:idクローンの名前を変更するか、内容を編集します。
DELETE/v1/voice-clones/:idクローンを削除します。
POST/v1/voice-clones、/v1/voice-clones/from-url廃止されました。どちらも 410 voice_cloning_retired を返します。
POST/v1/voice-clone/consentログイン中のユーザーの、1 回限りのボイスクローンへの同意を記録します:{ sourceAudioUrl, consentAudioUrl } → { userId, signature }。何も取得、保存、請求されません。

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

Gemini の音声モデル(gemini-3-8-flash-lite-tts、gemini-3-8-flash-tts、gemini-3-1-flash-tts、gemini-2-5-pro-tts)は、それぞれ自身の名前付きボイスだけを話します。GET /v1/voices?model=<model> でそれらを一覧できます。voice_id と name はボイスの名前で、3.8 のモデルでは use_case がそのボイスの用途を示します。ほかのモデルを指定した場合や model を指定しない場合は、標準ボイスのカタログを返します。

保存されない、1 回のリクエストだけの自分の声のクローンは、gemini-3-8-flash-tts での /v1/text-to-speech の replica フィールド、および /v1/text-to-dialogue の話者の replica フィールドで、consent: true とともに使います。テキストから音声を参照してください。公開されたアプリに、作成者の録音が含まれることはありません。アプリを実行する人が、自分の 2 つの WAV 録音と、POST /v1/voice-clone/consent で得た自分の同意を、実行の inputOverrides で送ります。これらがない実行は、何も請求される前に 400 clone_recordings_required または 400 clone_consent_required で拒否されます。

ボイスライブラリの結果には recommendedProvider が含まれることがあります。これは、そのボイスの動作が確認されているテキスト読み上げモデルです。アプリにモデルピッカーがない場合は、これをテキストから音声の 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 } : {}),
})

ボイスライブラリの絞り込み

  • use_cases は、ピッカーがカテゴリーを表示するのと同じようにライブラリをグループ分けします:advertisement、characters_animation、conversational、entertainment_tv、informative_educational、narrative_story、social_media のいずれかです。1 回の呼び出しで 1 つの値を送ります。
  • descriptives は、calm、deep、cute のようなトーンを表す 1 語です。1 回の呼び出しで 1 つの値を送ります。
  • 各ボイスには、descriptive(ライブラリが付けた 1 語のトーン。なければ "")、主な language と locale(記載がなければ "")、verifiedLanguages が含まれます。verifiedLanguages は、そのボイスの動作が確認されているすべての言語コードで、主な言語が先頭です。language は verifiedLanguages と照合されるので、英語のボイスでスペイン語の確認が取れているものは language=es で一覧に出ます。

GET /v1/voices/library/facets は、ページングと並べ替えを除いた同じフィルターを受け取り、{ total, use_cases, languages, descriptives, genders, ages, accents, categories, approximate, updatedAt } を返します。各ファセットは { value, count } のリストで、件数の多い順に並び、件数 0 の値は含まれません。

  • total にはすべてのフィルターが適用されます。各ファセットの件数には、そのファセット自身を除くすべてのフィルターが適用されるので、ピッカーは 1 つのカテゴリーを選んだ状態でも、すべてのカテゴリーの件数を表示できます。
  • languages では、ボイスは確認済みのすべての言語で数えられます。そのため、件数の合計は total より多くなります。
  • 件数は、プラットフォームが定期的に読み込むライブラリのコピーから数えます。 いつ読み込んだかは updatedAt でわかります。そのため、件数が一覧より数件遅れることがあります。search を付けると、件数は下限の見積もりになり、approximate が true になります。
  • このルートは公開で無料です。5 分間キャッシュできます。デプロイメントが初めてライブラリを読み込んでから数分間は、Retry-After 付きで 503 voice_library_warming を返します。音声のキーがないデプロイメントは、keyMissing: true 付きで件数 0 を返します。

お気に入りのボイス

お気に入りのボイスは、使っているすべてのクライアントで共有されます。標準ボイス、ボイスライブラリのボイス、自分のクローンのいずれでも、一度お気に入りに追加すれば、どこでも読み取れます。

  • GET /v1/voices/favorites は、{ favorites: [{ voiceId, voiceType, name, previewUrl, createdAt }] } を新しい順に返します。voiceId と voiceType は、テキストから音声が voice と voiceType として受け取る値です。name と previewUrl は、お気に入りに追加したときのスナップショットです。
  • PUT /v1/voices/favorites/:voiceId は { voiceType: "premade" | "library" | "custom", name, previewUrl? } を受け取り、{ favorite } を返します。もう一度追加すると、スナップショットが更新されます。お気に入りが 500 件を超えると 409 limit_reached になります。
  • DELETE /v1/voices/favorites/:voiceId は { success: true } を返します。お気に入りにないボイスでも同じです。
  • スコープ:OAuth アプリのトークンでは、一覧に assets:read、2 つの書き込みに assets:write が必要です。

デプロイメント自身のホストから配信するボイスのプレビュー

デプロイメントは、ボイスのプレビューを自分のホストから配信できます。その場合、GET /v1/voices と GET /v1/voices/library はどちらも、各 preview_url を、音声プロバイダーのアドレスではなく、GET /v1/voices/:voiceId/preview の署名付きアドレスで返します。アドレスは受け取ったとおりに再生してください。

  • このルートにはベアラートークンが要りません。 <audio> 要素はトークンを送らないからです。署名が認証情報になります。
  • 音声そのものを返します。 バイト範囲の指定には 206 で応えます。一覧が返していないアドレスには 404、デプロイメントのボイス制限が拒否するボイスには 400 voice_not_available、プロバイダーのファイルを配信できないときは 502 preview_unavailable が返されます。
  • それ以外のデプロイメントでは、このルートは 404 を返します。

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

メソッドパスボディ結果
POST/v1/voice-design{ text, voiceDescription, model?, loudness?, guidanceScale?, seed?, quality?, shouldEnhance? }プレビューと、再利用できるボイス ID です。
POST/v1/voice-remix{ text, voiceDescription }クローンを使わずに、説明したボイスで話す音声です。

ボイスデザインでは、text は 100〜1,000 文字のプレビュー用の文で、loudness は -1〜1、guidanceScale は 0〜100 です。ボイスリミックスでは、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
フィールド意味
voiceId必須です。ターゲットのボイスです。
audioUrl または videoUrlいずれか 1 つが必須です。変更する録音です。
model音声から音声へ変換するモデルです。
stability、similarityBoost0〜1 です。話し方の安定度と、ターゲットのボイスにどれだけ近いかを指定します。
style0〜1 で、デフォルトは 0 です。話し方を強調しますが、速度と安定度が多少犠牲になります。
useSpeakerBoostターゲットのボイスへの似せ方をより際立たせます。わずかに処理が遅くなります。
seed出力を再現可能にする整数です。
removeBackgroundNoisetrue の場合はクリーンな声だけを返し、false の場合は音楽や効果音を新しい声の下に残します。

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

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

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

メソッドパス説明
POST/v1/voice-changer-proマッピングしたすべての話者の声を差し替え、完成した動画として、または別々のステムとして出力します。
POST/v1/voice-changer-pro/analyze声を差し替えずに、話者だけを検出します。Nodaro Cloud 専用です。
POST/v1/voice-changer-pro/exportステムの自分のミックスから、完成した動画をレンダリングします。Nodaro Cloud 専用です。
POST/v1/voice-changer-pro/translate検出した文字起こしを別の言語に翻訳し、動画をその言語で話し直せるようにします。Nodaro Cloud 専用です。

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

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

  • ボイス ID:"Rachel" のような ID です。
  • null:声を維持するスロットです。その話者は自分の声のままになり、後に続く話者はそれでも声が差し替えられます。声を維持するスロットは無料ですが、少なくとも 1 つのエントリーはボイスを指定する必要があります。
  • オブジェクト:話者ごとの設定です。{ voiceId, engine?, stability?, similarityBoost?, style?, useSpeakerBoost?, seed?, volumeMode?, volume?, languageCode? }。engine は sts(デフォルト、音声から音声への変換)、v3、v4 のいずれかです。v3 は、文字起こしからそのセリフを ElevenLabs v3 でもう一度発話し直すもので、stability は 0、0.5、1 のいずれかしか指定できません。v4 は同じことを ElevenLabs v4 で行い、stability に 0〜1 の任意の値を指定でき、similarityBoost が適用されます。languageCode は v4 でだけ使え、翻訳したセリフを話すためのものです。下で説明します。volumeMode は match(デフォルト)、normalize、manual のいずれかで、manual では volume を 0〜200% で指定します。

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

フィールド意味
audioUrl または videoUrlいずれか 1 つが必須です。動画の場合、差し替えた音声は元の映像に戻されます。
preserveBackground音楽や効果音を、新しい声の下にミックスして戻します。デフォルトは true です。
separationQualityfast(デフォルト、声をより多く残します)または best(より精細な分離)です。
removeBackgroundNoise結果からさらにノイズを除去します。
musicVolumeMode、musicVolume保持する背景音のレベルです。match(デフォルト)、normalize、または manual(0〜200% を指定)のいずれかです。
voiceFx声だけにかけるリバーブやエコーです。{ preset, wetDryMix?, delayMs?, decay? }。room、hall、church などのリバーブプリセットは wetDryMix を使い、echo と custom は delayMs と decay を使います。
outputvideo(デフォルト、完成した結果)または stems(自分でミックスするための、エフェクトもレベル調整もかけていないトラック)です。
analysis以前の分析ジョブの output_data です。声質変換で、検出をやり直す代わりに、その話者とステムを再利用します。

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

別の言語で話し直す。POST /v1/voice-changer-pro/translate は、分析の話者を、セグメントごとに 1 つの対象言語へ翻訳します。各セリフには長さの予算があり、話し直したセリフが元の枠に収まります。ボディは { speakers, targetLanguage, sourceLanguage?, tier? } で、speakers は分析から取り、tier は economy、standard、premium のいずれかです。ジョブの output_data.speakers は、すべての話者、セグメント、タイミングを保ち、翻訳した text、sourceText に元の文、そして元の言語のまま残ったセリフの ID である untranslated を含みます。テキストを確認してから、これらの話者を声質変換の analysis.speakers として送り、話し直す各声に engine: "v4" と、対象言語を設定した languageCode を付けます。sts や v3 に languageCode を付けた場合や、モデルが対応していない言語を指定した場合は、400 が返されます。翻訳の料金はテキストの長さで決まり、最低料金と、1,000 文字ごと(端数は切り上げ)の上限があり、どちらもティアによって異なります。Nodaro Cloud 以外では、4 つの voice-changer-pro のルートは 404 を返します。

インタラクティブなフロー:分析、ステムへの声質変換、エクスポート

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

話者を検出する

POST /v1/voice-changer-pro/analyze に audioUrl または videoUrl を指定し、必要に応じて separationQuality と suggestTitle も指定します。完了したジョブの output_data には、分離された vocalsUrl と backgroundUrl、検出された languageCode と languageProbability が含まれます。speakers のリストには、話者ごとの id、segments、firstStartSec、wordCount、snippet が入ります。suggestTitle を指定した場合は、suggestedTitle も含まれます。拍手のような、人ではない「話者」が検出されることもあるので注意してください。

ステムに声質変換する

POST /v1/voice-changer-pro に output: "stems" と、分析の output_data 全体を analysis として指定します。声質変換は検出をスキップするため、検出の料金を再度払うことなく、別のボイスでもう一度声質変換できます。

ミックスして書き出す

各ステムのレベルは、自分のインターフェースで設定します。これは無料です。次に、元の videoUrl と、最大 16 個の tracks(それぞれ { url, gain, muted, kind? })を指定して POST /v1/voice-changer-pro/export を呼びます。gain は 0〜200、kind は voice または background で、少なくとも 1 つのトラックはミュートを解除しておく必要があります。任意の voiceFx は、声のトラックにだけ適用されます。動画のストリームはコピーされるだけで、エンコードし直されることはないため、書き出し結果はプレビューと一致します。完了したジョブの output_data.videoUrl が結果です。

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(動画がある場所への公開リンク、またはメディアへの直接リンクで、吹き替えモデル自身が取得するもの)のいずれか 1 つだけを送ります。sourceUrl はそのリンクのインポートなので、そのリンクについて確認した confirmationId を送ってください。コンテンツ権利を参照してください。動画の場合、output_data.videoUrl に吹き替え済みの動画が返り、output_data.audioUrl には吹き替えたトラックだけが入ります。

フィールド意味
targetLanguage必須です。es や pt-BR のような ISO コードです。
sourceLanguage話されている言語です。省略すると自動検出されます。
numSpeakers0(デフォルト)は自動検出します。話者数がわかっている場合は、1〜20 で指定すると分離の精度が上がります。
startTime、endTimeソースのこの区間だけを、秒単位で吹き替えます。
disableVoiceCloning、dropBackgroundAudio各話者自身の声を再現しない、または音楽や効果音を取り除きます。
highestResolution動画のソースの解像度を保ちます。
useProfanityFilter、targetAccent、watermark不適切な言葉のフィルター、対象言語のアクセント、動画上への吹き替えモデルのウォーターマークです。

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

作成後に吹き替えを読み取る

吹き替えは、ジョブの完了後も読み取れます。元の音声のセリフ、各言語とそのセリフ、話者、各言語の字幕です。どちらの読み取りも無料です。あとから吹き替えに言語を追加することもできます。

メソッドパス説明
GET/v1/dubbing/:jobId吹き替えの構造です:{ jobId, durationSec, source, languages, speakers, capabilities, addLanguage }。
GET/v1/dubbing/:jobId/captions1 つの言語、または元の音声の字幕を、SubRip または WebVTT ファイルのテキストとして返します。?language=(吹き替えが挙げている言語コード、または source)と ?format=(デフォルトの srt、または vtt)を送ります。
POST/v1/dubbing/:jobId/languages言語を追加します:{ "targetLanguage": "de" } で、その言語を届けるジョブの { jobId } を返します。

jobId は、吹き替えを作成したジョブ、またはあとから追加した言語のジョブです。吹き替えを読み取れるのは所有者だけで、ほかの人のジョブには 404 not_found が返ります。OAuth アプリでは、読み取りに assets:read、言語の追加に assets:write が必要です。読み取りはそれぞれ 1 分あたり 60 リクエスト、追加の呼び出しは 1 分あたり 10 回までです。

  • languages には、言語ごとに 1 つのエントリーがあります。status は processing、completed、stale(メディアの作成後にセリフが変わった)、failed のいずれかです。segments が入るのは、言語が completed または stale のときだけです。
  • 吹き替えた各セリフには、秒単位の start と end、その text があり、吹き替えが保持している場合は、sourceSegmentId(翻訳元の元の音声のセリフ)と sourceText もあります。
  • speakers は、最初に話した順に並び、それぞれのセリフの数が付きます。
  • capabilities は、今その吹き替えでできることを示します。フラグが true のときだけ、その操作を提示してください。現在 true になりうるフラグは、addLanguage と captions です。
  • addLanguage は、言語を追加する料金を料金 ID で示します。その言語が挙げられていれば creditIdByLanguage[language]、なければ creditId です。POST /v1/credits/model-costs で料金を調べてください。billableMinutes は、追加した言語に課金される分数(整数)です。

言語の追加は、吹き替えの開始した 1 分ごとに課金され、実行は開始前にその料金を確保します。ヘブライ語の吹き替えでは、言語が同じプロジェクトに追加されるので、何も再アップロードされません。それ以外の吹き替えでは、同じソースの新しい吹き替えとして、同じ設定で追加されます。吹き替えにすでにある言語や作成中の言語には 409 dubbing_language_exists が返ります。失敗した言語は、もう一度追加できます。

読み取りは、吹き替えの作成中は 409 dubbing_not_ready、失敗した吹き替えには 422 dubbing_failed、ほかの種類のジョブには 422 not_a_dubbing_job、吹き替えサービスが吹き替えを保持していない場合は 410 dubbing_unavailable を返します。字幕は、書き出せない言語に対して 404 dubbing_language_not_found、409 dubbing_language_processing、または 422 dubbing_captions_unavailable を返します。SDK は、client.dubbing.get、client.dubbing.captions、client.dubbing.addLanguage で同じルートを呼び出します。

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

フィールド意味
url必須です。インポートするページまたはファイルです。
maxHeight解像度の上限で、たとえば 720 です。省略すると、利用できる最高の解像度になります。
sectionStartSec、sectionEndSecこの範囲だけを秒単位でインポートします。カットはキーフレームの位置で行われるため、前後に数秒ずつ長くなります。両方送るか、どちらも送らないかのいずれかにしてください。正確にカットするには、結果をトリミングしてください。
exactSectiontrue にすると、余白なしで、指定した範囲どおりにカットします。
requireAudio音声がない結果は、デフォルトで失敗します。多くの場合、ソースが劣化していることを意味するためです。無音のクリップを受け入れる場合は false を送ります。
confirmationIdこのリンクのコンテンツ権利の確認で、POST /v1/content-rights/confirm から得たものです。コンテンツ権利を参照してください。

動画ファイルへの直接リンクの上限は、長さ 30 分、サイズ 10 GiB です。ヘッダーからどちらかの上限を超えるとわかるファイルには、すぐに 422 が返されます。コードは media_too_long、media_too_large、media_bitrate_implausible のいずれかです。ダウンロードしたファイルはもう一度確認され、通らなかったファイルは残されません。進行状況のストリームは failed で終わり、理由が入ります。ソーシャルネットワークの動画ページへのリンクには、この長さの上限はありません。上限の詳細は、アップロードを参照してください。

リンクのインポートでは、何かを取得する前にコンテンツ権利のチェックが行われます。当てはまらない確認や、デプロイ環境が許可していないサイトの場合は、理由を示すコードとともに 403 が返ります。コンテンツ権利を参照してください。

ダウンロードの進行状況は、サーバー送信イベントのストリームである 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動画を指定した範囲にカットします。動画のトリミング
POST/v1/combine-videos2〜100 本の動画を順番につなぎます。動画を結合
POST/v1/add-captions動画に字幕を焼き込みます。字幕を追加
POST/v1/still-to-video1 枚の画像と 1 つのオーディオトラックから、MP4 を作ります。0 クレジット
POST/v1/slideshow2〜100 枚の画像と、任意のオーディオトラックから、MP4 を作ります。0 クレジット
POST/v1/video-overlay動画の上に、タイミング付きの画像または動画のレイヤーを 1〜20 個配置します。画像レイヤーだけの場合は 22 クレジット。動画レイヤーがある場合は、元の動画の 5 秒(開始した単位)ごと
POST/v1/media/process保存済みのファイルをカットまたはクロップし、すぐに応答します。無料
POST/v1/edit-plan録画の編集を、その文字起こしから計画します。短く詰める、クリップを見つける、チャプターを付ける、予告編を作る、のいずれかです。結果はメディアではなく、編集決定リストです。編集プラン
POST/v1/camera-switch編集の各カットを、話している人のカメラに切り替えます。音声は変わりません。カメラ切り替え
POST/v1/apply-edl編集決定リストを、1 つの動画または音声ファイルにレンダリングします。final か、proxy のプレビューです。EDL 適用
POST/v1/tighten-episodeポッドキャストやインタビューを 1 回の呼び出しで引き締めます。文字起こしをし、無音とつなぎ言葉を取り除き、エピソードをレンダリングし、必要に応じて字幕と BGM を加えます。エピソードを引き締める
POST/v1/episode-chapters録音のチャプターを 1 回の呼び出しで見つけ、番組の概要として書き出します。何もレンダリングしません。ステップの料金と実行ごとの手数料です。チャプターを参照してください。
POST/v1/episode-trailer録音から 20〜40 秒のトレーラーを、選んだ SNS の形式ごとに切り出します。ステップの料金と実行ごとの手数料です。トレーラーを参照してください。
POST/v1/clip-pack録音を、フレーミングと字幕の付いた短いクリップのセットに切り分けます。ステップの料金と実行ごとの手数料です。クリップパックを参照してください。
POST/v1/speaker-layout録音全体を話者ごとにフレーミングします。長さは同じで、何もカットしません。ステップの料金と実行ごとの手数料です。スピーカーレイアウトを参照してください。
POST/v1/shot-cuts動画の各ショットの始まりと終わりを、ファイルから測定して見つけます。実行ごとの定額料金です。ショットカットを参照してください。
POST/v1/speaker-view話者を画面に映した編集を、レイアウトに沿ってレンダリングし、話者が替わるたびに切り替えます。料金は出力 1 分ごとです。話者ビュー
POST/v1/split-media動画、音声ファイル、またはその両方を、最小と最大の長さの間のパートに、または動画をショットごとに 1 つのパートにカットします。1 回の実行につき 22 クレジット
POST/v1/video-maskテキストで指定した被写体を追跡し、白黒のマスク動画を返します。料金はクリップの長さで決まります。動画マスク
POST/v1/mask-compositeマスク動画を通して、前景の動画を背景の動画に重ねます。5 秒ごと(端数は切り上げ)に 11 クレジット
POST/v1/video-depth動画を深度動画に変換します。近いものが明るく、遠いものが暗くなります。料金はクリップの長さで決まります。動画の深度

編集プラン、カメラ切り替え、話者ビューと、エピソードを引き締める、チャプター、トレーラー、クリップパック、スピーカーレイアウトの計画のステップは Nodaro Cloud で実行されます。セルフホスティング環境は Nodaro Cloud への接続を通じて実行し、接続がない場合は 503 nodaro_connection_required を返します。

POST /v1/camera-switch は leadMs と lagMs(整数のミリ秒、0〜5,000、デフォルト 0)を受け付けます。leadMs は各カットを早め、lagMs は遅らせます。POST /v1/speaker-view は、ボーダーの強調の色である accentColor(#RRGGBB)を受け付けます。switch がない場合、話者ビューは話者の間をカットで切り替え、emphasis がない場合は強調を描きません。videoUrl からの話者ビューのレンダリングは、500 MB を超えるファイルを 422 video_too_large で拒否します。

POST /v1/shot-cuts は { videoUrl, frames? } を受け取ります。対象は、最大 30 分、約 10.7 GiB までの MP4、MOV、MKV、WebM の動画です。デコードしたすべてのフレームを評価し、ハードカットごとに新しいショットが始まります。ディゾルブとフェードはカットではありません。ジョブの output_data.json は { shotCount, cutsSec, durationSec, shots: [{ index, startSec, endSec, durationSec, firstFrameUrl?, lastFrameUrl? }] } で、単位はミリ秒までの秒です。frames: true では、最大 1,000 ショットについて、各ショットの正確な最初と最後のフレームが PNG で保存されます。読み取れる動画ではないファイルや、上限を超えるファイルは失敗し、クレジットは返還されます。料金は、フレームの有無にかかわらず同じです。

POST /v1/split-media は、videoUrl、audioUrl またはその両方、chunkDuration(パートの最大の長さ。1 秒以上)、minPartDuration(デフォルトは 4。chunkDuration を超えることはありません)、audioFormat(mp3、wav または aac)を受け取ります。完了したジョブの output_data には、videoUrls、audioUrls、chunkCount、partDurationsSec が含まれます。

{ videoUrl, mode: "shots" } を送ると、代わりに動画をショットごとに 1 つのパートにカットします。カット位置はファイルから測定されます。パートの長さは受け取らず、動画だけを受け取ります。別に audioUrl を送ると 400 validation_error になります。各パートは、動画自体の音声を保ちます。動画は最長 30 分、ショットは最大 200 個で、料金は同じです。この場合、出力には shotCount と shots: [{ index, startSec, endSec, durationSec }] が加わります。パートのカット方法は、チャンクに分割を参照してください。

GET /v1/edit-plan/capabilities は、このサーバーが計画できる編集プランのモードを一覧にします。形は { modes, source, perMinute } です。tighten、clips、chapters は常に含まれ、trailer はサーバーが予告編を計画できる場合にだけ含まれます。perMinute は、編集プランがマスターの録画の 1 分ごと(端数は切り上げ)に課金される場合に true です。そうでない場合は、録画の長さを切り上げた 15、30、60、90、120、180 分の段階で課金されます。SDK では client.edit.editPlanCapabilities()、CLI では nodaro edit capabilities でこのルートを読み取ります。サーバーが一覧にないモードを POST /v1/edit-plan に指定すると、何も請求される前に 400 mode_not_available が返されます。

Nodaro Cloud では、POST /v1/edit-plan は次の場合も、何も請求される前に拒否します。mode のないリクエスト(422 unknown_mode)、メディアの URL を持つソースがない(422 no_source)、マスターのソースの長さを読み取れないか 0 である(422 probe_failed、422 invalid_duration)、180 分を超えるソース(422 source_too_long)、時間付きの単語がない文字起こし(400 empty_transcript)です。planTier のデフォルトは standard です。MCP ツールの plan_edit は Nodaro Cloud でのみ提供され、セルフホスティング環境では使えません。

エピソードを引き締める

POST /v1/tighten-episode は、録画に対してエピソードを引き締めるを実行します。ボディは { mediaUrls, masterAudioUrl?, cameras?, musicUrl?, output?, framing?, framingSource?, captions?, captionStyle?, reviewBeforeRender?, planTier?, instructions?, styleGuide?, musicDuckAmount? } です。mediaUrls には、最大 3 時間で音声のある動画または音声の録音を 1 件、または 1 つの会話の録音を最大 6 件入れます。複数のカメラを参照してください。framing は { aspect, layout } または null です。ルートは { jobId, executionId } とともに 202 を返します。

  • ジョブを追跡します。GET /v1/jobs/:id/status を使います。その output_data には、エピソード(videoUrl、音声のエピソードでは audioUrl)、編集(json)、文字起こし(transcript)、quality が含まれます。quality は、確認する実行のプレビューでは proxy、それ以外では final です。複数の録音またはマスターオーディオでの実行では、誰をどのカメラに割り当てたかを示す cameras が加わります。失敗した実行は完了した部分を保持し、失敗したステップを failedStep で示します。
  • 安全に再試行できます。Idempotency-Key ヘッダーを付けると、同じリクエストの再試行には同じ jobId と "deduped": true が返され、何も開始されません。
  • 先に料金を確認します。POST /v1/tighten-episode/estimate は同じボディを受け取り、何も開始せずに { data: { totalCredits, stepsCredits, feeCredits, durationSec } } を返します。ステップが従量課金の LLM 呼び出しの見積もりの場合は estimate: true が加わるので、合計は ≈N と表示してください。見積もりはレンダリングを録画の全長で計算するので、実際の実行は通常それより安くなります。
  • 実行を続けます。POST /v1/tighten-episode/continue に { jobId, mode } を送ると、自分の実行の 1 つを続けます。"mode": "from-failed" は、失敗した実行が完了しなかった部分だけを実行します。"mode": "render-final" は、確認する実行の最終版をレンダリングします。プランに対する自分の編集を入れた editedEdl を任意で付けられます。

プレビューではなかった実行の最終レンダリングには render_final_not_preview が、すでにレンダリングされた編集の最終レンダリングには、チャプターを除くすべてのルートで render_final_already_rendered が返されます。失敗していない実行を続けようとすると、409 continuation_not_failed が返されます。

チャプター、トレーラー、クリップパック、スピーカーレイアウト

ほかに 4 つのルートが、POST /v1/tighten-episode と同じように、ポッドキャストやインタビューの編集を 1 回の呼び出しで実行します。チャプター、トレーラー、クリップパック、スピーカーレイアウトの各ノードのルートです。どれも { jobId, executionId } とともに 202 を返し、各ステップを独立したジョブとして実行します。実行の料金は、各ステップのそれぞれの料金と、実行ごとの手数料です。各ルートには、同じボディを受け取り { data: { totalCredits, stepsCredits, feeCredits, durationSec } } を返す /estimate ルートと、/continue ルートがあります。Idempotency-Key を付けると、再試行には同じ実行が返されます。

ルートボディoutput_data の結果
POST /v1/episode-chapters{ mediaUrls: [<one recording>], planTier?, instructions?, styleGuide? }。planTier のデフォルトは economy です。text:番組の概要で、チャプターごとに M:SS Title の行が 1 つです(1:00:00 以降に始まるチャプターがあると H:MM:SS)。json:同じチャプターを [{ startMs, title }] で表したもので、最初は 0 です。
POST /v1/episode-trailer{ mediaUrls, masterAudioUrl?, cameras?, introCardUrl?, formats?, reviewBeforeRender?, planTier?, instructions?, styleGuide? }。formats は 9:16、1:1、4:5、16:9 のリストで、デフォルトは最初の 3 つです。introCardUrl は 15 秒以内の動画です。formats:[{ format, url }]。videoUrl:最初の形式。failedFormats:レンダリングできなかった形式。json:トレーラーの編集。
POST /v1/clip-pack{ mediaUrls, masterAudioUrl?, cameras?, count?, targetDurationSec?, framing?, framingSource?, captions?, captionStyle?, reviewBeforeRender?, planTier?, instructions?, styleGuide? }。count は 1〜50(デフォルト 8)、targetDurationSec は 5〜180(デフォルト 60)です。clips:[{ url, title?, hook?, clipKey, thumbnailUrl?, captionsFailed? }]。videoUrl(または audioUrl):最初のクリップ。failedClips と failedCaptions:レンダリングされなかったクリップと、字幕なしになったクリップの数。json:クリップのセット。
POST /v1/speaker-layout{ mediaUrls, masterAudioUrl?, cameras?, targetAspect?, layout?, switchType?, emphasisStyle?, framingSource?, reviewBeforeRender? }。targetAspect のデフォルトは 9:16 です。videoUrl:録音と同じ長さの、フレーミングした動画。durationSec、json(編集)、transcript、quality。

mediaUrls には、最大 3 時間で音声のある録音を 1 件、または 1 つの会話の録音を最大 6 件入れます。トレーラーとスピーカーレイアウトには動画が必要で、音声だけの実行は 400 media_needs_video で拒否されます。スピーカーレイアウトのカメラは最大 5 台で、6 つ目の枠は音声、マスターオーディオ、または音声だけの録音 1 件のためのものです。複数の録音またはマスターオーディオでの実行では、output_data に cameras が加わります。

  • 何も作成も課金もされる前に拒否されます。読み取れない録音(400 media_unreadable)、音声のない録音(400 media_has_no_audio)、3 時間を超える録音(400 media_too_long)、読み取れないマスターオーディオ(400 master_audio_unreadable)です。エラーを参照してください。
  • 作業の一部を残した実行は完了します。一部の形式を持つトレーラーや、一部のクリップを持つクリップパックは完了し、手数料を保持します。失敗したクリップは課金されません。何もレンダリングされなかった場合、実行は失敗し、手数料は返還されます。
  • チャプターが見つからなかったチャプターの実行は失敗し、手数料は返還されます。その実行のステップはすべて完了しているので、/continue は 409 continuation_not_failed を返します。たとえば別の指示で、もう一度実行してください。
  • 実行を続けるには、{ jobId, mode } を送ります。"mode": "from-failed" は、失敗した実行が完了しなかった部分を実行します。"mode": "render-final" は、確認する実行の最終版を手数料なしでレンダリングします。トレーラーでは任意の editedEdl を、クリップパックでは一部のクリップを残す editedEdl を受け付けます。すべてのクリップを外したクリップパックの確認には 409 use_case_nothing_kept が返されます。スピーカーレイアウトは editedEdl を受け付けず、送ると 400 use_case_no_plan が返されます。チャプターは何もレンダリングしないので、その最終レンダリングには 409 render_final_not_preview が返されます。

手数料だけを請求する。 { type, workflowId? } を付けた POST /v1/use-case-fee は、ユースケースノード 1 つの実行ごとの手数料だけを請求します。編集の計画を自分で立て、結果を自分のエディターで組み立てるクライアントのためのルートです。手動編集の AI で編集パネルは、この方法でショートクリップ、トレーラー、チャプターを作ります。type はユースケースノードのタイプで、clip-pack、episode-trailer、episode-chapters、tighten-episode、speaker-layout などです。手数料は、キャンバスでそのノードを実行したときと同じ額で、専用のジョブですぐに確定します。ルートは 200 { jobId } を返します。結果ができてから呼んでください。そうすれば、何も作らなかった実行に手数料がかかることはありません。何かを確保する前に、次の場合は拒否されます。ユースケースノードではないタイプには 400 validation_error、このデプロイメントが提供していないノードには 403 node_not_available、クレジット不足には 402 insufficient_credits が返されます。Nodaro Cloud だけで使えます。

SDK では、これらのルートは client.edit.episodeChapters、episodeTrailer、clipPack、speakerLayout で、それぞれに estimate… メソッドがあり、continueUseCase でどれでも続けられます。CLI では nodaro edit episode-chapters、episode-trailer、clip-pack、speaker-layout です。MCP では make_chapters、make_trailer、make_clip_pack、speaker_layout、continue_use_case を使います。

ワークフローの中では、レンダリング前に確認がオンのエピソードを引き締めるノードは、エディターまたはアプリ自体のページで、人による確認が必要です。API、SDK、MCP の run_workflow、トリガーから開始したワークフローの実行では、その前のノードが実行されて請求され、続いてこのノードが preview_review_required で失敗します。このノードには何も請求されません。そのような実行では、レンダリング前に確認をオフにしてください。リストから入力される、確認がオンのノードは、その実行がどれも始まる前に use_case_review_list_driven で拒否されます。SDK は同じルートを client.edit.tightenEpisode、client.edit.estimateTightenEpisode、client.edit.continueUseCase で呼び出し、CLI は nodaro edit tighten-episode と nodaro edit continue-use-case で呼び出します。MCP では、tighten_episode と continue_use_case を使います。

動画をトリミングする

POST /v1/trim-video には videoUrl と、好きな単位での範囲を指定します。秒単位の startTime と endTime、trimStartFrames と trimEndFrames、trimStartSeconds と trimEndSeconds、または keepFirstSeconds か keepLastSeconds のいずれかです。endTime を省くと、startTime からクリップの終わりまでをカットします。endTime を送る場合は、startTime より後でなければなりません。

クリップは、請求の前に計測されます。読み取れないクリップには 400 invalid_video_duration が返ります。計測が時間切れになった場合は 503 probe_timeout、その時点でホストを名前解決できない場合は 503 source_unreachable が返ります。その時点でサーバーがクリップを読み取れなかった場合は 503 probe_unavailable が返ります。この 3 つの場合は、リクエストをもう一度実行してください。ストリーミングのプレイリストや、サーバーが読み込めない形式のファイルへのリンクには、400 media_link_not_a_file が返ります。メディアのリンクを参照してください。POST /v1/combine-videos も各クリップを同じ方法で計測し、101 本以上のクリップは、どのクリップも読み取る前に 400 validation_error になります。

字幕を焼き込む

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

フィールド意味
stylesubtitle(静的なブロック)、またはキネティックスタイル:word-highlight、karaoke、tiktok-words、word-pop、bouncy のいずれかです。
textsubtitle の場合:字幕そのもので、動画全体にわたる 1 つの静的なブロックとして焼き込まれます。キネティックスタイルの場合:文字起こしで何も見つからなかったときのフォールバックとしてのみ使われます。
captions単語ごとのタイミング付きエントリー { text, startMs, endMs } で、キネティックスタイルでは単語ごとに 1 つ指定します。文字起こしの words は、そのまま使えます。
auto_transcribe、transcribe_providerほかに単語が得られない場合に、音声を文字起こしします。キネティックスタイルには単語単位のタイミングが必要です:incredibly-fast-whisper(デフォルト)、elevenlabs-stt、または nemotron-3-5-transcribe です。
lookキネティックスタイルではデフォルトが outline、subtitle ではデフォルトが clean です。
maxWordsPerLine1 行あたり 1〜20 語で、フレームの幅による改行に加えて適用されます。1 か 2 にすると、テンポの良い見た目になります。
highlightColor、animateキネティックスタイル専用です。subtitle では 400 です。
position、positionY、fontSize、fontFamily、fontWeight、color、backgroundColor、strokeColor、strokeWidth、uppercaseテキストの見た目です。
segments動画の範囲ごとに、それぞれ異なるスタイル、見た目、位置を指定します。

スタイルを指定しないプレーンテキストの 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 です。静止画から動画を参照してください。
  • POST /v1/slideshow は imageUrls(2〜100 枚)、任意の audioUrl、imageDurations(画像ごとの秒数、自動の場合は null)または perImageDuration、transition、そして同じ見た目のフィールドを受け取ります。オーディオがある場合、スライドショーの長さはオーディオと同じになります。指定した長さの合計が一致しない場合は自動的に調整され、ジョブの出力にその旨が示されます。オーディオがない場合は、画像の枚数に perImageDuration を掛けた長さになり、無音になります。スライドショーを参照してください。

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

動画に画像や動画を重ねる

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

  • 動画レイヤー。1 回のリクエストに含められる動画レイヤーは最大 2 個です。動画レイヤーは start で最初のフレームから再生され、ウィンドウが終わるまで最後のフレームを表示し続けます。sound: { volume }(0〜1)がない限り無音です。指定した場合、その音声は元の動画のオーディオとミックスされます。音声がオンのレイヤーがなければ、元のオーディオには手を加えません。
  • baseBox は、元の動画をフレーム上に配置します:{ anchor, width, x?, y?, height?, fit? }。outputAspect が必要で、フレームの覆われていない部分には backgroundColor が表示されます。
  • layout は、元の動画、最初の動画レイヤー、またはその両方を配置します:video-bottom、video-top、stack-whole、stack-filled、pip のいずれかです。pip 以外のすべてのレイアウトには outputAspect が必要です。2 つのスタックと pip には動画レイヤーが必要で、スタックは baseBox を受け付けません。それ以外の場合、リクエストには 400 validation_error が返されます。

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

料金。画像レイヤーだけの実行は、レイヤーの数にかかわらず 22 クレジットです。動画レイヤーがある実行は、元の動画の 5 秒(開始した単位)ごとに料金が決まります。そのような実行では、サーバーがまず元の動画の長さを測ります。次のリクエストは、課金の前に拒否されます:

エラー条件
400 video_overlay_too_long元の動画が 60 秒を超えています。
400 invalid_media_duration元の動画の長さを読み取れません。
400 video_overlay_starts_after_endすべてのレイヤー、またはスタックの最初の動画レイヤーが、元の動画の終わりより後に始まります。

画像レイヤーだけの実行で、すべてのレイヤーが終わりより後に始まる場合は、レンダリングで失敗し、クレジットが返還されます。

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

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 にすると、そのファイルが自分のものであり、ほかで使われていない場合に限り、処理の後にソースを削除します。

オーディオを編集する

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

メソッドパスボディ説明
POST/v1/audio-separation{ audioUrl, mode?, quality? }トラックを分割します。vocal_instrumental(デフォルト)か、完全な stems のいずれかで、品質は auto、fast、best です。音源分離を参照してください。
POST/v1/audio-isolation{ audioUrl }メインの声を残し、背景音を取り除きます。音声抽出を参照してください。
POST/v1/audio-fx{ audioUrl, preset?, mix?, delayMs?, decay?, eqLow?, eqHigh? }リバーブ、エコー、電話、メガホンのいずれかの効果です。オーディオ FXを参照してください。
POST/v1/mix-audio{ audioUrls, trackVolumes?, duck?, endAt? }2〜20 個のトラックを、それぞれ 0〜200% の音量で重ねます。duck は { under, amount?, thresholdDb?, ratio?, attackMs?, releaseMs? } で、audioUrls[under] の音が大きい間、それ以外のすべてのトラックの音量が下がります。料金は duck の有無で変わりません。endAt は "longest"(デフォルト)または "voice" です。"voice" は duck.under のトラックが終わったところでミックスを終え、duck が必要です。オーディオをミックスを参照してください。
POST/v1/adjust-volume{ audioUrl or videoUrl, volume?, normalize?, fadeIn?, fadeOut? }レベルの変更、ノーマライズ、フェードを行います。音量調整を参照してください。
POST/v1/pitch-tempo{ audioUrl or videoUrl, semitones?, tempo?, preserveFormants? }ピッチを -12〜12 半音シフトするか、ピッチを変えずにテンポを 0.5〜2 の範囲で変更します。動画は映像がそのまま保たれ、テンポは 1 のままです。入力 1 分ごとに 22 クレジットで(1 分未満は切り上げ)、最長 30 分です。ピッチとテンポを参照してください。
POST/v1/combine-audio{ segments: [{ url, startTime?, endTime? }] }セグメントを順につなぎます。オーディオを結合を参照してください。
POST/v1/trim-audio{ audioUrl or videoUrl, startTime?, endTime?, audioFormat? }オーディオをカットするか、動画から取り出します。形式は mp3(デフォルト)、wav、aac のいずれかです。オーディオのトリミングを参照してください。
POST/v1/silence-detect{ audioUrl, thresholdDb?, minSilenceMs?, padMs? }録音の無音区間を見つけます。11 クレジットです。無音検出を参照してください。
POST/v1/audio-sync{ sources: [{ id, url }], reference? }1 つの会話を録音した 2〜6 件の録音の間のオフセットを測定します。音声同期を参照してください。
POST/v1/speaker-map{ sources: [{ id, url, kind? }], transcript, offsets?, masterSourceId?, wideSourceId?, marginDb? }カメラ自身のマイクから、各話者がどのカメラに映っているかを見つけます。実行ごとの定額料金です。話者マップを参照してください。

speaker-map は、ID が重複しない 2〜6 件のソースを受け取ります。kind: "audio" は音声だけの録音を示し、誰のカメラにもなりません。マスターとワイドショットも誰のカメラにもなりません。文字起こしには話者のラベルが必要で、offsets は audio-sync の結果です。話者が話している間、その話者の声を marginDb(0〜30、デフォルト 3)以上の差で最も大きく拾うカメラが、その話者のカメラになります。そうでない場合、話者には "" が割り当てられ、ワイドショットに映ります。不正なソースのリストには 400 validation_error が、話者のない文字起こしには 422 no_speakers が、何も確保される前に返されます。output_data.json は { version, speakerMap, confidence, notes, edl? } です。speakerMap は POST /v1/camera-switch に送ります。

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

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

音声を文字起こしする

POST /v1/transcribe は、音声をテキストに変換し、ジョブを返します。ボディは { audioUrl, provider?, language?, diarize?, tagAudioEvents?, wordTimestamps?, targetLanguage?, confirmationId? } で、audioUrl には動画も指定できます。動画のページにリンクする audioUrl はそのリンクのインポートなので、そのリンクについて確認した confirmationId を送ってください。コンテンツ権利を参照してください。

provider単語のタイミング補足
elevenlabs-stt常にありますdiarize(どの単語をどの話者が話したか)と tagAudioEvents(笑い声、拍手など)に対応する唯一のエンジンです。
incredibly-fast-whisperwordTimestamps: true を指定した場合フラグを指定しない場合、ジョブは成功して課金されますが、フレーズのみが返ります。
whisperなしフレーズのみです。wordTimestamps: true を指定すると、クレジットが使われる前に 400 validation_error が返ります。
nemotron-3-5-transcribe(Nemotron 3.5 Transcribe)wordTimestamps: true を指定した場合単語ごとに speaker を加えます。翻訳できる唯一のエンジンです。下記を参照してください。

Nemotron 3.5 Transcribe では、targetLanguage(英語へ、または英語から)を指定すると、代わりに翻訳を返し、単語のタイミングは付きません。ほかのエンジンや、wordTimestamps: true と一緒に指定すると、400 validation_error になります。Nemotron は、音声の開始した 1 分ごとに課金されます。ファイルは何かが確保される前に測定され、実行はモデルがデコードした長さで課金されます。長さを読み取れないファイルは、60 分の料金を確保します。受け付けるのは、公開ホストへの https リンクで、60 分以内かつ 200 MB 以内のものだけです。それ以外は、課金される前に 400 になります:invalid_media_url、media_duration_exceeds_limit、media_size_exceeds_limit、media_page_link_unsupported。出力に truncated が含まれることがあります。音声を翻訳するを参照してください。

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対応しているネットワークと、それぞれがこのデプロイ環境で利用できるかどうかです。
GET/v1/social/connections接続済みのアカウントです。
DELETE/v1/social/connections/:idアカウントの接続を解除します。
POST/v1/social/telegram/connectボットトークンで Telegram を接続します:{ botToken }。
POST/v1/social/connect/customログインの代わりにフィールドを使うネットワークを接続します:{ platform, fields }。
POST/v1/social/publish今すぐ公開します。ジョブを返します。11 クレジットです。
POST/v1/social/scheduled-posts投稿をスケジュールします。11 クレジットで、公開時に課金されます。
GET/v1/social/scheduled-posts自分のスケジュール済みの投稿を、from、to、status で絞り込んで返します。
PATCH/v1/social/scheduled-posts/:idqueued または draft の間に、投稿を編集します。
DELETE/v1/social/scheduled-posts/:idキュー中の投稿をキャンセルします。履歴は保持されます。

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 に公開と SNS への公開を参照してください。

SDK と CLI の対応表

分野TypeScript SDKCLI
ボイスとボイスチェンジャーclient.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
メディアclient.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
オーディオclient.audio.separate、isolate、applyFx、mix、adjustVolume、pitchTempo、combine、transcribenodaro audio separate、isolate、fx、mix、adjust-volume、pitch-tempo、combine、transcribe
編集ヘルパーclient.edit.silenceDetect、audioSync、speakerMap、editPlanCapabilities、client.media.shotCutsnodaro edit silence-detect、audio-sync、speaker-map、capabilities

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

エラー

ステータスコード意味
400validation_errorフィールドが不足しているか無効です。たとえば whisper に対する wordTimestamps、キネティックな字幕スタイルが必要なスタイル関連フィールド、すべてのトラックがミュートされたエクスポートなどです。
400provider_not_configuredデプロイ環境で、その SNS が設定されていません。
401unauthorizedトークンがないか、無効か、取り消されています。
402insufficient_creditsNodaro Cloud 専用です。アカウントがジョブの料金をまかなえません。
404not_found提供していないデプロイ環境で、ボイスチェンジャー Pro のルートが呼び出されました。
409limit_reachedお気に入りのボイスがすでに 500 件あります。
409not_editableスケジュールされた投稿が、すでに公開処理中です。
410voice_cloning_retiredボイスクローンの提供は終了しています。
413—吹き替えの区間が 30 分を超えています。
429too_many_downloadsこのアカウントで、すでに 4 件の動画インポートが実行中です。
500publish_failed投稿の結果が不明です。再送する前に、SNS 側を確認してください。
502preview_unavailableプロバイダーのプレビューファイルを配信できません。
503publish_retryable何も投稿されていません。同一のリクエストを再送しても安全です。
503voice_library_warmingデプロイメントが初めてボイスライブラリを読み込んでいます。Retry-After の秒数が経ってから再試行してください。

よくある質問

1 本の動画に登場する複数の話者の声を変更するには、どうすればよいですか?

POST /v1/voice-changer-pro を orderedVoices とともに使い、検出された話者の順に 1 人につき 1 つのエントリーを指定します。null のエントリーを使うと、その話者は自分の声のままになります。先に話者を確認したい場合は、分析のステップを実行してから、ステム出力で声質変換し、自分のミックスを書き出してください。

API でボイスクローンを作成できますか?

保存するクローンは廃止されており、クローン用のルートは 410 voice_cloning_retired を返します。廃止前に作成したクローンは、これまでどおりボイス ID として使えます。Gemini 3.8 Flash では、replica フィールドで 1 回のリクエストだけ自分の声をクローンでき、そのクローンは保存されません。新しく保存するボイスは、POST /v1/voice-design で説明文から設計してください。

単語単位のタイミングが得られる文字起こしエンジンはどれですか?

elevenlabs-stt は常に単語単位のタイミングを返します。incredibly-fast-whisper は、wordTimestamps を true にして送ると返します。whisper はフレーズ単位のみです。provider を省略すると whisper が実行されるため、単語単位のタイミングが必要な場合はエンジンを指定してください。

吹き替えできるクリップの長さは、どのくらいですか?

吹き替えの対象区間は最大 30 分です。料金は 1 分単位で、最低 1 分からです。ソースがそれより長い場合は、startTime と endTime で区間を指定して吹き替えてください。

無料で使えるメディアツールはどれですか?

静止画から動画、スライドショー、同期処理でカットとクロップを行う POST /v1/media/process は 0 クレジットです。動画オーバーレイは、画像レイヤーだけの場合、実行ごとに 22 クレジットです。動画レイヤーがある場合は、元の動画の 5 秒(開始した単位)ごとに料金が決まります。無音検出は 11 クレジットです。

最終更新

目次