A Node.js command-line tool to upload images and media files to various services compatible with Nostr notes, with full support for the Blossom protocol.
npm install
node blossom_uploader.js [options] <files...>
-s, --service <service>: Upload service to use (default: "imgbb")-k, --key <key>: API key for the service (if required)-u, --url <url>: Custom URL for the service (required for blossom)-n, --nsec <nsec>: Nostr private key (nsec) for blossom authentication-d, --debug: Show debug information-o, --output <format>: Output format: json or url (default: "url")-h, --help: Display help-V, --version: Output the version number
Upload a single image using ImgBB (default):
node blossom_uploader.js path/to/image.jpg
Upload using Imgur:
node blossom_uploader.js -s imgur image1.png
Use your own ImgBB API key:
node blossom_uploader.js -s imgbb -k YOUR_API_KEY image.png
Upload to a Blossom server using your nsec private key:
node blossom_uploader.js -s blossom -u https://blossom.band/upload -n nsec1... image.png
Get JSON output:
node blossom_uploader.js -o json image.jpg
Debug mode to see detailed request/response information:
node blossom_uploader.js -d image.jpg
- imgbb (default) - Uses a public demo API key for testing
- freeimage.host - Uses a public demo API key
- imgur - Uses anonymous uploads via client ID
The tool fully supports the BUDS02 specification for Blossom servers, including:
- blossom - Generic service type for any Blossom-compatible server
- Requires a URL (via -u) and optionally an nsec key
- Automatically generates a temporary key if no nsec provided
- Implements NIP-98 HTTP authentication with proper event signing
- Requires URL in format:
https://example.com/upload
Example Blossom servers:
- blossom.band
- blossom.nostr.wine (paid)
- nostr.build (requires API key)
The tool supports the following file types and automatically sets the correct MIME type:
| Extension | MIME Type | Description |
|---|---|---|
| .jpg/.jpeg | image/jpeg | JPEG images |
| .png | image/png | PNG images |
| .gif | image/gif | GIF images |
| .webp | image/webp | WebP images |
| .svg | image/svg+xml | SVG images |
| application/pdf | PDF documents | |
| .mp4 | video/mp4 | MP4 videos |
| .mov | video/quicktime | QuickTime videos |
| .mp3 | audio/mpeg | MP3 audio files |
Other file types are uploaded with the generic application/octet-stream content type.
Many Nostr-specific image hosting services have different requirements:
- Standard Services (imgbb, imgur) - These provide simple API endpoints and are widely compatible
- Blossom Protocol Services - These implement the BUDS02 specification and require Nostr authentication
For Blossom servers, the tool:
- Generates a SHA-256 hash of the file
- Creates and signs a proper Nostr event (kind 24242)
- Includes required tags: ['t', 'upload'], ['x', hash], ['expiration', timestamp]
- Sets the correct Content-Type header based on file extension
- Securely encodes the authorization header in the required format