アップロード

アップロードは、自分の画像、動画、オーディオを Nodaro のストレージに入れ、どのノードからも URL で使えるようにします。POST /v1/upload は、1 つのファイルを保存し、その URL を返します。ほかのルートは、URL からファイルをコピーしたり、SNS から動画をインポートしたり、保存済みのファイルを無料でカットしたり、保存しているメディアを一覧表示したりします。

エンドポイント

ファイルをアップロードする

ファイルは、file フィールドに multipart form data として送ります。type を image、video、audio のいずれかに設定して、一緒に送ることもできます。

curl -s -X POST https://app.nodaro.ai/v1/upload \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -F "file=@portrait.png;type=image/png" \
  -F "type=image"

{
  "data": {
    "url": "https://…/portrait.png",
    "assetId": "5d6e7f80-91a2-4b3c-8d4e-5f60718293a4",
    "thumbnailUrl": "https://…/portrait-thumb.webp",
    "category": "image",
    "filename": "portrait.png",
    "mimeType": "image/png",
    "sizeBytes": 1482233,
    "r2Key": "…/portrait.png"
  }
}

// In a browser, file comes from an <input type="file">.
// In Node 20 or newer, build it from bytes:
import { readFile } from 'node:fs/promises'

const file = new File([await readFile('portrait.png')], 'portrait.png', { type: 'image/png' })
const upload = await client.uploads.upload(file)
console.log(upload.url) // pass it as imageUrl, videoUrl or audioUrl

CLI には、アップロードのコマンドはありません。すでにオンラインにあるファイルをターミナルから自分のストレージにコピーするには、nodaro media save <url> を使います。

形式とファイルの種類

メディアの種類ごとに、それぞれのサイズ上限があります。クライアントが宣言する型は、標準的なものである必要はありません。サーバーは、ファイルを確認する前に、実際の型を判定するためです。

• パラメーターは取り除かれます。audio/webm;codecs=opus は audio/webm になります。
• よくある別表記は変換されます。Windows が単純な .aac ファイルに使う audio/vnd.dlna.adts は audio/aac に、image/jpg は image/jpeg に、video/mov は video/quicktime になります。
• 型が役に立たない場合は、ファイル名から判定されます。application/octet-stream や、型がまったく指定されていない場合は、拡張子で決まります。clip.mp4 は video/mp4 として保存されます。

それでも受け付けている形式のどれにも一致しない場合は、受け付けている形式の一覧とともに 400 validation_error が返されます。サーバーが決定した型は mimeType として返り、ファイルはその型で配信されます。

アップロードが拒否される場合

代わりに URL を使う

ほとんどのルートは、imageUrl、videoUrl、audioUrl、referenceImageUrls などの URL でメディアを受け付けるため、すでにオンラインにあるファイルはアップロードする必要がありません。URL は、公開された http または https のアドレスである必要があります。非公開のネットワークアドレスを指す URL や、ほかのスキームを使う URL は拒否されます。

URL が一時的なもの、たとえば期限が切れる署名付きリンクである場合や、そのファイルを使い続けられるようにしたい場合は、ファイルを Nodaro のストレージにコピーしてください。

curl -s -X POST https://app.nodaro.ai/v1/save-to-storage \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mediaUrl": "https://example.com/clip.mp4", "filename": "clip.mp4", "mediaType": "video"}'
# {"jobId":"…"}  poll the job; its output carries the stored file

const { jobId } = await client.media.saveToStorage({
  mediaUrl: 'https://example.com/clip.mp4',
  filename: 'clip.mp4',
  mediaType: 'video',
})

nodaro media save https://example.com/clip.mp4 --filename clip.mp4 --type video --watch

ワークフローの中では、アップロードしたファイルの URL を、実行の入力を通じて、画像アップロード（Upload Image）、動画アップロード（Upload Video）、オーディオアップロード（Upload Audio）のいずれかのノードに渡します。入力ノードのメディアの url フィールドは、実行のたびに、常に上書きできます。新しい入力値でワークフローを実行するを参照してください。

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

POST /v1/download-video は、YouTube、TikTok、Instagram、X、Facebook から、または動画ファイルへの直接リンクから、動画を自分のストレージにインポートします。ジョブ ID ではなく、downloadId を返します。

{ "url": "https://youtu.be/XXXX", "maxHeight": 720, "sectionStartSec": 30, "sectionEndSec": 90 }

• maxHeight は解像度を制限します。指定しない場合は、利用できる最高のものになります。sectionStartSec と sectionEndSec は、動画のその部分だけを取得します。両方とも送るか、どちらも送らないかのいずれかです。
• requireAudio: false を送らない限り、音声トラックのない動画は失敗します。
• 1 つのアカウントで、同時に実行できるインポートは 4 件までです。5 件目は 429 too_many_downloads を返します。
• GET /v1/download-video/progress/:downloadId は、進行状況を、1 秒に約 2 回、サーバー送信イベントとしてストリーミングします。{ phase, percent, videoUrl?, thumbnailUrl?, error? } です。ストリームは、インポートが completed（保存された videoUrl 付き）または failed（error 付き）になると終了します。進行状況は、インポートの終了後、短い時間しか保持されないため、すぐに読み始めてください。
• 完成した動画は、自分のライブラリに保存されます。

インポートする前に動画を確認するには、{ url } を指定して POST /v1/video-metadata を呼び出します。ダウンロードせずに、長さ、サイズ、タイトルを読み取れます。ターミナルからは、nodaro media download <url> --max-height 720 --watch と nodaro media metadata <url> です。ほかのメディアツールは、音声とメディアにあります。

保存済みファイルをトリミング・クロップする

POST /v1/media/process は、保存済みの動画またはオーディオファイルをカットまたはクロップします。無料で、ジョブを使わずに、すぐに応答します。

{
  "sourceUrl": "https://…/interview.mp4",
  "type": "video",
  "trim": { "startTime": 12.5, "endTime": 48 },
  "crop": { "x": 0, "y": 0, "width": 1080, "height": 1080 }
}

応答は { "data": { url, thumbnailUrl, assetId, sizeBytes, mimeType, metadata } } です。format は出力形式を指定します。動画は mp4 または webm、オーディオは mp3、wav、m4a、aac です。deleteSource: true を指定すると、そのファイルが自分のものであり、ほかで使われていない場合、処理のあとに元のファイルが削除されるため、カットしたものが元のファイルを置き換えます。SDK では client.media.process(input) を呼び出します。ワークフローの中でトリミングするには、クレジットのかかる動画のトリミング（Trim Video）ノードを使います。

保存しているメディアを一覧表示する

GET /v1/library は、保存している画像、動画、オーディオを、ストレージの概要とともに返します。type（image、video、audio のいずれか）で絞り込み、limit と cursor でページ単位に分けて取得できます。SDK では client.library.list({ type: 'image' }) を呼び出します。

AI アシスタントからアップロードする

MCP サーバーは、アップロードの 3 つの方法を用意しており、それぞれ画像、オーディオ、動画に対応しています。すべて assets:write スコープが必要です。