![\"Bytescale](\"https://raw.githubusercontent.com/bytescale/bytescale-javascript-sdk/main/.github/assets/bytescale-javascript-sdk.svg\")
\n \n\n \n\n \n ![](\"https://img.shields.io/badge/%40bytescale%2Fsdk-npm-4ba0f6\"){kind=icon}
![](\"https://img.shields.io/badge/build-passing-4ba0f6\"){kind=icon}
![](\"https://img.shields.io/badge/gzipped-9%20kb-4ba0f6\"){kind=icon}
![](\"https://img.shields.io/npm/dt/upload-js?color=%234ba0f6\")
\n\n \n ![](\"https://img.shields.io/badge/TypeScript-included-4ba0f6\"){kind=icon}
![](\"https://img.shields.io/npms-io/maintenance-score/upload-js?color=4ba0f6\")
![\"Twitter](\"https://img.shields.io/twitter/url?style=social&url=https%3A%2F%2Fgithub.com%2Fbytescale%2Fbytescale-javascript-sdk\")
\n Use the Bytescale JavaScript SDK to upload, transform, and serve files at scale.\n
\n
\n Full SDK Documentation • Upload Widget • Media Processing APIs • Storage • CDN\n
![\"Bytescale](\"https://raw.githubusercontent.com/bytescale/bytescale-javascript-sdk/main/.github/assets/bytescale-javascript-sdk-2.png\")
\n\n## Installation\n\n#### For Node.js:\n\n```bash\nnpm install @bytescale/sdk node-fetch\n```\n\n#### For Browsers:\n\n```bash\nnpm install @bytescale/sdk\n```\n\nIf you'd prefer to use a script tag:\n\n```html\n\n```\n\n## Uploading Files — [Try on CodePen](https://codepen.io/bytescale/pen/abVapaJ?editors=1010)\n\nThis library is isomorphic, meaning you can upload files from Node.js, or the browser, or both.\n\n#### From Node.js:\n\n```javascript\nimport * as Bytescale from \"@bytescale/sdk\";\nimport nodeFetch from \"node-fetch\";\n\nconst uploadManager = new Bytescale.UploadManager({\n fetchApi: nodeFetch, // import nodeFetch from \"node-fetch\"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.\n apiKey: \"free\" // Get API keys from: www.bytescale.com\n});\n\nuploadManager\n .upload({\n // Supported types:\n // - String\n // - Blob\n // - ArrayBuffer\n // - Buffer\n // - ReadableStream (Node.js), e.g. fs.createReadStream(\"file.txt\")\n data: \"Hello World\",\n\n // ---------\n // Optional:\n // ---------\n\n // Required if 'data' is a stream.\n // size: 5098, // e.g. fs.statSync(\"file.txt\").size\n\n // Required if 'data' is a stream, buffer, or string.\n mime: \"text/plain\",\n\n // Required if 'data' is a stream, buffer, or string.\n originalFileName: \"my_file.txt\"\n\n // Reports progress: bytesTotal, bytesSent, progress.\n // onProgress: ({ progress }) => console.log(progress),\n\n // Controls multipart upload concurrency. Ignored if 'data' is a stream.\n // maxConcurrentUploadParts: 4,\n\n // Up to 2KB of arbitrary JSON.\n // metadata: {\n // productId: 60891\n // },\n\n // Up to 25 tags per file.\n // tags: [\n // \"example_tag\"\n // ],\n\n // About file paths:\n // - Your API key's \"file upload path\" is used by default, and can be changed by editing the API key's settings.\n // - You can override the API key's file upload path by specifying a path below.\n // - You may use path variables (e.g. \"{UTC_DAY}\"): http://localhost:3201/docs/path-variables\n // path: {\n // folderPath: \"/uploads/{UTC_YEAR}/{UTC_MONTH}/{UTC_DAY}\",\n // fileName: \"{UTC_TIME_TOKEN_INVERSE}{UNIQUE_DIGITS_2}{ORIGINAL_FILE_EXT}\"\n // },\n\n // Set to 'isCancelled = true' after invoking 'upload' to cancel the upload.\n // cancellationToken: {\n // isCancelled: false\n // }\n })\n .then(\n ({ fileUrl, filePath }) => {\n // --------------------------------------------\n // File successfully uploaded!\n // --------------------------------------------\n // The 'filePath' uniquely identifies the file,\n // and is what you should save to your DB.\n // --------------------------------------------\n console.log(`File uploaded to: ${fileUrl}`);\n },\n error => console.error(`Error: ${error.message}`, error)\n );\n```\n\n#### From the Browser:\n\n```html\n\n \n \n \n \n \n \n \n\n```\n\n## Downloading Files\n\n```javascript\nimport * as Bytescale from \"@bytescale/sdk\";\nimport nodeFetch from \"node-fetch\"; // Only required for Node.js\n\nconst fileApi = new Bytescale.FileApi({\n fetchApi: nodeFetch, // import nodeFetch from \"node-fetch\"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.\n apiKey: \"YOUR_API_KEY\" // e.g. \"secret_xxxxx\"\n});\n\nfileApi\n .downloadFile({\n accountId: \"YOUR_ACCOUNT_ID\", // e.g. \"W142hJk\"\n filePath: \"/uploads/2022/12/25/hello_world.txt\"\n })\n .then(response => response.text()) // .text() | .json() | .blob() | .stream()\n .then(\n fileContents => console.log(fileContents),\n error => console.error(error)\n );\n```\n\nUse the [`UrlBuilder`](#urlbuilder) to get a URL instead (if you need a file URL instead of a binary stream).\n\n## Processing Files\n\n```javascript\nimport * as Bytescale from \"@bytescale/sdk\";\nimport fetch from \"node-fetch\"; // Only required for Node.js\nimport fs from \"fs\";\n\nconst fileApi = new Bytescale.FileApi({\n fetchApi: nodeFetch, // import nodeFetch from \"node-fetch\"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.\n apiKey: \"YOUR_API_KEY\" // e.g. \"secret_xxxxx\"\n});\n\nfileApi\n .processFile({\n accountId: \"YOUR_ACCOUNT_ID\", // e.g. \"W142hJk\"\n filePath: \"/uploads/2022/12/25/image.jpg\",\n\n // See: https://www.bytescale.com/docs/image-processing-api\n transformation: \"image\",\n transformationParams: {\n w: 800,\n h: 600\n }\n })\n .then(response => response.stream()) // .text() | .json() | .blob() | .stream()\n .then(\n imageByteStream =>\n new Promise((resolve, reject) => {\n const writer = fs.createWriteStream(\"image-thumbnail.jpg\");\n writer.on(\"close\", resolve);\n writer.on(\"error\", reject);\n imageByteStream.pipe(writer);\n })\n )\n .then(\n () => console.log(\"Thumbnail saved to 'image-thumbnail.jpg'\"),\n error => console.error(error)\n );\n```\n\nUse the [`UrlBuilder`](#urlbuilder) to get a URL instead (if you need a file URL instead of a binary stream).\n\n## Get File Details\n\n```javascript\nimport * as Bytescale from \"@bytescale/sdk\";\nimport fetch from \"node-fetch\"; // Only required for Node.js\n\nconst fileApi = new Bytescale.FileApi({\n fetchApi: nodeFetch, // import nodeFetch from \"node-fetch\"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.\n apiKey: \"YOUR_API_KEY\" // e.g. \"secret_xxxxx\"\n});\n\nfileApi\n .getFileDetails({\n accountId: \"YOUR_ACCOUNT_ID\", // e.g. \"W142hJk\"\n filePath: \"/uploads/2022/12/25/image.jpg\"\n })\n .then(\n fileDetails => console.log(fileDetails),\n error => console.error(error)\n );\n```\n\n## Listing Folders\n\n```javascript\nimport * as Bytescale from \"@bytescale/sdk\";\nimport fetch from \"node-fetch\"; // Only required for Node.js\n\nconst folderApi = new Bytescale.FolderApi({\n fetchApi: nodeFetch, // import nodeFetch from \"node-fetch\"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.\n apiKey: \"YOUR_API_KEY\" // e.g. \"secret_xxxxx\"\n});\n\nfolderApi\n .listFolder({\n accountId: \"YOUR_ACCOUNT_ID\", // e.g. \"W142hJk\"\n folderPath: \"/\",\n recursive: false\n })\n .then(\n // Note: operation is paginated, see 'result.cursor' and 'params.cursor'.\n result => console.log(`Items in folder: ${result.items.length}`),\n error => console.error(error)\n );\n```\n\n## 📙 Bytescale SDK API Reference\n\nFor a complete list of operations, please see:\n\n**[Bytescale JavaScript SDK Docs »](https://www.bytescale.com/docs/sdks/javascript)**\n\n## 🌐 Media Processing APIs (Image/Video/Audio)\n\nBytescale provides several real-time [Media Processing APIs](https://www.bytescale.com/docs/media-processing-apis):\n\n- **[Image Processing APIs](https://www.bytescale.com/docs/image-processing-api)** ([resize](https://www.bytescale.com/docs/image-processing-api#image-resizing-api), [crop](https://www.bytescale.com/docs/image-processing-api#image-cropping-api), [convert](https://www.bytescale.com/docs/image-processing-api#f), [compress](https://www.bytescale.com/docs/image-processing-api#image-compression-api) & [watermark](https://www.bytescale.com/docs/image-processing-api#Text-layering-api))\n- **[Video Processing APIs](https://www.bytescale.com/docs/video-processing-api)** ([transcode](https://www.bytescale.com/docs/video-processing-api#video-transcoding-api), [optimize](https://www.bytescale.com/docs/video-processing-api#video-compression-api), [resize](https://www.bytescale.com/docs/video-processing-api#video-resizing-api) & [extract metadata](https://www.bytescale.com/docs/video-processing-api#video-metadata-api))\n- **[Audio Processing APIs](https://www.bytescale.com/docs/audio-processing-api)** ([transcode](https://www.bytescale.com/docs/audio-processing-api#audio-transcoding-api), [optimize](https://www.bytescale.com/docs/audio-processing-api#audio-compression-api), [trim](https://www.bytescale.com/docs/audio-processing-api#audio-trimming-api) & [extract metadata](https://www.bytescale.com/docs/audio-processing-api#audio-metadata-api))\n\n### Image Processing API (Original Image)\n\nHere's an example using [a photo of Chicago](https://upcdn.io/W142hJk/raw/example/city-landscape.jpg):\n\n![](\"https://upcdn.io/W142hJk/raw/example/city-landscape.jpg\")
\n\n```\nhttps://upcdn.io/W142hJk/raw/example/city-landscape.jpg\n```\n\n### Image Processing API (Transformed Image)\n\nUsing the [Image Processing API](https://www.bytescale.com/docs/image-processing-api), you can produce [this image](https://upcdn.io/W142hJk/image/example/city-landscape.jpg?w=900&h=600&fit=crop&f=webp&q=80&blur=4&text=WATERMARK&layer-opacity=80&blend=overlay&layer-rotate=315&font-size=100&padding=10&font-weight=900&color=ffffff&repeat=true&text=Chicago&gravity=bottom&padding-x=50&padding-bottom=20&font=/example/fonts/Lobster.ttf&color=ffe400):\n\n![](\"https://upcdn.io/W142hJk/image/example/city-landscape.jpg?w=900&h=600&fit=crop&f=webp&q=80&blur=4&text=WATERMARK&layer-opacity=80&blend=overlay&layer-rotate=315&font-size=100&padding=10&font-weight=900&color=ffffff&repeat=true&text=Chicago&gravity=bottom&padding-x=50&padding-bottom=20&font=/example/fonts/Lobster.ttf&color=ffe400\")
\n\n```\nhttps://upcdn.io/W142hJk/image/example/city-landscape.jpg\n ?w=900\n &h=600\n &fit=crop\n &f=webp\n &q=80\n &blur=4\n &text=WATERMARK\n &layer-opacity=80\n &blend=overlay\n &layer-rotate=315\n &font-size=100\n &padding=10\n &font-weight=900\n &color=ffffff\n &repeat=true\n &text=Chicago\n &gravity=bottom\n &padding-x=50\n &padding-bottom=20\n &font=/example/fonts/Lobster.ttf\n &color=ffe400\n```\n\n## Authentication\n\nThe Bytescale JavaScript SDK supports two types of authentication:\n\n### API Keys\n\nThe Bytescale JavaScript SDK automatically adds the `apiKey` from the constructor to the `authorization` header for all requests made via the SDK.\n\nWith API key auth, the requester has access to the resources available to the API key:\n\n- Secret API keys (`secret_***`) can perform all API operations.\n\n- Public API keys (`public_***`) can perform file uploads and file downloads only. File overwrites, file deletes, and all other destructive operations cannot be performed using public API keys.\n\nEach Public API Key and Secret API Key can have its read/write access limited to a subset of files/folders.\n\n### JWTs\n\nJWTs are optional.\n\nWith JWTs, the user can download private files directly via the URL, as authentication is performed implicitly via a session cookie _or_ via an `authorization` header if service workers are enabled (see the `serviceWorkerScript` param on the `AuthManager.beginAuthSession` method). This allows the browser to display private files in `