Uploads

Uploads put your own images, video and audio into Nodaro's storage, so that any node can use them by URL. POST /v1/upload stores one file and returns its URL. Other routes copy a file from a URL, import a video from a social network, cut a stored file for free, or list the media you have stored.

Endpoints

Upload a file

Send the file as multipart form data in the file field. You can also send type, set to image, video or 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

The CLI has no upload command. To copy a file that is already online into your storage from the terminal, use nodaro media save <url>.

Formats and file types

Each media type has its own size limit. The type your client declares does not have to be the standard one, because the server works out the real type before it checks the file:

• Parameters are removed. audio/webm;codecs=opus becomes audio/webm.
• Common alternative spellings are mapped. audio/vnd.dlna.adts, which Windows uses for a plain .aac file, becomes audio/aac, image/jpg becomes image/jpeg, and video/mov becomes video/quicktime.
• An unhelpful type is read from the file name. With application/octet-stream, or no type at all, the extension decides: clip.mp4 is stored as video/mp4.

A type that still matches no accepted format answers 400 validation_error, with the list of accepted formats. The type the server settled on comes back as mimeType, and the file is served with it.

HEIC, HEIF and AVIF images are converted before they are stored. Few browsers show these formats, and the image models do not accept them. Every image upload lane stores such a file as a JPEG, or as a PNG when the picture has transparency, and mimeType reports the stored type. The lanes are POST /v1/upload, POST /v1/upload/image, the upload behind the MCP tools prepare_image_upload and request_image_upload, and the server-side import of an image URL. A lane that gave out the file's URL before the upload keeps that URL, and only its content type changes. This covers 10-bit AVIF files and iPhone HEIC photos. These two are read by a decoder that does not keep transparency, so a transparent area in them comes out opaque. An 8-bit AVIF keeps its transparency. A file that cannot be decoded at all is refused with 400.

MP4 and MOV videos are stored with their index at the front. A recording from OBS or a phone often keeps this index at the end of the file, so the first seek into a large file is slow. Every video upload lane rewrites such a file once, before it is stored, by copying its streams into a new container. Nothing is re-encoded: the picture and the sound stay identical. A file that already has its index at the front, or that the rewrite cannot verify, is stored exactly as sent. Because a rewritten file is wrapped again, the stored size can differ slightly from the bytes you sent. sizeBytes is always the stored file's length, so do not compare it to your local file size or checksum.

When an upload is refused

Use a URL instead

Most routes take media by URL, such as imageUrl, videoUrl, audioUrl and referenceImageUrls, so a file that is already online does not need an upload. The URL must be a public http or https address: a URL that points at a private network address, or uses another scheme, is refused.

Copy the file into Nodaro's storage when the URL is temporary, such as a signed link that expires, or when you want the file to stay available:

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

In a workflow, pass an uploaded file's URL to an Upload Image, Upload Video or Upload Audio node through the run's inputs. The media url fields of input nodes can always be overridden by a run. See Run a workflow with new input values.

Import a video from a social network

POST /v1/download-video imports the video behind a link to a video's page, or from a direct link to a video file, into your storage. Send the content rights confirmation for the link as confirmationId (see Content rights). It answers with a downloadId, not a job id:

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

• maxHeight limits the resolution; leave it out for the best available. sectionStartSec and sectionEndSec fetch only that part of the video, with about 3 seconds more on each side, because the cut lands on keyframes. Send both or neither, and trim the result when you need an exact cut. With exactSection: true, the part is cut at exactly that range instead, with no margin.
• A video without a sound track fails, unless you send requireAudio: false.
• Each account can run 4 imports at once. A fifth answers 429 too_many_downloads.
• GET /v1/download-video/progress/:downloadId streams the progress as server-sent events, about twice a second: { phase, percent, videoUrl?, thumbnailUrl?, error? }. The stream ends when the import is completed, with the stored videoUrl, or failed, with an error. The progress is kept only for a short time after the import ends, so start reading it right away.
• The finished video is saved in your library.

