Get Started with a Backblaze Integration

If you are new to Backblaze B2 Cloud Storage, start here. Complete the following steps to configure access and begin transferring data to and from Backblaze B2. This setup should take about 15 minutes.

Choose Your API

Backblaze B2 offers two APIs. Choose one before you write a single line of code.

Not sure? Start with the S3-Compatible API. It supports most use cases and works with the broad ecosystem of S3-compatible tools, often with little to no additional configuration.  

Coming from AWS S3? The S3-Compatible API is designed as a drop-in replacement. Simply update the endpoint URL and continue using your existing code, SDKs, and tools.

Create an Account and Enable B2

Skip this step if you already have a Backblaze account.

If you already have a Backblaze account and the left navigation menu contains a B2 Cloud Storage section, your account is already enabled for Backblaze B2.

1. Go to backblaze.com, and click Start Free.

2. Click Try for Free.

3. Complete the registration, and verify your email address.

4. Sign in to the Backblaze web console.

5. In the user menu in the upper-right corner of the page, select My Settings.

6. Under Enabled Products, select the checkbox to enable B2 Cloud Storage.

7. Review the Terms and Conditions, and click OK to accept them. 

Note

Backblaze B2 Cloud Storage and Backblaze Computer Backup are separate products. This guide covers only Backblaze B2.

Generate Credentials

Do not use your Backblaze account password for API access.

Master Application Key

The master application key has full account access. For production, create a scoped key below that limits access to a specific bucket.

Scoped Application Key (Recommended)

For the S3-Compatible API: Your keyID maps to AWS_ACCESS_KEY_ID and your applicationKey maps to AWS_SECRET_ACCESS_KEY.

Create a Bucket

Buckets are the top-level containers for your data.

Important: Your Backblaze B2 account is tied to a single region. Your endpoint URL must match that region, for example, s3.us-west-004.backblazeb2.com.

Make Your First API Call

Choose the example that matches your preferred tool or programming language.

AWS CLI (S3-Compatible API)

Use the AWS CLI to connect to Backblaze B2 through the S3-Compatible API.

1. Configure a named profile pointing at Backblaze B2:

   aws configure --profile backblaze

2. When prompted, enter your keyID as the Access Key ID and your applicationKey as the Secret Access Key. Set the region to your Backblaze B2 region (for example, us-west-004).

3. Verify the connection:  

   aws s3 ls \
     --endpoint-url https://s3.YOUR-REGION.backblazeb2.com \
     --profile backblaze

4. Upload a file:  

   aws s3 cp ./myfile.txt s3://YOUR-BUCKET-NAME/myfile.txt \
     --endpoint-url https://s3.YOUR-REGION.backblazeb2.com \
     --profile backblaze

Python (boto3, S3-Compatible API)

Use the AWS SDK for Python (boto3) to connect to Backblaze B2 through the S3-Compatible API. This example lists your buckets, uploads a file, and downloads a file.

import boto3

s3 = boto3.client(
    's3',
    endpoint_url='https://s3.YOUR-REGION.backblazeb2.com',
    aws_access_key_id='YOUR_KEY_ID',
    aws_secret_access_key='YOUR_APPLICATION_KEY',
    region_name='YOUR-REGION'
)

# List buckets
response = s3.list_buckets()
for bucket in response['Buckets']:
    print(bucket['Name'])

# Upload a file
s3.upload_file('myfile.txt', 'YOUR-BUCKET-NAME', 'myfile.txt')

# Download a file
s3.download_file('YOUR-BUCKET-NAME', 'myfile.txt', 'downloaded.txt')

Node.js (AWS SDK for JavaScript v3)

Use the AWS SDK for JavaScript v3 to connect to Backblaze B2 through the S3-Compatible API. This example lists your buckets and uploads a file.

import { S3Client, ListBucketsCommand, PutObjectCommand } from "@aws-sdk/client-s3";
import { readFileSync } from "fs";

const client = new S3Client({
  endpoint: "https://s3.YOUR-REGION.backblazeb2.com",
  region: "YOUR-REGION",
  credentials: {
    accessKeyId: "YOUR_KEY_ID",
    secretAccessKey: "YOUR_APPLICATION_KEY",
  },
});

// List buckets
const { Buckets } = await client.send(new ListBucketsCommand({}));
console.log("Buckets:", Buckets.map(b => b.Name));

