メディアとアップロード
Nodaro の SDK を使って、TypeScript からファイルをアップロードし、メディアライブラリを一覧表示し、リンクから動画をインポートし、クリップをトリミングし、字幕を焼き込み、画像と動画を合成します。
client.uploads は、ファイルを Nodaro に保存します。client.library は、すでに持っているメディアを一覧表示します。client.gallery は、公開ギャラリーとお気に入りを閲覧します。client.media は、メディアの準備と編集を行います。リンクからの動画のダウンロード、クリップのトリミング、字幕の焼き込み、画像と動画の合成です。client.media のほとんどのメソッドはジョブを開始し、その jobId を返します。これは client.jobs.getStatus() でポーリングします。これらのメソッドは、アップロードと音声とメディアの REST API のエンドポイントを呼び出します。
メソッド
| メソッド | 内容 |
|---|---|
uploads.upload(file) | ファイルを 1 つアップロードし、その公開 URL を取得します |
uploads.uploadLarge(file, options?) | どんなサイズのファイルもアップロードし、長い動画やオーディオのファイルはストレージに直接送ります |
uploads.uploadJson(json) | JSON ドキュメントを保存し、その URL を取得します |
uploads.importUrl(url, options?) | Web アドレスの画像を、自分のストレージにコピーします |
library.list(params?) | 保存されているメディアを一覧表示、検索します |
gallery.browse(params?) | 公開ギャラリーを閲覧します |
gallery.toggleFavorite(jobId) | 生成物をお気に入りにするか、お気に入りから外します |
gallery.favorites() | お気に入りにしたジョブの ID を一覧表示します |
contentRights.declaration() | コンテンツ権利の宣言を読み取ります |
contentRights.confirm(input) | 1 件のリンクについて、インポートの前に宣言を確認します |
contentRights.authorization() | キーやエージェントによるインポートの、継続的な承認を読み取ります |
contentRights.authorize(input) | 本人のセッションから、キーやエージェントによるインポートを承認します |
contentRights.revokeAuthorization() | その承認を取り消します |
media.downloadVideo(input) | リンクの先にある動画を、自分のストレージにダウンロードします |
media.downloadVideoProgress(downloadId, opts?) | ダウンロードの進行状況を追跡します |
media.videoMetadata(input) | SNS の動画の長さとサイズを、ダウンロードせずに読み取ります |
media.saveToStorage(input) | メディアの URL を、自分のストレージにコピーします |
media.process(input) | 保存済みのファイルを、無料でカットまたはクロップします |
media.discard(input) | 作成したばかりで、もう不要になったファイルを破棄します |
media.trimVideo(input) | 動画を範囲でトリミングします |
media.trimAudio(input) | オーディオをトリミングするか、動画から抽出します |
media.splitMedia(input) | 動画またはオーディオファイルを、最小と最大の長さの間のパートに、または動画をショットごとに 1 つのパートにカットします |
media.shotCuts(input) | 動画の各ショットの開始位置と終了位置を見つけます |
media.addCaptions(input) | 動画に字幕を焼き込みます |
media.stillToVideo(input) | 画像とオーディオトラックを、動画にします |
media.slideshow(input) | 画像と任意のオーディオを、スライドショーにします |
media.videoOverlay(input) | タイミング付きの画像または動画のレイヤーを、動画の上に配置します |
media.imageCollage(input) | 2〜30 枚の画像を、1 つのコラージュに結合します |
media.imageOverlay(input) | 画像、テキスト、QR、図形のレイヤーを、画像の上に配置します |
media.splitIntoLayers(input, options?) | 1 枚の画像を、ベース画像と個別のレイヤーに分けます |
media.videoMask(input) | テキストで指定した被写体を追跡し、マスク動画を取得します |
media.maskComposite(input) | マスク動画を通して、ある動画を別の動画の上に配置するか、マスクした部分にモザイクやぼかしをかけます |
media.suggestOverlayPlacement(input) | レイヤーをどこに置くべきか、ビジョンモデルに尋ねます |
client.uploads
uploads.upload(file)
ファイルを 1 つアップロードし(POST /v1/upload、マルチパート)、その公開 URL と保存の詳細を返します。SDK はファイルをフォームデータとして送信し、マルチパートの境界はランタイムに設定させます。
upload(file: File): Promise<UploadResult>プロパティ
型
const result = await client.uploads.upload(file)
const clip = await client.nodes.runAndWait("generate-video", {
prompt: "The camera slowly pushes in",
imageUrl: result.url,
})| フィールド | 型 | 説明 |
|---|---|---|
url | string | 保存されたファイルの公開 URL です。imageUrl、videoUrl、audioUrl として渡してください。 |
assetId | string | null | 保存された項目の ID です。匿名でのアップロードでは null です。 |
thumbnailUrl | string | null | 画像と動画のサムネイルです。ない場合は null です。 |
category | string | image、video、audio のいずれかです。 |
filename | string | 表示用のファイル名です。 |
mimeType | string | サーバーが判定したメディアタイプです。ブラウザーが宣言したものと異なることがあります。たとえば、application/octet-stream として送られた .mp4 ファイルは video/mp4 になります。 |
sizeBytes | number | 保存されたサイズです。 |
r2Key | string | ファイルのストレージキーです。 |
ストレージが満杯の場合は、StorageExceededError をスローします。画像アップロード、動画アップロード、オーディオアップロードの各ノードも、同じストレージを使います。
uploads.uploadLarge(file, options?)
どんなサイズのファイルもアップロードし、サイズに応じてルートを選びます。upload と同じ UploadResult を返します。
uploadLarge(
file: Blob & { name?: string },
options?: {
filename?: string
onProgress?: (sentBytes: number, totalBytes: number) => void
signal?: AbortSignal
concurrency?: number
},
): Promise<UploadResult>- 500 MB 以下(
UPLOAD_MAX_BYTES):ファイルはupload、つまりPOST /v1/uploadで送られ、HEIC の変換やサムネイルなど、サーバーがそこで行う処理がすべて行われます。 - それより大きい動画またはオーディオだけ: バイトはパートに分けてストレージに直接送られ、API サーバーを通りません。大容量の動画やオーディオをアップロードするを参照してください。このファイルの上限は、主に長さです。30 分より長いファイルは、届いた後に
MediaTooLongErrorで拒否されます。保存されたコピーは削除され、ストレージの使用量には何も数えられません。10 GiB を超えるファイルは、何も送る前に、ステータス 422、コードmedia_too_largeのNodaroErrorをスローします。長さに対して大きすぎるファイルは、media_bitrate_implausibleで拒否されます。ファイルは送ったとおりに保存されます。
プロパティ
型
const result = await client.uploads.uploadLarge(file, {
onProgress: (sent, total) => console.log(`${Math.round((sent / total) * 100)}%`),
})
console.log(result.url)大容量のルートでは、失敗や取り消しがあると、サーバー上のアップロードも中止されます。1 つのアカウントで同時に開ける大容量アップロードは 3 件までで、1 時間に始められるのは 20 件までです。どちらかを超えると、SDK はコード too_many_open_uploads または rate_limited の RateLimitedError をスローします。ファイルがストレージに収まらないときは、StorageExceededError をスローします。大容量のルートがないデプロイメントで 500 MB を超えるファイルを送ると、LargeUploadUnavailableError をスローします。status は、すべてのアップロードのバイトを確認するデプロイメントでは 409、古いサーバーでは 404 です。ブラウザーで大容量のルートを使うには、ページのオリジンからのクロスオリジンの PUT をストレージが受け付ける必要があります。Nodaro Cloud は受け付けます。UPLOAD_MAX_BYTES は @nodaro/sdk と @nodaro/sdk/uploads からエクスポートされています。
uploads.uploadJson(json)
25 MB までの JSON ドキュメントを保存し(POST /v1/upload-json)、その公開 URL である { url } を返します。たとえば、画像エディターのデザインの状態に使います。それを jobs.fromUpload に editStateUrl として渡すと、編集をもう一度開けるようになります。
uploadJson(json: Record<string, unknown> | readonly unknown[]): Promise<UploadJsonResult>URL は推測しにくいものの公開されているので、秘密の情報は決して保存しないでください。ライブラリの項目は作成されません。
uploads.importUrl(url, options?)
Web アドレスの画像を自分のストレージにコピーし、それを返します(POST /v1/media/import-url、ボディは { url, confirmationId? })。保存されたコピーは自分のアップロードとして扱われ、ブラウザーのキャンバスがピクセルを読み取れるように配信されます。たとえば、画像をクロップできます。ほかのサイトにある画像では、それができません。
importUrl(url: string, options?: { confirmationId?: string }): Promise<ImportUrlResult>プロパティ
型
プラットフォームは、ファイルが画像としてデコードできる場合にだけ保存します。対応する形式は JPEG、PNG、WebP、GIF です。HEIC、HEIF、AVIF の画像は、JPEG または PNG に変換されます。
try {
const picture = await client.uploads.importUrl("https://example.org/photo.jpg")
console.log(picture.url, picture.width, picture.height)
} catch (err) {
if (err instanceof StorageExceededError && err.reason === "file_too_large") {
// one picture over 20 MB, not a full storage
}
}| フィールド | 型 | 説明 |
|---|---|---|
url | string | 保存された画像の公開 URL です。 |
thumbnailUrl | string | null | サムネイルです。作成できなかった場合は null です。 |
assetId | string | null | 保存された項目の ID です。何も書き込まれなかった場合は null です。 |
mimeType | string | 最終的なメディアタイプです。HEIC、HEIF、AVIF のソースは、JPEG または PNG として保存されます。 |
sizeBytes | number | 保存されたサイズです。 |
filename | string | アドレスのパスの最後の部分、または imported-<id>.<ext> です。 |
width | number | ピクセル単位の幅です。読み取れなかった場合は 0 です。 |
height | number | ピクセル単位の高さです。読み取れなかった場合は 0 です。 |
| ステータス | エラー | 発生する場合 |
|---|---|---|
| 400 | コードが validation_error の NodaroError | アドレスが http でも https でもないか、プライベートまたは予約済みの IP アドレスです。ファイルがデコードできる画像ではないか、SVG や TIFF のように、受け付けられない形式です。 |
| 422 | コードが fetch_failed の NodaroError | アドレスにアクセスできなかったか、エラーが返されました。プライベートなアドレスに解決されるホストも含まれます。 |
| 403 | ImportRefusedError(ForbiddenError の一種) | デプロイ環境の繰り返し侵害者ポリシーにより、あなたのアカウントでリンクのインポートがブロックされているか、アカウントが閉鎖されている(imports_blocked)か、デプロイ環境がそのサイトを許可していない(import_source_disabled)か、デプロイ環境がリンクのインポートをオフにしている(link_imports_disabled:代わりにファイルをアップロードします)か、コンテンツ権利の確認が、必須なのにない、別のリンクやアカウントのもの、古い、期限切れ、またはすでに使用済みです(rights_confirmation_* コード)。 |
| 413 | reason が file_too_large の StorageExceededError | 画像が 20 MB を超えています。 |
| 413 | reason が storage_limit_exceeded の StorageExceededError | 自分のストレージが満杯です。details に usedBytes、quotaBytes、remainingBytes、tier が含まれます。 |
画像アップロードノードは、画像のリンクを貼り付けたときに、同じインポートを使います。不要になったインポート済みの画像を破棄するには、media.discard() を呼び出します。
client.library
library.list(params?)
保存されているメディアを、カーソル付きで一覧表示します(GET /v1/library)。デフォルトでは、自分のライブラリに保存した項目と、自分に共有された項目が、エディターのメディアピッカーと同じ形で返されます。
list(params?: ListLibraryParams): Promise<{ data: LibraryAsset[]; nextCursor: string | null; totalCount?: number }>プロパティ
型
const { data: videos, nextCursor } = await client.library.list({ type: "video", limit: 20 })
for (const asset of videos) console.log(asset.filename, asset.url)const { data, nextCursor } = await client.library.list({ type: "image", q: "poster" })保存されたファイルがなくなったライブラリの行は、一覧にも totalCount にも含まれないため、どの行の url も文字列です。各 LibraryAsset は、id、type、filename、mimeType、sizeBytes、url、thumbnailUrl、metadata、isLibraryItem、uploadSource、source、sourceDetail、jobId、title、createdAt を持ちます。jobId はファイルを作成したジョブで、アップロードの場合は null です。title は、所有者が client.jobs.rename() でそのジョブに付けた名前です。名前がない場合やジョブがない場合は null です。ダウンロード名として残るファイルの filename ではありません。古いサーバーでは、どちらのフィールドも含まれません。totalCount があるのは、最初のページだけです。
client.gallery
完了した生成物の公開ギャラリーと、お気に入りです。お気に入りは、生成物に付けるブックマークです。自分の生成物にも、ほかの人の公開された生成物にも付けられます。自分のジョブでは Job.favorited に入り、client.jobs.list({ favorited: true }) で一覧表示できます。ギャラリーを非表示にしているデプロイメントでは、これらのルートは 404 を返します。
gallery.browse(params?)
公開ギャラリーの 1 ページを、新しい順に読み取ります(GET /v1/gallery)。トークンは必要ありません。
browse(params?: BrowseGalleryParams): Promise<GalleryPage>プロパティ
型
const { data: items, nextCursor } = await client.gallery.browse({ type: "image", limit: 20 })ページは { data: GalleryItem[], nextCursor, totalCount? } で、totalCount があるのは最初のページだけです。各アイテムは { id, type, jobName, outputUrl, thumbnailUrl, createdAt, prompt, model, title?, preview? } で、id はジョブの ID です。title は、client.jobs.rename() で所有者が付けたジョブの名前で、名前が付くまでは null です。プロンプトの横に公開されます。favoritesOnly は、client.me() で得た自分の userId と一緒にだけ使えます。トークンがない場合は UnauthorizedError を、ほかの人の userId を指定した場合や userId がない場合は ForbiddenError をスローします。
公開作品を許可していないデプロイ環境では、自分の表示を除くすべての表示に空のページが返されます。自分の userId と自分のトークンを使えば、引き続き自分の作品を一覧表示できます。
gallery.toggleFavorite(jobId)
ジョブをお気に入りにするか、すでにお気に入りの場合はお気に入りから外します(POST /v1/gallery/favorite)。favorited は、呼び出し後のジョブの状態です。
toggleFavorite(jobId: string): Promise<{ favorited: boolean }>const { favorited } = await client.gallery.toggleFavorite(jobId)お気に入りにできるのは、自分のジョブと公開されたジョブです。ほかの人の非公開のジョブでは、NotFoundError がスローされます。OAuth アプリには assets:write スコープが必要です。
gallery.favorites()
お気に入りにしたジョブの ID を、新しい順に返します(GET /v1/gallery/favorites)。OAuth アプリには assets:read または jobs:read スコープが必要です。
favorites(): Promise<string[]>const ids = await client.gallery.favorites()client.contentRights
client.contentRights は、リンクをインポートする前に人が確認する宣言を読み取り、インポートがその後に持ち運ぶ確認を記録します(/v1/content-rights)。ルールについては、コンテンツ権利を参照してください。
contentRights.declaration()
declaration(): Promise<{ version: number; text: string }>現在の宣言を返します(GET /v1/content-rights/declaration)。text はそのまま、最初はチェックの入っていないチェックボックスとともに表示してください。確認は version を指定します。この呼び出しには認証情報は不要です。
contentRights.confirm(input)
confirm(input: { url: string; declarationVersion: number }): Promise<{
id: string
declarationVersion: number
expiresAt: string
}>サインインしているアカウントが、1 件のリンクについて宣言を確認したことを記録します(POST /v1/content-rights/confirm)。インポートが受け取る http(s) のリンクであれば、どれでも確認できます。動画のページ、ファイル、画像、または吹き替えサービスが読み取るページです。返された id を、confirmationId として media.downloadVideo()、uploads.importUrl()、または voices.dub() や audio.transcribe() など、そのリンクを取得するインポートに渡してください。1 件の確認で開けるのは、同じアカウントによる、現在の宣言のもとでの、1 時間以内のそのリンクのダウンロード 1 回です。409 rights_confirmation_stale は、読み取った後に宣言が変わったことを意味します。もう一度読み取り、もう一度確認を求めてください。
const { version, text } = await client.contentRights.declaration()
// Show `text` with a checkbox. Once it is ticked:
const { id } = await client.contentRights.confirm({ url, declarationVersion: version })
const { downloadId } = await client.media.downloadVideo({ url, maxHeight: 1080, confirmationId: id })確認のないダウンロードを拒否するかどうかは、デプロイ環境の設定です。この設定がオンになると、そのようなダウンロードは 403 rights_confirmation_required で拒否されます。常に確認を送ってください。
contentRights.authorization()
authorization(): Promise<{ id: string; declarationVersion: number; createdAt: string } | null>API キー、接続済みアプリ、AI エージェントによるインポートについての、アカウントの継続的な承認を返します(GET /v1/content-rights/authorization)。承認がない場合(一度も承認していない、取り消した、または古い宣言について承認した場合)は、null を返します。
contentRights.authorize(input)
authorize(input: { declarationVersion: number }): Promise<{
id: string
declarationVersion: number
createdAt: string
}>本人が、自分のキー、アプリ、エージェントによるインポートを、表示された宣言のバージョンについて承認したことを記録します(POST /v1/content-rights/authorization)。本人がサインインしている自分のセッションから呼び出してください。キー、アプリ、エージェントからの呼び出しには 403 forbidden が返ります。409 rights_confirmation_stale は、宣言が変わったことを意味します。もう一度読み取り、もう一度確認を求めてください。
contentRights.revokeAuthorization()
revokeAuthorization(): Promise<{ revoked: boolean }>継続的な承認を取り消します(DELETE /v1/content-rights/authorization)。記録は残ります。取り消すものがなかった場合、revoked は false です。本人のセッションから呼び出してください。
client.media:インポートと準備
media.downloadVideo(input)
リンク(動画のページ、または動画ファイルへの直接リンク)の先にある動画を、自分のストレージにダウンロードします(POST /v1/download-video)。返されるのは、ジョブ ID ではなく downloadId です。続けて downloadVideoProgress() を使ってください。完成したファイルは、ライブラリに入ります。
downloadVideo(input: {
url: string
maxHeight?: number
sectionStartSec?: number
sectionEndSec?: number
exactSection?: boolean
requireAudio?: boolean
confirmationId?: string
}): Promise<{ downloadId: string }>プロパティ
型
const { downloadId } = await client.media.downloadVideo({
url: "https://youtu.be/dQw4w9WgXcQ",
maxHeight: 720,
})media.downloadVideoProgress(downloadId, opts?)
ダウンロードのライブの進行状況を、非同期イテレーターとしてストリーミングします(GET /v1/download-video/progress/:id、サーバー送信イベント)。ダウンロードが完了または失敗するまで、約 500 ミリ秒ごとにイベントを 1 つ生成し、その後終了します。
downloadVideoProgress(downloadId: string, opts?: { signal?: AbortSignal }): AsyncGenerator<DownloadVideoProgress>プロパティ
型
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)
if (event.phase === "failed") console.error(event.error)
}各イベントは { phase, percent, videoUrl?, thumbnailUrl?, error? } です。downloadVideo() が返ったら、すぐにイテレートを始めてください。進行状況のレコードは、ダウンロードが終わってからほどなく期限切れになります。クライアントの timeoutMs は適用されません。大きなダウンロードには数分かかるためです。
media.videoMetadata(input)
SNS の動画の長さ、サイズ、タイトル、ライブ配信かどうかを、ダウンロードせずに読み取ります(POST /v1/video-metadata)。ジョブを介さず、直接答えを返します。一部の区間だけを取得するかどうかを判断するために使います。
videoMetadata(input: { url: string }): Promise<VideoMetadata>プロパティ
型
const meta = await client.media.videoMetadata({ url: "https://youtu.be/dQw4w9WgXcQ" })各フィールドはベストエフォートです。プラットフォームによっては、すべてを報告しないことがあります。
media.saveToStorage(input)
メディアファイルを、URL から自分の Nodaro のストレージにコピーします(POST /v1/save-to-storage)。ファイルを取得するのはサーバーなので、クライアントを経由しません。
saveToStorage(input: { mediaUrl: string; filename?: string; mediaType?: "image" | "video" | "audio" }): Promise<{ jobId: string }>プロパティ
型
const { jobId } = await client.media.saveToStorage({ mediaUrl: "https://example.com/intro.mp4", mediaType: "video" })ストレージに保存ノードも、ワークフローの中で同じことを行います。
media.process(input)
すでに自分のストレージにあるファイルをカットまたはクロップします(POST /v1/media/process)。直接答えを返し、料金はかかりません。有料のステップの前に、素材を準備するために使います。
process(input: {
sourceUrl: string
type: "video" | "audio"
trim?: { startTime: number; endTime: number }
crop?: { x: number; y: number; width: number; height: number }
format?: "mp4" | "webm" | "mp3" | "wav" | "m4a" | "aac"
deleteSource?: boolean
}, options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<{ data: MediaProcessResult }>プロパティ
型
const { data } = await client.media.process({
sourceUrl: stored.url,
type: "video",
trim: { startTime: 12, endTime: 42 },
})
console.log(data.url, data.sizeBytes)結果には、url、thumbnailUrl、assetId、sizeBytes、mimeType、metadata が含まれます。
media.discard(input)
作成したばかりで、もう不要になったファイルを破棄します(POST /v1/media/discard)。たとえば、使う前に差し替えたリンクのダウンロード、新しいものに差し替えたカット、インポートしてからキャンセルした画像です。
discard(input: { url: string }): Promise<{ data: { discarded: boolean } }>プロパティ
型
discard() は、一般的な削除の機能ではありません。ファイルが削除されるのは、次のすべてに当てはまる場合だけです。
- ファイルが自分のものである。
- ファイルが、
downloadVideo()、process()、またはuploads.importUrl()のような URL のインポートで作成された。 - ファイルが作成から 24 時間未満である。
- 自分のどのジョブも、出力としても、実行の
videoUrlのような入力としても、ファイルを使っていない。
その場合、応答は { data: { discarded: true } } です。それ以外の場合は何も変更されず、コードが not_discardable の 409 エラーで呼び出しが失敗します。discarded: false は、そのアドレスに自分のものが何もなかったことを意味します。ファイルはすでに削除されているか、自分のものではありません。
await client.media.discard({ url: oldCut.url })media.trimVideo(input)
動画を範囲でトリミングします(POST /v1/trim-video)。動画のトリミングノードと同じです。範囲は、都合のよい単位で指定できます。
trimVideo(input: {
videoUrl: string
startTime?: number
endTime?: number
trimStartFrames?: number
trimEndFrames?: number
trimStartSeconds?: number
trimEndSeconds?: number
keepFirstSeconds?: number
keepLastSeconds?: number
}): Promise<{ jobId: string }>プロパティ
型
const { jobId } = await client.media.trimVideo({ videoUrl, keepFirstSeconds: 15 })media.trimAudio(input)
オーディオを範囲でトリミングするか、動画から抽出します(POST /v1/trim-audio)。オーディオのトリミングノードと同じです。
trimAudio(input: {
videoUrl?: string
audioUrl?: string
audioFormat?: "mp3" | "wav" | "aac"
startTime?: number
endTime?: number
}): Promise<{ jobId: string }>プロパティ
型
const { jobId } = await client.media.trimAudio({ videoUrl, startTime: 5, endTime: 35 })media.splitMedia(input)
動画、オーディオファイル、またはその両方を、連続したパートにカットします(POST /v1/split-media)。チャンクに分割ノードと同じ処理です。各入力は、それぞれ個別に分割されます。
splitMedia(input:
| {
videoUrl?: string
audioUrl?: string
mode?: "duration"
chunkDuration: number
minPartDuration?: number
audioFormat?: "mp3" | "wav" | "aac"
}
| { videoUrl: string; mode: "shots" }
): Promise<{ jobId: string }>プロパティ
型
1 回の実行は、パートの数にかかわらず 22 クレジットです。完了したジョブの出力には、順番に並んだパートである videoUrls と audioUrls、chunkCount、各パートの正確な長さである partDurationsSec が含まれます。両方の入力を分割した場合は、audioPartDurationsSec にオーディオのパートの長さが入ります。ファイルの長さは最大 3 時間で、パートは最大 200 個です。
const { jobId } = await client.media.splitMedia({ videoUrl, chunkDuration: 60, minPartDuration: 30 })mode: "shots" を指定すると、代わりに動画をショットごとに 1 つのパートにカットします。カット位置はファイルから測定されます。パートの長さは受け取らず、動画だけを受け取ります。別に audioUrl を送ると 400 になります。各パートは、動画自体の音声を保ちます。動画は最長 30 分、ショットは最大 200 個で、料金は同じです。この場合、出力には shotCount と shots が加わり、それぞれ { index, startSec, endSec, durationSec } です。
const { jobId } = await client.media.splitMedia({ videoUrl: "https://example.com/ad.mp4", mode: "shots" })media.shotCuts(input)
ショットカットノードと同じく、動画の各ショットの開始位置と終了位置を見つけます(POST /v1/shot-cuts)。カットはファイルから測定されます。デコードしたすべてのフレームを評価し、ハードカットごとに新しいショットが始まります。ディゾルブとフェードはカットとして扱いません。
shotCuts(input: { videoUrl: string; frames?: boolean }): Promise<{ jobId: string }>プロパティ
型
1 回の実行の料金は、フレームの有無にかかわらず定額です。ジョブをポーリングしてください。完了したジョブの output_data は ShotCutsOutput です:
interface ShotCutsOutput {
json: {
shotCount: number
cutsSec: number[] // where each new shot starts: ascending, never 0; [] for one shot
durationSec: number // the video's length
shots: Array<{
index: number
startSec: number // seconds from the first frame, to the millisecond
endSec: number // the next shot's start, or the video's end
durationSec: number
firstFrameUrl?: string // with frames: the shot's first frame (PNG)
lastFrameUrl?: string // with frames: its last frame
}>
}
firstFrames?: string[] // with frames: each shot's first frame, in shot order
lastFrames?: string[] // with frames: each shot's last frame, in shot order
}const { jobId } = await client.media.shotCuts({ videoUrl: "https://example.com/ad.mp4", frames: true })client.media:字幕
media.addCaptions(input)
動画に字幕を焼き込みます(POST /v1/add-captions)。字幕を追加ノードと同じです。単語は text で指定するか、単語ごとにタイミングの付いた captions を指定するか、Nodaro に音声を文字起こしさせます(これがデフォルトです)。
addCaptions(input: AddCaptionsInput): Promise<{ jobId: string }>プロパティ
型
const { jobId } = await client.media.addCaptions({
videoUrl: "https://example.com/talk.mp4",
style: "word-highlight",
maxWordsPerLine: 2,
})単語がどこから来るか。呼び出しに複数の情報源がある場合、単語ごとにタイミングの付いた captions が優先され、次に subtitle スタイルの text、その次に文字起こしの順です。subtitle では、text がそのまま字幕になります。動画全体で 1 つの静止したブロックとして焼き込まれ、文字起こしの結果に置き換わることはありません。改行を強制するには \n を使います。キネティックスタイルでは、text はフォールバックにすぎません。文字起こしで何も見つからなかった場合や autoTranscribe が false の場合に使われ、その単語は動画全体に均等に配置されます。
スタイルとルック。キネティックスタイルでは、look を指定しない場合、outline としてレンダリングされます。subtitle では clean としてレンダリングされます。明示的なレバーは、ルックの個々のフィールドを上書きします。独自の look を指定したセグメントは、そのプリセットを起点とし、トップレベルのレバーは継承しません。
subtitle でのレバー。スタイル用のレバー(look、fontFamily、fontWeight、strokeColor、strokeWidth、uppercase、positionY、maxWordsPerLine)は、subtitle でも機能します。これらのいずれかを使った subtitle は、キネティックと同じ料金になり、プレーンテキストの subtitle は、より低い料金になります。highlightColor と animate はキネティック専用で、subtitle では 400 で拒否されます。自動で文字起こしされた subtitle も、キネティックと同じ料金になります。
行。word-highlight、karaoke、bouncy は、1 行ずつ表示します。行が終わるのは、文の終わり、0.5 秒以上の間、フレーム幅の約 85% を占めたとき、または maxWordsPerLine の単語数に達したときです。word-pop は 1 単語ずつ表示するため、maxWordsPerLine はここでは影響しません。tiktok-words のページは、文の終わりや間を越えることはありません。どちらも、最後に発話された単語の後、最大 1.5 秒間画面に残ります。単語の startMs と endMs は、その効果が現れるタイミングを示すものであり、表示され続ける長さではありません。
文字起こしエンジン。キネティックスタイルには単語ごとのタイミングが必要なため、transcribeProvider は、ここでのデフォルトである incredibly-fast-whisper、elevenlabs-stt、nemotron-3-5-transcribe のいずれかである必要があります。Nemotron 3.5 Transcribe は 1 回の請求で、レンダリングと動画の開始した分数の料金です。字幕を追加を参照してください。whisper には単語ごとのタイミングがありません。文字起こしが単語の唯一の情報源になる場合に限り、400 validation_error で拒否されます。subtitle では、フレーズ単位のタイミングしか必要ないため、どのエンジンでも使えます。
フレームレート。スタイル付きのレンダリングは、元の動画のフレームレートを保ち、15〜60 の整数に丸めます。フレームレートが可変の動画や、フレーム数の上限を超える長さのクリップは、30 fps でレンダリングされます。
文字起こしして修正し、それから焼き込む
client.audio.transcribe() のジョブが持つ words は、captions が取る形と完全に同じです。単語を修正し、2 回目の文字起こしをせずに字幕を焼き込みます。
import type { TranscribeJobOutput } from "@nodaro/sdk"
const { jobId } = await client.audio.transcribe({
audioUrl: "https://example.com/talk.mp3",
provider: "elevenlabs-stt", // always returns word timings
})
// ...poll until the job completes, then:
const { data: job } = await client.jobs.get(jobId)
const { words = [] } = job.output_data as TranscribeJobOutput
const corrected = words.map((w, i) => (i === 7 ? { ...w, text: "Nodaro" } : w))
await client.media.addCaptions({
videoUrl: "https://example.com/talk.mp4",
captions: corrected,
autoTranscribe: false,
style: "word-highlight",
})client.media:レンダリングと合成
media.stillToVideo(input)
1 枚の静止画と 1 つのオーディオトラックを、MP4 にします(POST /v1/still-to-video)。静止画から動画ノードと同じです。AI モデルを使わずにサーバー上でレンダリングされ、クレジットはかかりません。動画の長さはオーディオと同じで、長さを指定するフィールドはありません。
stillToVideo(input: {
imageUrl: string
audioUrl: string
motion?: "none" | "zoom-in" | "zoom-out" | "pan-left" | "pan-right" | "ken-burns"
intensity?: number
resolution?: "720p" | "1080p" | "4K"
aspectRatio?: "16:9" | "9:16" | "1:1" | "4:3"
fps?: 24 | 30
fit?: "cover" | "contain"
padColor?: string
}): Promise<{ jobId: string }>プロパティ
型
const { jobId } = await client.media.stillToVideo({ imageUrl: coverUrl, audioUrl: podcastUrl, motion: "ken-burns" })media.slideshow(input)
2〜100 枚の画像と任意のオーディオトラックを、MP4 のスライドショーにします(POST /v1/slideshow)。スライドショーノードと同じです。クレジットはかかりません。画像が 1 枚だけの場合は、stillToVideo() を使ってください。
slideshow(input: {
imageUrls: string[]
audioUrl?: string
imageDurations?: Array<number | null>
perImageDuration?: number
transition?: string
transitionDuration?: number
motion?: "none" | "zoom-in" | "zoom-out" | "ken-burns" | "alternate"
intensity?: number
resolution?: "720p" | "1080p" | "4K"
aspectRatio?: "16:9" | "9:16" | "1:1" | "4:3"
fps?: 24 | 30
fit?: "cover" | "contain"
padColor?: string
}): Promise<{ jobId: string }>プロパティ
型
const { jobId } = await client.media.slideshow({ imageUrls: frames, audioUrl: musicUrl, motion: "alternate" })オーディオがある場合、imageDurations で一部の画像の時間を固定しない限り、時間は均等に分割されます。オーディオがない場合、動画の長さは画像の枚数に perImageDuration を掛けた値になり、無音になります。
media.videoOverlay(input)
タイミング付きの画像または動画のレイヤーを 1〜20 個、1 回の処理で動画の上に配置します(POST /v1/video-overlay)。動画オーバーレイノードと同じです。レンダリングはローカルで行われ、AI モデルは使いません。
videoOverlay(input: VideoOverlayRequest): Promise<{ jobId: string }>プロパティ
型
各レイヤーは、imageUrl または videoUrl と、0〜3,600 の秒数で指定する start を取ります。任意の end でレイヤーを終わらせます。end を指定しない場合は、動画が終わるまで表示されます。preset は card、corner-badge、full-frame のいずれかです。ボックスを指定するフィールドの x と y は -100〜100、width と height は 1〜100 で、いずれも出力フレームに対する割合(パーセント)です。height を省略すると、ボックスは画像または動画のアスペクト比に従います。ボックスのフィールドを明示すると、プリセットより優先されます。どちらも指定しないレイヤーは、右下、または指定した corner の位置に付くコーナーバッジになります。opacity は 0〜1、zIndex は 0〜100 です。animate は、画像レイヤーではデフォルトでオン、動画レイヤーではオフです。
動画レイヤーとレイアウト
動画レイヤーは、start で最初のフレームから再生されます。end、またはベース動画の終わりで止まります。レイヤーの動画が先に終わった場合は、最後のフレームが画面に残ります。
動画レイヤーは、sound: { volume }(音量は 0〜1)がない限り無音です。指定した場合、その音声はウィンドウの間ベースのオーディオとミックスされ、ピークを -1 dBFS 以下に抑えるリミッターがかかります。音声のあるレイヤーがない場合、ベースのオーディオはそのまま保たれます。
layout は、ベース動画と最初の動画レイヤーを配置します:
layout | 結果 |
|---|---|
video-bottom、video-top | ベース動画全体を、全幅で下端または上端に寄せます |
stack-whole | ベース動画全体を最初の動画レイヤーのすぐ上に置き、その 2 つを中央に配置します |
stack-filled | ベース動画が上半分を、動画レイヤーが下半分を満たし、どちらもクロップされます |
pip | 最初の動画レイヤーを、フレームの幅の 30% で、その corner から 4% 内側に置きます |
pip 以外のすべてのレイアウトには outputAspect が必要です。2 つのスタックと pip には動画レイヤーが必要です。スタックは baseBox を受け付けません。
const { jobId } = await client.media.videoOverlay({
videoUrl,
layers: [
{ imageUrl: logoUrl, start: 0, preset: "corner-badge", corner: "top-right" },
{ imageUrl: offerCardUrl, start: 8, end: 14, preset: "card" },
],
})動画オーバーレイの料金
画像レイヤーだけの実行は、レイヤーの数や長さにかかわらず 22 クレジット です。動画レイヤーが 1 つでもある実行は、ベース動画の 5 秒(開始した単位)ごとに料金が決まります。そのような実行では、ベース動画は最長 60 秒、動画レイヤーは最大 2 個で、それぞれ最大 200 MB です。ベース動画は、課金の前に測定されます。60 秒を超えるベース動画は video_overlay_too_long で、読み取れないものは invalid_media_duration で失敗します。すべてのレイヤーがベース動画の終わりより後に始まる場合、実行は video_overlay_starts_after_end で失敗します。
完了したジョブの出力には、videoUrl、thumbnailUrl、width、height、durationSec、warnings が含まれます。各警告は { layer?, slot?, code, detail } の形式で、code は clipped、skipped、animated_first_frame、audio_reencoded、layer_no_audio などです。layer_no_audio は、sound を指定した動画レイヤーに音声トラックがなかったため、無音で描画されたことを意味します。
media.imageCollage(input)
2〜30 枚の画像を、1 枚の大きな 2K または 4K のコラージュに結合します(POST /v1/image-collage)。画像コラージュノードと同じです。
imageCollage(input: {
imageUrls: string[]
imageSizes?: Array<0 | 1 | 2 | 3>
numbered?: boolean
imageLabels?: Array<string | null>
badgePosition?: "top-left" | "top-right"
layout?: "smart" | "grid"
resolution?: "2K" | "4K"
aspectRatio?: string
gap?: number
backgroundColor?: string
}): Promise<{ jobId: string }>プロパティ
型
const { jobId } = await client.media.imageCollage({
imageUrls: shotUrls,
numbered: true,
imageLabels: ["Wide", "Medium", "Close-up"],
})番号とラベルは、レイアウト、出力サイズ、料金を変えることはありません。画像に対して長すぎるラベルは、省略記号で短縮されます。
media.imageOverlay(input)
1〜12 個のレイヤーを、ベース画像の上にピクセル単位で正確に配置します(POST /v1/image-overlay)。画像オーバーレイノードと同じです。AI モデルを使わない合成です。11 クレジット かかり、variants に追加するプラットフォームサイズごとに料金が加算されます。
imageOverlay(input: {
imageUrl: string
layers: Array<{
kind?: "image" | "text" | "qr" | "shape"
imageUrl?: string
anchor?: "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right"
x?: number
y?: number
width?: number
height?: number
opacity?: number
rotation?: number
blend?: "over" | "multiply" | "screen"
fit?: "contain" | "cover" | "stretch"
shadow?: { blur: number; offsetX: number; offsetY: number; color: string; opacity: number }
roundedCorners?: number
zIndex?: number
text?: OverlayTextStyle
qr?: OverlayQrStyle
shape?: OverlayShapeStyle
effects?: OverlayImageEffects
}>
canvas?: { width: number; height: number; backgroundColor?: string }
baseFit?: "contain" | "cover"
outputFormat?: "png" | "jpg" | "webp"
variants?: string[]
maskMode?: "none" | "layers" | "around" | "outside"
maskSpread?: number
qrText?: string
}): Promise<{ jobId: string }>プロパティ
型
レイヤー。レイヤーは、次の 4 種類のいずれかです。
- 画像:デフォルトの
kind: "image"とimageUrlです。 - 本物のテキスト:
kind: "text"とtextオブジェクトです。内容、フォント、太さ、色、配置、輪郭、背景ボックス、ベースの高さに対する割合(パーセント)でのサイズを設定します。 - QR コード:
kind: "qr"とqr: { text }です。 - 単色の図形:
kind: "shape"とshape: { shape, color }です。
位置は、ベース画像に対する割合(パーセント)です。そのため、同じ呼び出しが 1K のプレビューにも 4K のレンダリングにも通用します。
anchorは 9 つの位置のいずれかで、デフォルトはcenterです。xとyは、アンカーからのレイヤーの移動量で、ベースの幅と高さに対する割合(パーセント)です。右または下のアンカーでは、負の値を指定すると内側に移動します。widthはベースの幅に対する割合(パーセント)で、デフォルトは 25 です。高さは、heightを設定しない限りレイヤーのアスペクト比に従い、設定した場合はfitがレイヤーをボックスにどう収めるかを決めます。opacityは 0〜1、rotationはレイヤーの中心を軸にした度数、blendはover(デフォルト)、multiply、screenのいずれかです。shadowはやわらかい影を追加し、roundedCornersは角をピクセル単位で丸め、zIndexは重なりの順序を決めます。
const { jobId } = await client.media.imageOverlay({
imageUrl: productShotUrl,
layers: [{ imageUrl: logoUrl, anchor: "bottom-right", x: -4, y: -6, width: 12, opacity: 0.95 }],
variants: ["youtube-thumbnail"],
})完了したジョブの出力には、imageUrl、その width と height、maskUrl、そして variants(それぞれ { id, label, width, height, url })が含まれます。SVG のレイヤーは、対象のサイズで鮮明に描画されます。qr.fromInput: true を指定した QR レイヤーは、そのペイロードを qrText から取得します。qrText を指定しない実行は、それを示す 400 で拒否されます。
media.splitIntoLayers(input, options?)
1 枚の画像を、ベース画像と個別のレイヤーに分けます(POST /v1/split-into-layers)。要素ごとに透明な PNG になり、名前、説明、重なり順、ベース上の位置を示すボックスが付きます。
splitIntoLayers(
input: {
imageUrl: string
maxLayers?: number // 1–99, default 9
size?: "1K" | "1.5K" | "2K" | "auto" // default "1K"
prompt?: string // what to separate, up to 2,000 characters
sessionId?: string // one of your sessions: the job is filed in it
origin?: string // your app's slug, stored on the job
},
options?: {
idempotencyKey?: string // sent as the Idempotency-Key header (8+ characters)
signal?: AbortSignal
timeoutMs?: number
},
): Promise<{ jobId: string; deduped?: true }>maxLayersはレイヤー数の上限です。要素がそれより多い画像では、要素がまとめられてレイヤーが少なくなり、省かれる要素はありません。sizeは各画像のピクセル数の目安です。1Kは約 100 万ピクセルで、autoは画像本来のサイズ(1K〜2K)を保ちます。promptで、分離する要素を指定します。範囲を示す<bbox>x1 y1 x2 y2</bbox>(0〜1000)を含められます。空欄にすると、主な要素が自動で見つかります。- ボディの形式が正しくない場合は、クレジットが確保される前に
400 validation_errorになります。自分のものでないセッションは、何かが作成・課金される前に404になります。 options.idempotencyKeyを付けると、同じリクエストの再試行は、2 つ目のジョブを開始して課金する代わりに、すでに開始したジョブを返します(deduped: true)。
Nodaro Cloud では、実行は返す可能性のある最大の画像数(ベースを含めて maxLayers + 1)の料金を、そのサイズで確保します。請求されるのは、実際に返した画像の分だけです。1K と 1.5K は同じ料金で、2K と auto も同じです。要素が見つからなかった実行はベース画像だけで完了し、画像 1 枚分の料金になります。client.nodes.quote("split-into-layers", input) で、実行前に確保額がわかります。
jobs.get(jobId) をポーリングします。完了したジョブの output_data は SplitIntoLayersOutput です。
interface SplitIntoLayersOutput {
imageUrl: string // the base picture: an opaque PNG
layers: string[] // each layer's transparent PNG, bottom to top
layerData: Array<{ // one per layer, in the same order
name?: string
description?: string
zIndex: number // stacking order: 1 sits on the base, higher is drawn above
width?: number // the layer FILE's own pixels, not the base's
height?: number
box?: { x1: number; y1: number; x2: number; y2: number } // where it sits on the base, in the base's pixels
boxNormalized?: { x1: number; y1: number; x2: number; y2: number } // the same box on a 0–1000 scale of the base
url: string
baseUrl?: string // the base picture this layer was cut from: the same as imageUrl
}>
layerCount: number // layers saved
layersNotSaved?: number // layers that could not be saved; they are not charged
libraryImages?: Array<{ url: string; name?: string }> // each layer as filed in the Library, under its name
}レイヤーはベースのピクセルではなく、要素ごとに、サイズの設定のピクセル数を目安に切り抜かれています。元の位置に戻すには、box に合わせて拡大縮小してください。x1 と y1 が左上、x2 と y2 が右下の角です。
const { jobId } = await client.media.splitIntoLayers({ imageUrl: "https://example.com/poster.png", maxLayers: 5 })完全なリファレンス:レイヤーに分割。
media.videoMask(input)
普通のテキストで指定した被写体を動画の中で追跡し、白黒のマスク動画を返します。被写体のある部分が白になります(POST /v1/video-mask)。動画マスクノードと同じ処理です。
videoMask(input: {
videoUrl: string
prompt: string
threshold?: number
provider?: "sam-3.1" | "sam-3"
holdLastMask?: boolean
minSubjectHeightPct?: number
maxSubjectHeightPct?: number
zone?: { leftPct?: number; rightPct?: number; topPct?: number; bottomPct?: number } | null
perShot?: boolean
redetectEverySec?: number
}): Promise<{ jobId: string }>プロパティ
型
料金はクリップの長さで決まり、SAM 3.1 では 55〜3,108 クレジットです。30 fps より高いフレームレートのクリップは、その分だけ長いものとして数えられます。完了したジョブの出力には、videoUrl(マスク)、width、height、frames、chunks、shots、coverage、kept、recipe が含まれます。chunks は、モデルに送られたリクエストの数です。perShot がカットを見つけない限り、shots は 1 です。recipe はマスキング手法のバージョンで、同じクリップと設定から異なるマスクができるようになるたびに変わります。kept が false になるのは、サイズとゾーンのフィルターによって、どのフレームにも何も残らなかった場合だけです。小数点以下 4 桁に丸められる coverage ではなく、kept を読んでください。
media.maskComposite(input)
マスク動画を通して、前景の動画を背景の動画の上に配置します(POST /v1/mask-composite)。マスク合成ノードと同じ処理です。マスクの白い部分に前景が表示されます。fill: "pixelate" または "blur" にすると、マスクした部分には、モザイクまたはぼかしをかけた背景そのものが表示され、前景は不要です。
maskComposite(input: {
foregroundUrl?: string
backgroundUrl: string
maskUrl: string
invertMask?: boolean
feather?: number
grow?: number
opacity?: number
fill?: "video" | "pixelate" | "blur"
pixelSizePct?: number
blurStrengthPct?: number
backgroundFit?: "cover" | "contain" | "stretch"
audioSource?: "foreground" | "background" | "mix" | "none"
}): Promise<{ jobId: string }>プロパティ
型
1 回の実行は、結果の 5 秒ごと(端数は切り上げ)に 11 クレジットです。
const { jobId: maskJobId } = await client.media.videoMask({ videoUrl: talkUrl, prompt: "the person" })
// Poll the mask job. Its output videoUrl is the mask.
const { jobId } = await client.media.maskComposite({ foregroundUrl: talkUrl, backgroundUrl: beachUrl, maskUrl })media.suggestOverlayPlacement(input)
1 つのレイヤーをベース画像のどこに置くべきかを、ビジョンモデルに尋ねます(POST /v1/image-overlay/suggest-placement)。モデルは、レイヤーを顔、メインの被写体、複雑なテクスチャから避けて配置します。ポーリングするジョブを介さず直接答えを返し、画像の説明の呼び出し 1 回として課金されます。何も合成されません。配置を適用するのはあなたです。
suggestOverlayPlacement(input: {
imageUrl: string
layerAspect?: number
intent?: string
safeArea?: { x: number; y: number; w: number; h: number }
llmModel?: string
}): Promise<{ jobId: string; placement: OverlayPlacement }>プロパティ
型
const { placement } = await client.media.suggestOverlayPlacement({
imageUrl: baseUrl,
intent: "a logo",
layerAspect: 2.5,
})
const { reason, ...box } = placement // anchor, x, y and width, in imageOverlay's units
await client.media.imageOverlay({ imageUrl: baseUrl, layers: [{ imageUrl: logoUrl, ...box }] })placement は、imageOverlay のパーセント単位での anchor、x、y、width に加えて、ユーザーに表示できる 1 文の reason を持ちます。jobId は、課金の記録です。
よくある質問
Nodaro の SDK でファイルをアップロードするには、どうすればよいですか?
File を指定して client.uploads.upload(file) を呼び出します。画像、動画、オーディオの URL を受け取るどのノードにも渡せる、公開 URL が返ります。
コードから動画に字幕を追加するには、どうすればよいですか?
videoUrl と style を指定して client.media.addCaptions を呼び出します。text も captions も指定しない場合、Nodaro が音声を文字起こしします。この呼び出しは jobId を返し、完了したジョブに字幕付きの動画が入ります。
クレジットがかからないメディアのメソッドは、どれですか?
stillToVideo と slideshow は AI モデルを使わずにレンダリングされ、クレジットはかかりません。media.process も無料です。画像レイヤーだけの videoOverlay は 1 回の実行につき 22 クレジット、動画レイヤーがあるものはベース動画の 5 秒(開始した単位)ごとに料金が決まり、imageOverlay は 11 クレジットかかり、追加のプラットフォームサイズごとに料金が加算されます。
コードから生成物をお気に入りにするには、どうすればよいですか?
client.gallery.toggleFavorite(jobId) を呼び出します。ジョブをお気に入りにし、すでにお気に入りの場合はお気に入りから外します。お気に入りは、client.gallery.favorites() または client.jobs.list({ favorited: true }) で一覧表示します。
動画のダウンロードを追跡するには、どうすればよいですか?
client.media.downloadVideo は downloadId を返します。client.media.downloadVideoProgress(downloadId) をイテレートすると、ダウンロードが完了または失敗するまで phase と percent を受け取れます。
関連ページ
ボイスとオーディオ
ジョブと実行
アップロード
音声とメディア
字幕を追加
最終更新