Uploads

---

The Uploads API provides methods for uploading audio and image files to Audius storage nodes. These methods return CIDs (Content Identifiers) that you then pass to write methods like createTrack or updateTrack.

tip

File uploads are a separate step from track/playlist creation. You first upload your files using the Uploads API to get CIDs, then pass those CIDs as metadata when creating or updating content.

---

createAudioUpload

createAudioUpload(params)

Upload an audio file to a storage node. Returns the resulting CIDs and audio analysis metadata (duration, BPM, musical key).

Params

Create an object with the following fields and pass it as the first argument.

Name	Type	Description	Required?
file	File	The audio file to upload	Required
onProgress	(loaded: number, total: number) => void	A callback for tracking upload progress	Optional
previewStartSeconds	number	Start time in seconds for generating a preview clip	Optional
placementHosts	string[]	A list of storage node hosts to prefer for placement	Optional

Example

import fs from 'fs'

const trackBuffer = fs.readFileSync('path/to/track.mp3')

const upload = audiusSdk.uploads.createAudioUpload({
  file: {
    buffer: Buffer.from(trackBuffer),
    name: 'track.mp3',
    type: 'audio/mpeg',
  },
  onProgress: (loaded, total) => {
    console.log(`Upload progress: ${Math.round((loaded / total) * 100)}%`)
  },
  previewStartSeconds: 30,
})

const result = await upload.start()
console.log(result)

Response

The method returns an object with:

• abort — a function you can call to cancel the upload.
• start() — a function that begins the upload and returns a Promise that resolves with the upload result once complete.

The resolved value of start() contains:

{
  trackCid: string         // CID of the transcoded 320kbps audio
  previewCid?: string      // CID of the preview clip (if previewStartSeconds was provided)
  origFileCid: string      // CID of the original uploaded file
  origFilename: string     // Original filename
  duration: number         // Duration in seconds
  bpm?: number             // Detected BPM (beats per minute)
  musicalKey?: string      // Detected musical key
}

---

createImageUpload

createImageUpload(params)

Upload an image file (e.g. cover art or profile picture) to a storage node. Returns the resulting CID.

Params

Create an object with the following fields and pass it as the first argument.

Name	Type	Description	Required?
file	File	The image file to upload	Required
onProgress	(loaded: number, total: number) => void	A callback for tracking upload progress	Optional
isBackdrop	boolean	Set to true for wide/banner images (e.g. profile banners). Default: false	Optional
placementHosts	string[]	A list of storage node hosts to prefer for placement	Optional

Example

import fs from 'fs'

const coverArtBuffer = fs.readFileSync('path/to/cover-art.png')

const upload = audiusSdk.uploads.createImageUpload({
  file: {
    buffer: Buffer.from(coverArtBuffer),
    name: 'cover-art.png',
    type: 'image/png',
  },
})

const coverArtCid = await upload.start()
console.log(coverArtCid) // CID string

Response

The method returns an object with:

• abort — a function you can call to cancel the upload.
• start() — a function that begins the upload and returns a Promise resolving with the CID of the uploaded image (string).

---

Full Example: Upload and Create a Track

This example demonstrates the full workflow of uploading files via the Uploads API and then creating a track with the returned CIDs.

import fs from 'fs'

// Step 1: Upload the audio file
const trackBuffer = fs.readFileSync('path/to/track.mp3')
const audioUpload = audiusSdk.uploads.createAudioUpload({
  file: {
    buffer: Buffer.from(trackBuffer),
    name: 'track.mp3',
    type: 'audio/mpeg',
  },
  previewStartSeconds: 30,
})
const audioResult = await audioUpload.start()

// Step 2: Upload cover art
const coverArtBuffer = fs.readFileSync('path/to/cover-art.png')
const imageUpload = audiusSdk.uploads.createImageUpload({
  file: {
    buffer: Buffer.from(coverArtBuffer),
    name: 'cover-art.png',
    type: 'image/png',
  },
})
const coverArtCid = await imageUpload.start()

// Step 3: Create the track using the CIDs from the uploads.
// The audio upload result fields (trackCid, previewCid, origFileCid, etc.)
// match the metadata field names, so you can spread them directly.
const { data } = await audiusSdk.tracks.createTrack({
  userId: '7eP5n',
  metadata: {
    title: 'Monstera',
    description: 'Dedicated to my favorite plant',
    genre: 'Metal',
    mood: 'Aggressive',
    ...audioResult,
    coverArtCid: coverArtCid,
  },
})