Images

Upload and manage images with Cloudflare Images

Cloudflare Images provides image storage, resizing, optimization, and delivery. The Images API allows you to upload and manage images programmatically.

Upload an image

Upload an image with up to 10 megabytes using a single HTTP POST request.

const image = await client.images.v1.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: imageFile,
});

account_id · string · required

The account identifier

file · File

The image file to upload

url · string

A URL to an accessible image to upload (alternative to file upload)

id · string

An optional custom unique identifier for your image

requireSignedURLs · boolean

Whether the image can only be accessed using a signed URL

metadata · object

User modifiable key-value metadata. Must not exceed 1024 bytes.

id · string

Image unique identifier

filename · string

Image file name

uploaded · string

When the image was uploaded

requireSignedURLs · boolean

Whether signed URLs are required to access the image

variants · array

Available variants for the image

meta · object

User-defined metadata

List images (v1)

This endpoint is deprecated. Use the v2 list endpoint instead.

List up to 100 images with one request.

for await (const image of client.images.v1.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(image.id, image.filename);
}

account_id · string · required

The account identifier

page · number

Page number of paginated results

per_page · number

Number of items per page (max 100)

List images (v2)

List up to 10,000 images with continuation token support.

const response = await client.images.v2.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  per_page: 1000,
});

for (const image of response.images || []) {
  console.log(image.id, image.filename);
}

// Fetch next page if continuation token exists
if (response.continuation_token) {
  const nextPage = await client.images.v2.list({
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    continuation_token: response.continuation_token,
  });
}

account_id · string · required

The account identifier

per_page · number

Number of items per page (max 10,000)

continuation_token · string

Continuation token for fetching the next page

creator · string

Filter by creator ID. Use empty string "" for images without a creator.

sort_order · string

Sorting order by upload time: asc or desc

images · array

Array of image objects

continuation_token · string

Token to fetch the next page (null if no more pages)

Get an image

Fetch details for a single image.

const image = await client.images.v1.get(
  'image_id',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

imageId · string · required

The image identifier

account_id · string · required

The account identifier

Update an image

Update image access control or metadata.

const image = await client.images.v1.edit(
  'image_id',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    requireSignedURLs: true,
    metadata: {
      alt: 'Product image',
      category: 'products',
    },
  },
);

imageId · string · required

The image identifier

account_id · string · required

The account identifier

requireSignedURLs · boolean

Whether the image requires signed URLs for access

metadata · object

User modifiable metadata. Must not exceed 1024 bytes.

Delete an image

Delete an image from Cloudflare Images. All copies of the image are deleted and purged from cache.

await client.images.v1.delete(
  'image_id',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

imageId · string · required

The image identifier

account_id · string · required

The account identifier

Direct upload

Create a unique one-time upload URL for direct user uploads.

const upload = await client.images.v2.directUploads.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  requireSignedURLs: true,
  metadata: {
    user: 'user_123',
  },
});

console.log(upload.uploadURL); // Use this URL to upload the image

account_id · string · required

The account identifier

requireSignedURLs · boolean

Whether uploaded images require signed URLs

metadata · object

Metadata to associate with the uploaded image

expiry · string

Expiration time for the upload URL (RFC 3339)

id · string

Custom identifier for the image

uploadURL · string

The unique upload URL for direct upload

id · string

The image identifier that will be assigned

Image variants

Manage image variants to create different sizes and formats.

// Create a variant
const variant = await client.images.v1.variants.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  id: 'thumbnail',
  options: {
    fit: 'cover',
    width: 200,
    height: 200,
  },
});

// List variants
const variants = await client.images.v1.variants.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

// Get a variant
const variant = await client.images.v1.variants.get(
  'thumbnail',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

// Update a variant
await client.images.v1.variants.edit(
  'thumbnail',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    options: {
      fit: 'contain',
      width: 300,
      height: 300,
    },
  },
);

// Delete a variant
await client.images.v1.variants.delete(
  'thumbnail',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

Signing keys

Manage signing keys for signed URL tokens.

// List signing keys
const keys = await client.images.v1.keys.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

// Update a signing key
await client.images.v1.keys.update(
  'key_id',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    name: 'Production Key',
  },
);

// Delete a signing key
await client.images.v1.keys.delete(
  'key_id',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

Get usage statistics

Get statistics about image usage.

const stats = await client.images.v1.stats.get({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

console.log(`Images: ${stats.count.current} / ${stats.count.allowed}`);

Get base image

Get the base image data without transformations.

const blob = await client.images.v1.blobs.get({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  image_id: 'image_id',
});

account_id · string · required

The account identifier

image_id · string · required

The image identifier