Documentation
Upload, store, transform, and deliver product images with the Image Upload API, built on the Filestack File API.
Image Upload API Reference
This API is organized around REST. It has predictable resource-oriented URLs, accepts binary and form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. Uploads go to www.filestackapi.com and images are delivered from cdn.filestackcontent.com.
Just Getting Started?
Send your first upload with POST /upload, or add a browser upload widget with the Filestack web picker guide.
Authentication
Image Upload API uses API keys to authenticate requests. You can view and manage your API keys in the Filestack developer portal.
Pass the key as the key query parameter on upload and file requests, and as the first path segment of a transformation URL. The API key identifies your application and is safe to use in browser code.
Enabling application security in the developer portal requires a policy and signature on every request. Generate both on your server with the application secret, and keep the secret out of client-side code and public repositories. Overwrite and delete require a policy and signature on every application.
https:/
Send every request over HTTPS.
Endpoints
POST/uploadUpload a file image
POST https:/
Stores an image from the request body and returns its CDN URL. The handle at the end of the URL is the ID for every later call.
Parameters
| Parameter | Location, type | Description |
|---|---|---|
keyrequired | Query, string | Your Filestack API key. |
bodyrequired | Body, binary | The image file, sent as the raw request body with its Content-Type. |
filenameoptional | Query, string | Name for the stored file. |
mimetypeoptional | Query, string | MIME type of the file, for example image/jpeg. |
pathoptional | Query, string | Path to store the file under in the bucket. |
containeroptional | Query, string | Bucket or container to store the file in, when you connect your own storage. |
accessoptional | Query, string | S3 only. Access setting for the stored file: public or private. |
base64decodeoptional | Query, boolean | Decode a base64-encoded body before storing it. |
policy, signatureoptional | Query, string | Required when application security is enabled. |
Code samples
-H "Content-Type: image/
--data-binary @product.jpg \
"https:/
const res = await fetch(
'https:/
{ method: 'POST', headers: { 'Content-Type': file.type }, body: file }
);
console.log(await res.json());
with open('product.jpg', 'rb') as f:
res = requests.post(
'https:/
params={'key': 'YOUR_API_KEY', 'filename': 'product.jpg'},
headers={'Content-Type': 'image/
data=f,
)
print(res.json())
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: image/
CURLOPT_POSTFIELDS => file_get_contents('product.jpg'),
CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $result['url'];
import (
"fmt"
"io"
"net/
"os"
)
func main() {
f, _ := os.Open("product.jpg")
defer f.Close()
res, err := http.Post("https:/
if err != nil {
panic(err)
}
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}
import java.net.http.*;
import java.nio.file.Path;
public class Upload {
public static void main(String[] args) throws Exception {
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https:/
.header("Content-Type", "image/
.POST(HttpRequest.BodyPublishers.ofFile(Path.of("product.jpg")))
.build();
HttpResponse<String> res = HttpClient.newHttpClient()
.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
}
}
uri = URI('https:/
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'image/
req.body = File.binread('product.jpg')
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
http.request(req)
end
puts res.body
var content = new ByteArrayContent(File.ReadAllBytes("product.jpg"));
content.Headers.ContentType = new MediaTypeHeaderValue("image/
var res = await client.PostAsync(
"https:/
Console.WriteLine(await res.Content.ReadAsStringAsync());
const client = filestack.init('YOUR_API_KEY');
const file = await client.upload(fileInput.files[0]);
console.log(file.handle, file.url);
Words in capitals, such as YOUR_API_KEY, are placeholders to replace with your own values.
Returns
"url": "https:/
"size": 209870,
"type": "image/
"filename": "straw-hat.jpg"
}
POST/urlUpload an URL image
POST https:/
Fetches an image from a public URL and stores it. Send the source as a form-encoded url field.
Parameters
| Parameter | Location, type | Description |
|---|---|---|
keyrequired | Query, string | Your Filestack API key. |
urlrequired | Body, string | Public URL of the image to fetch and store, sent form-encoded. |
filenameoptional | Query, string | Name for the stored file. |
path, container, accessoptional | Query, string | Same as POST /upload. |
policy, signatureoptional | Query, string | Required when application security is enabled. |
Code samples
-d "url=https:/
"https:/
method: 'POST',
body: new URLSearchParams({ url: 'https:/
});
console.log(await res.json());
res = requests.post(
'https:/
params={'key': 'YOUR_API_KEY', 'filename': 'product.jpg'},
data={'url': 'https:/
)
print(res.json())
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query(['url' => 'https:/
CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
curl_close($ch);
Returns
"url": "https:/
"size": 209870,
"type": "image/
"filename": "hat-from-url.jpg"
}
GET/file/{HANDLE}/metadataRead image metadata
GET https://
Returns the stored file's properties. Request each field with a boolean query parameter.
Parameters
| Parameter | Location, type | Description |
|---|---|---|
HANDLErequired | Path, string | The file handle returned by an upload. |
width, heightoptional | Query, boolean | Return the image dimensions in pixels. |
mimetype, size, filenameoptional | Query, boolean | Return the MIME type, size in bytes, and stored filename. |
Code samples
'https:/
);
console.log(await res.json());
Returns
"filename": "straw-hat.jpg",
"height": 1118,
"mimetype": "image/
"size": 209870,
"width": 721
}
GET/{API_KEY}/{TASKS}/{HANDLE}Resize, crop, and optimize
GET https://
Chain tasks in the URL, separated by /, and they run left to right. The CDN caches each variant, and the stored original stays unchanged. Use the URL directly in an <img> tag, or end the chain with store to save the result as a new file.
Tasks
| Task | Parameters | What it does |
|---|---|---|
resize | width, height, fit, align | Resize to a width, a height, or both. fit:crop fills the box and crops the overflow; align picks the anchor.resize=width:480,height:480,fit:crop,align:center |
crop | dim | Cut an exact region: x and y of the top-left corner, then width and height. crop=dim:[40,120,600,600] |
rotate | deg, background | Rotate by degrees. deg:exif applies the orientation stored by the camera.rotate=deg:exif |
output | format, quality | Convert to jpg, png, webp, or avif at a set quality.output=format:webp,quality:80 |
compress | none | Recompress the image to reduce file size. compress |
enhance | none | Automatic color and lighting correction. Paid plans. enhance |
store | location, path, container | Save the transformed result as a new file and return its JSON. store |
Code samples
curl "https:/
Returns
The image bytes, or with store at the end of the chain:
"filename": "straw-hat.webp",
"handle": "2XF12SikSRO5r9D60ptO",
"size": 123968,
"type": "image/
"url": "https:/
}
The full task list is in the Filestack Processing API reference.
DELETE/file/{HANDLE}Delete a file
DELETE https://
Removes a stored file. Delete always requires a policy with the remove call and its signature, generated on your server with the application secret.
Parameters
| Parameter | Location, type | Description |
|---|---|---|
HANDLErequired | Path, string | The file handle to delete. |
keyrequired | Query, string | Your Filestack API key. |
policy, signaturerequired | Query, string | A policy that allows remove for this handle, and its HMAC-SHA256 signature. |
Code samples
"https:/
Rate Limiting
Each plan includes an allowance of uploads, transformations, bandwidth, and storage. Start on the Free plan and move to a larger plan as your catalog grows.
| Plan | Price | Uploads | Transformations | Bandwidth | Storage |
|---|---|---|---|---|---|
| Free | $0 | 500 | 1,000 | 1 GB | 1 GB |
| Start | $69 / mo | 20,000 | 50,000 | 75 GB | 50 GB |
| Grow | $199 / mo | 50,000 | 150,000 | 200 GB | 150 GB |
| Scale | $379 / mo | 125,000 | 300,000 | 400 GB | 350 GB |
| Enterprise | Custom | Custom | Custom | Custom | Custom |
Paid plans bill usage past the allowance at the overage rates on Filestack pricing. For volume beyond the Scale plan, contact Filestack about Enterprise.
Error Codes
Image Upload API uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate a problem with the request, such as an invalid parameter or a missing policy, and codes in the 5xx range indicate an error on Filestack's servers.
Error bodies are plain text that names the problem. A successful upload always returns JSON with a url field, so check for that field as well as the status code.
| Status | Explanation |
|---|---|
200 with Invalid Application | The key parameter is missing or does not match an application. The store endpoint answers with a plain-text body. |
200 with Invalid response when trying to read from | A POST /url source could not be fetched. Check that the URL is public. |
| 400 Bad Request | A transformation parameter is invalid, for example validation error: invalid value format abc for parameter width required by resize task. |
| 403 Forbidden | The request needs a policy and signature that allow the action, or it came from a domain outside the application whitelist. |
| 404 Not Found | The handle does not exist: file not found: HANDLE. |
| 5xx Server Error | Filestack could not process the request. Contact Filestack support with the request details. |
You can always contact Filestack support for more assistance with building your product.