// Upload a file
await client.send(new PutObjectCommand({
  Bucket: "YOUR-BUCKET-NAME",
  Key: "myfile.txt",
  Body: readFileSync("myfile.txt"),
}));

B2 Native API

Use the B2 Native API when you want direct access to Backblaze B2 features without the S3 compatibility layer.

Authenticate to get an authorization token and API URL:

curl \
  -H "Authorization: Basic $(echo -n 'YOUR_KEY_ID:YOUR_APPLICATION_KEY' | base64)" \
  "https://api.backblazeb2.com/b2api/v4/b2_authorize_account"

The response includes an authorizationToken and apiInfo.storageApi.apiUrl. Save these values for future requests.

List your buckets using the authorization token and API URL:

curl \
  -H "Authorization: YOUR_AUTH_TOKEN" \
  "YOUR_API_URL/b2api/v4/b2_list_buckets?accountId=YOUR_ACCOUNT_ID"

Build AI Apps on Backblaze B2

AI and ML applications can use Backblaze B2 to store data objects across the full project lifecycle: training and fine-tuning datasets, model weights and checkpoints, cached models, embeddings and vector store snapshots, and generated image, audio, and video files. Model training and inference run on separate compute infrastructure (local hardware or a model provider's API) and read from and write to Backblaze B2 as needed.

Use the application key and endpoint from the previous steps to connect. Most AI and ML tooling uses the S3-Compatible API, because the majority of machine learning libraries include an S3 client. Standard object-storage libraries like boto3 and s3fs work directly with Backblaze B2. The following example uses the client defined in Python (boto3, S3-Compatible API):

# Upload a model checkpoint
s3.upload_file("checkpoint.pt", "YOUR-BUCKET-NAME", "runs/checkpoint.pt")

# Download a training dataset
s3.download_file("YOUR-BUCKET-NAME", "datasets/train.parquet", "train.parquet")

Backblaze Labs

Backblaze Labs publishes open-source tools that integrate Backblaze B2 with AI and ML workflows. These projects are experimental and not production-supported.

genblaze: Python SDK for generative media pipelines (video, image, and audio) across providers including OpenAI, Google, and Runway. genblaze uses Backblaze B2 as its default storage backend; each run writes output assets and a SHA-256 provenance manifest to Backblaze B2.

from genblaze_core import Pipeline, Modality, ObjectStorageSink
from genblaze_openai import SoraProvider
from genblaze_s3 import S3StorageBackend

# Backend reads B2_KEY_ID and B2_APP_KEY from the environment
storage = ObjectStorageSink(S3StorageBackend.for_backblaze("YOUR-BUCKET-NAME"))

result = (
    Pipeline("demo")
    .step(SoraProvider(), model="sora-2", prompt="a coastal city at sunrise", modality=Modality.VIDEO)
    .run(sink=storage, timeout=300)
)

print(result.run.steps[0].assets[0].url)  # durable B2 object URL

The generation provider requires an API key, in this example, OPENAI_API_KEY.

hf-cache-sync: Synchronizes a local Hugging Face model cache to Backblaze B2 for shared access across machines and CI runners.

jupyter-b2 / jupyterlab-b2: Extensions that add Backblaze B2 access directly to Jupyter and JupyterLab notebooks.

b2-vscode: Extension that manages Backblaze B2 buckets and files from within Visual Studio Code.

Connect an Integration Partner

For each tool, the configuration pattern is the same: provide your endpoint URL, key ID, and application key in the tool's storage settings.

Common Issues

If you run into problems during setup, review the following issues and solutions.

Wrong endpoint URL

Your endpoint must match your account's region. Find it on the Buckets page next to your bucket name. Using s3.amazonaws.com instead of the Backblaze B2 endpoint is a common mistake.

Authentication fails immediately

Make sure you are using an application key and not your Backblaze account password. Confirm the key has access to the bucket you are targeting.

ACL errors (S3-Compatible API)

Backblaze B2 supports only private and public-read canned ACLs at the bucket level. Per-object ACL overrides are not supported. Remove or adjust object-level ACL logic before pointing existing S3 code at Backblaze B2.

What's Next?

Connecting a tool? Browse the Integration Guides for step-by-step setup.

Writing your own integration? Visit the API Reference for full endpoint documentation, error codes, and advanced options.