To check a video before you import it, POST /v1/video-metadata with { url } reads its duration, size and title without downloading it. From the terminal: nodaro media download <url> --max-height 720 --watch and nodaro media metadata <url>. The other media tools are in Voice and media.

Trim or crop a stored file

POST /v1/media/process cuts or crops a stored video or audio file. It is free and answers at once, without a job:

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

The answer is { "data": { url, thumbnailUrl, assetId, sizeBytes, mimeType, metadata } }. format sets the output format: mp4 or webm for video, mp3, wav, m4a or aac for audio. With deleteSource: true, the source file is removed afterwards when it is yours and nothing else uses it, so the cut replaces the original. In the SDK, call client.media.process(input). For trimming inside a workflow, use the Trim Video node, which costs credits.

Import a picture from a web address

POST /v1/media/import-url with the body { "url": "https://…" } copies a picture from a web address into your storage. The address must be http or https and not private, and the picture can be up to 20 MB. The platform keeps the file only if it decodes as an image: JPEG, PNG, WebP or GIF. A HEIC, HEIF or AVIF picture is converted to JPEG or PNG. The stored copy is an upload of yours, served so that a browser canvas can read its pixels, for example to crop it.

The answer is { "data": { url, thumbnailUrl, assetId, mimeType, sizeBytes, filename, width, height } }. A refused import answers 400 validation_error for an address or a format that is not accepted, 422 fetch_failed when the address cannot be reached, and 413 when the picture is over 20 MB (file_too_large) or your storage is full (storage_limit_exceeded). In the SDK, call client.uploads.importUrl(url). The Upload Image node uses this import when you paste an image link.

Throw away a file you no longer need

POST /v1/media/discard with the body { "url": "https://…" } throws away a file you just made and no longer need. Examples are a link download you replaced before using it, a cut replaced by a newer one, and a picture you imported and then cancelled. It is not a general delete. The file is removed only when it is your own and was made by /v1/download-video, /v1/media/process or a URL import. It must also be less than 24 hours old, and no job of yours may use it, as an output or as an input such as a run's videoUrl.

In the SDK, call client.media.discard({ url }).

Your media library

GET /v1/library lists your media, newest first. By default it lists the files you saved to your library plus the shared library. With owned=true, it lists every file you own instead: uploads and generations, saved or not.

The answer is { data, nextCursor, totalCount }. Each item carries id, type, filename, mimeType, sizeBytes, url, thumbnailUrl, metadata, isLibraryItem, uploadSource, source, sourceDetail, jobId and createdAt. jobId is the job that made the file, or null for an upload. nextCursor is null on the last page, and totalCount, the number of matching files, comes with the first page only. A library row whose stored file is gone is not listed and not counted, so every item has a url.

curl -s "https://app.nodaro.ai/v1/library?owned=true&type=image&q=poster" \
  -H "Authorization: Bearer $NODARO_API_KEY"

In the SDK, call client.library.list({ type: 'image', q: 'poster' }). The MCP tool browse_uploads reads the owned=true view, with the same filename search as its search argument.

POST /v1/library/save-generated with { url, type } saves a file to your library. A file on Nodaro storage is accepted only when it is yours: one of your generations, a file you uploaded, or a file in your upload folder. Any other file on Nodaro storage answers 403 forbidden, whether or not it exists. A link to any other site is saved as given.

Link a user to one file

To send a signed-in user to one file in the app's file library, My Files, link to /library with one of two query parameters:

• The page searches, then shows the file. It shows "Looking for the file…", then scrolls to the file, marks it and opens its preview.
• It looks through about the user's newest 1,000 files. A link to an older file opens My Files without it.
• When the file cannot be shown, a short message says why, and the page opens as usual: the id is unknown or not the user's, the job is still running, or the job failed or made no file. When the lookup itself fails, the message asks the user to try the link again.
• The parameter is removed from the address once read, so a refresh or Back does not open the file again.
• A user who is not signed in signs in first and then lands on the file. A self-hosted install answers the same paths on its own address.

Upload from an AI assistant

The MCP server offers three ways to upload, each for images, audio and video. They all need the assets:write scope.