把檔案儲存到你自己的 S3 儲存桶

預設情況下，Bannerify 會把儲存的檔案放在它的 CDN 上，並回傳 images.bannerify.co 的連結。在請求中加上 s3Config 物件，Bannerify 就會把檔案寫入你的儲存桶，並回傳指向該副本的連結。當檔案必須放在你自己的儲存空間，或透過你自己的網域提供時，請使用這個功能。自訂 S3 儲存是 Scale 和 Enterprise 方案的一部分。

先決條件

一個 Scale 或 Enterprise 方案的工作區。Free 或 Automate 方案的工作區傳送帶有 s3Config 的請求，會以 FORBIDDEN 失敗，也不會計為一次生成。
一個相容 S3 的儲存桶，以及可以上傳物件到其中的存取金鑰。Bannerify 只會上傳檔案，不會讀取或刪除儲存桶中的任何東西。
一組 Bannerify API 金鑰和一個範本。

把檔案儲存到你的儲存桶

把 s3Config 加到 createStoredImage 或 createStoredPdf 請求的本文中：

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"
    }
  }'

讀取回應。url 指向你儲存桶中的檔案：

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

請從你的伺服器傳送這個請求。本文中包含你的 API 金鑰和密鑰，所以請不要放在瀏覽器端的程式碼中。

只有這兩個儲存端點會使用 s3Config。createImage、createPdf 和 signedurl 端點不會儲存檔案。

s3Config 欄位

欄位	必填	說明
`endPoint`	是	不含通訊協定的 S3 端點主機，例如 `s3.amazonaws.com`
`region`	是	儲存桶所在的區域，例如 `us-east-1`
`bucket`	是	儲存桶的名稱
`accessKey`	是	存取金鑰
`secretKey`	是	密鑰
`port`	否	端點的連接埠。預設為 `443`。關閉 `useSSL` 時請設定它
`useSSL`	否	透過 HTTPS 連線。預設為 `true`
`pathStyle`	否	把儲存桶名稱放在網址路徑中（`https://endpoint/bucket/file`），而不是主機名稱中（`https://bucket.endpoint/file`）。預設為 `false`
`customUrl`	否	回傳連結的範本。Bannerify 會把 `{key}` 換成檔案名稱。這只會變更回應中的連結，上傳仍然是傳到 `endPoint`

缺少必填欄位時，會以 BAD_REQUEST 失敗。

檔案會存到哪裡

Bannerify 會把檔案寫入儲存桶的根目錄。名稱是隨機 ID 加上副檔名：.png、JPEG 為 .jpg、.webp 或 .pdf。你無法選擇資料夾或名稱。
檔案只存在於你的儲存桶中。Bannerify 不會在它的 CDN 上保留副本。
回傳的連結沒有簽署。只有在開啟連結的人能讀取該物件時才有效，所以請把物件設為公開，或把 customUrl 設為公開的位址。

使用 Cloudflare R2

Cloudflare R2 使用相同的欄位。請把 endPoint 設為帶有你帳號 ID 的 ACCOUNT_ID.r2.cloudflarestorage.com，並把 region 設為 auto。R2 透過自訂網域提供公開檔案，所以請把 customUrl 設為該網域：

{
  "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}"
}

使用 SDK 或免寫程式工具

JavaScript SDK 的 createStoredImage 接受 s3Config。請見建立圖片與 PDF。Python 和 PHP SDK 無法傳送 s3Config，Go SDK 沒有儲存圖片的方法，也沒有任何 SDK 包裝 createStoredPdf。使用這些語言時，請直接呼叫 REST 端點。

Zapier、n8n 和 Pipedream 的動作不會傳送 s3Config。若要從工作流程把檔案儲存到你的儲存桶，請在工具的 HTTP 請求步驟中呼叫 REST 端點。

處理上傳錯誤

當上傳到你的儲存桶失敗時，請求會以 INTERNAL_SERVER_ERROR 失敗，訊息為 Failed to upload image to custom S3 storage。如果是 PDF，訊息則是 Failed to upload PDF to custom S3 storage。請檢查端點、區域、儲存桶名稱和金鑰。這個錯誤碼的處理方式，請見 INTERNAL_SERVER_ERROR。

把連結傳送到其他應用程式

若要把檔案傳送到 Google Drive、Dropbox 或 Slack，請在 Zapier、n8n 或 Pipedream 中，於 Bannerify 動作之後新增一個步驟。該步驟會從 url 上傳檔案，或把連結貼在訊息中。