Save files to your own S3 bucket

By default, Bannerify saves a stored file on its CDN and returns a link on images.bannerify.co. Add an s3Config object to the request, and Bannerify writes the file to your bucket and returns the link to that copy. Use it when the files must live in your own storage or behind your own domain. Custom S3 storage is part of the Scale and Enterprise plans.

Prerequisites

• A workspace on the Scale or Enterprise plan. A request with s3Config from a workspace on the Free or Automate plan fails with FORBIDDEN and does not count as a generation.
• An S3-compatible bucket and an access key that can upload objects to it. Bannerify only uploads files. It does not read or delete anything in the bucket.
• A Bannerify API key and a template.

Save a file to your bucket

1. Add s3Config to the body of a createStoredImage or createStoredPdf request:

curl --request POST \
  --url https://api.bannerify.co/v1/templates/createStoredImage \
  --header 'Content-Type: application/json' \
  --data '{
    "apiKey": "YOUR_API_KEY",
    "templateId": "tpl_xxx",
    "modifications": [
      { "name": "headline", "text": "Saved to my bucket" }
    ],
    "s3Config": {
      "endPoint": "s3.amazonaws.com",
      "region": "us-east-1",
      "bucket": "my-bannerify-renders",
      "accessKey": "YOUR_ACCESS_KEY",
      "secretKey": "YOUR_SECRET_KEY"
    }
  }'

2. Read the response. The url points to the file in your bucket:

{
  "url": "https://my-bannerify-renders.s3.amazonaws.com/0b3c1c1e-5d6f-4c52-9e0a-8f6a4c0f2a11.png"
}

Send this request from your server. The body holds your API key and your secret key, so keep it out of browser code.

Only the two stored endpoints use s3Config. The createImage, createPdf, and signedurl endpoints do not save files.

s3Config fields

Field	Required	Description
endPoint	Yes	The S3 endpoint host without the protocol, such as s3.amazonaws.com
region	Yes	The region of the bucket, such as us-east-1
bucket	Yes	The name of the bucket
accessKey	Yes	The access key
secretKey	Yes	The secret key
port	No	The port of the endpoint. The default is 443. Set it when you turn useSSL off
useSSL	No	Connect over HTTPS. The default is true
pathStyle	No	Put the bucket name in the URL path (https://endpoint/bucket/file) instead of the host name (https://bucket.endpoint/file). The default is false
customUrl	No	A template for the returned link. Bannerify replaces {key} with the file name. This changes only the link in the response, and the upload still goes to endPoint

A missing required field fails with BAD_REQUEST.

Where the file goes

• Bannerify writes the file to the root of the bucket. The name is a random id plus an extension: .png, .jpg for JPEG, .webp, or .pdf. You cannot choose a folder or a name.
• The file lives only in your bucket. Bannerify does not keep a copy on its CDN.
• The returned link is not signed. It works only when whoever opens it can read the object, so make the object public or set customUrl to a public address.

Use Cloudflare R2

Cloudflare R2 uses the same fields. Set endPoint to ACCOUNT_ID.r2.cloudflarestorage.com with your account id, and set region to auto. R2 serves public files from a custom domain, so set customUrl to that domain:

{
  "endPoint": "ACCOUNT_ID.r2.cloudflarestorage.com",
  "region": "auto",
  "bucket": "my-bannerify-renders",
  "accessKey": "YOUR_ACCESS_KEY",
  "secretKey": "YOUR_SECRET_KEY",
  "customUrl": "https://files.example.com/{key}"
}

Use an SDK or a no-code tool

The JavaScript SDK accepts s3Config in createStoredImage. See Create images and PDFs. The Python and PHP SDKs cannot send s3Config, the Go SDK has no stored image method, and no SDK wraps createStoredPdf. Call the REST endpoint from those languages.

The Zapier, n8n, and Pipedream actions do not send s3Config. To save files to your bucket from a workflow, call the REST endpoint from an HTTP request step in the tool.

Handle upload errors

When the upload to your bucket fails, the request fails with INTERNAL_SERVER_ERROR and the message Failed to upload image to custom S3 storage. For a PDF the message is Failed to upload PDF to custom S3 storage. Check the endpoint, the region, the bucket name, and the keys. INTERNAL_SERVER_ERROR explains how to handle the code.

Send the link to other apps

To send a file to Google Drive, Dropbox, or Slack, add a step after the Bannerify action in Zapier, n8n, or Pipedream. That step uploads the file from its url or posts the link in a message.