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,
});
A URL to an accessible image to upload (alternative to file upload)
An optional custom unique identifier for your image
Whether the image can only be accessed using a signed URL
User modifiable key-value metadata. Must not exceed 1024 bytes.
When the image was uploaded
Whether signed URLs are required to access the image
Available variants for the image
List images (v1)
This endpoint is deprecated. Use the v2 list endpoint instead.
for await (const image of client.images.v1.list({
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
console.log(image.id, image.filename);
}
Page number of paginated results
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,
});
}
Number of items per page (max 10,000)
Continuation token for fetching the next page
Filter by creator ID. Use empty string "" for images without a creator.
Sorting order by upload time: asc or desc
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' },
);
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',
},
},
);
Whether the image requires signed URLs for access
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' },
);
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
Whether uploaded images require signed URLs
Metadata to associate with the uploaded image
Expiration time for the upload URL (RFC 3339)
Custom identifier for the image
The unique upload URL for direct upload
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',
});