Use the Bytescale JavaScript SDK to upload, transform, and serve files at scale.
Full SDK Documentation • Upload Widget • Media Processing APIs • Storage • CDN
Installation
For Node.js:
npm install @bytescale/sdk node-fetch
For Browsers:
npm install @bytescale/sdk
If you'd prefer to use a script tag:
<script src="https://js.bytescale.com/sdk/v3"></script>
This library is isomorphic, meaning you can upload files from Node.js, or the browser, or both.
From Node.js:
import * as Bytescale from "@bytescale/sdk";
import nodeFetch from "node-fetch";
const uploadManager = new Bytescale.UploadManager({
fetchApi: nodeFetch,
apiKey: "free"
});
uploadManager
.upload({
data: "Hello World",
mime: "text/plain",
originalFileName: "my_file.txt"
})
.then(
({ fileUrl, filePath }) => {
console.log(`File uploaded to: ${fileUrl}`);
},
error => console.error(`Error: ${error.message}`, error)
);
From the Browser:
<html>
<head>
<script src="https://js.bytescale.com/sdk/v3"></script>
<script>
const uploadManager = new Bytescale.UploadManager({
apiKey: "free"
});
const onFileSelected = async event => {
const file = event.target.files[0];
try {
const { fileUrl, filePath } = await uploadManager.upload({
data: file
});
alert(`File uploaded:\n${fileUrl}`);
} catch (e) {
alert(`Error:\n${e.message}`);
}
};
</script>
</head>
<body>
<input type="file" onchange="onFileSelected(event)" />
</body>
</html>
Downloading Files
import * as Bytescale from "@bytescale/sdk";
import nodeFetch from "node-fetch";
const fileApi = new Bytescale.FileApi({
fetchApi: nodeFetch,
apiKey: "YOUR_API_KEY"
});
fileApi
.downloadFile({
accountId: "YOUR_ACCOUNT_ID",
filePath: "/uploads/2022/12/25/hello_world.txt"
})
.then(response => response.text())
.then(
fileContents => console.log(fileContents),
error => console.error(error)
);
Use the UrlBuilder
to get a URL instead (if you need a file URL instead of a binary stream).
Processing Files
import * as Bytescale from "@bytescale/sdk";
import fetch from "node-fetch";
import fs from "fs";
const fileApi = new Bytescale.FileApi({
fetchApi: nodeFetch,
apiKey: "YOUR_API_KEY"
});
fileApi
.processFile({
accountId: "YOUR_ACCOUNT_ID",
filePath: "/uploads/2022/12/25/image.jpg",
transformation: "image",
transformationParams: {
w: 800,
h: 600
}
})
.then(response => response.stream())
.then(
imageByteStream =>
new Promise((resolve, reject) => {
const writer = fs.createWriteStream("image-thumbnail.jpg");
writer.on("close", resolve);
writer.on("error", reject);
imageByteStream.pipe(writer);
})
)
.then(
() => console.log("Thumbnail saved to 'image-thumbnail.jpg'"),
error => console.error(error)
);
Use the UrlBuilder
to get a URL instead (if you need a file URL instead of a binary stream).
Get File Details
import * as Bytescale from "@bytescale/sdk";
import fetch from "node-fetch";
const fileApi = new Bytescale.FileApi({
fetchApi: nodeFetch,
apiKey: "YOUR_API_KEY"
});
fileApi
.getFileDetails({
accountId: "YOUR_ACCOUNT_ID",
filePath: "/uploads/2022/12/25/image.jpg"
})
.then(
fileDetails => console.log(fileDetails),
error => console.error(error)
);
Listing Folders
import * as Bytescale from "@bytescale/sdk";
import fetch from "node-fetch";
const folderApi = new Bytescale.FolderApi({
fetchApi: nodeFetch,
apiKey: "YOUR_API_KEY"
});
folderApi
.listFolder({
accountId: "YOUR_ACCOUNT_ID",
folderPath: "/",
recursive: false
})
.then(
result => console.log(`Items in folder: ${result.items.length}`),
error => console.error(error)
);
📙 Bytescale SDK API Reference
For a complete list of operations, please see:
Bytescale JavaScript SDK Docs »
🌐 Media Processing APIs (Image/Video/Audio)
Bytescale provides several real-time Media Processing APIs:
Image Processing API (Original Image)
Here's an example using a photo of Chicago:
https://upcdn.io/W142hJk/raw/example/city-landscape.jpg
Image Processing API (Transformed Image)
Using the 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
Authentication
The Bytescale JavaScript SDK supports two types of authentication:
API Keys
The Bytescale JavaScript SDK automatically adds the apiKey
from the constructor to the authorization
header for all requests made via the SDK.
With API key auth, the requester has access to the resources available to the API key:
-
Secret API keys (secret_***
) can perform all API operations.
-
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.
Each Public API Key and Secret API Key can have its read/write access limited to a subset of files/folders.
JWTs
JWTs are optional.
With 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 <img>
, <video>
, and other elements.
With JWTs, the user can also perform API requests, such as file deletions, as these can be granted by the JWT's payload. The Bytescale JavaScript SDK will automatically inject the user's JWT into the authorization-token
request header for all API requests, assuming the AuthManager.beginAuthSession
method has been called.
Learn more about the AuthManager
and JWTs »
UrlBuilder
Use the UrlBuilder
to construct URLs for your uploaded files:
import { UrlBuilder } from "@bytescale/sdk";
Raw Files
To get the URL for the uploaded image /example.jpg
in its original form, use the following:
UrlBuilder.url({
accountId: "1234abc",
filePath: "/example.jpg"
});
Images
To resize the uploaded image /example.jpg
to 800x600, use the following:
UrlBuilder.url({
accountId: "1234abc",
filePath: "/example.jpg",
options: {
transformation: "image",
transformationParams: {
w: 800,
h: 600
}
}
});
Image Processing API Docs »
Videos
To transcode the uploaded video /example.mov
to MP4/H.264 in HD, use the following:
UrlBuilder.url({
accountId: "1234abc",
filePath: "/example.mov",
options: {
transformation: "video",
transformationParams: {
f: "mp4-h264",
h: 1080
}
}
});
Video Processing API Docs »
Audio
To transcode the uploaded audio /example.wav
to AAC in 192kbps, use the following:
UrlBuilder.url({
accountId: "1234abc",
filePath: "/example.wav",
options: {
transformation: "audio",
transformationParams: {
f: "aac",
br: 192
}
}
});
Audio Processing API Docs »
Archives
To extract the file document.docx
from the uploaded ZIP file /example.zip
:
UrlBuilder.url({
accountId: "1234abc",
filePath: "/example.zip",
options: {
transformation: "archive",
transformationParams: {
m: "extract"
},
artifact: "/document.docx"
}
});
Archive Processing API Docs »
Antivirus
To scan the file example.zip
for viruses, use the following:
UrlBuilder.url({
accountId: "1234abc",
filePath: "/example.zip",
options: {
transformation: "antivirus"
}
});
Antivirus API Docs »
🙋 Can I use my own storage?
Bytescale supports AWS S3, Cloudflare R2, Google Storage, DigitalOcean, and Bytescale Storage.
Bytescale Storage Docs »
Bytescale JavaScript SDK Docs »
👋 Create your Bytescale Account
Bytescale is the best way to upload, transform, and serve images, videos, and audio at scale.
Create a Bytescale account »
License
MIT