生成圖片

你只需要傳送一個帶有範本 ID 和要變更之值的請求，回應本文就是圖片。Bannerify 會在請求等待期間繪製圖片，所以你可以從請求處理程式、背景工作或腳本中呼叫它。

先決條件

• 一個範本。設計範本說明如何製作，圖庫中也有現成的範本。
• 一組 API 金鑰。請在儀表板的 API Keys 頁面建立。
• 範本 ID。開啟範本卡片上的選單，選擇 Copy Template ID。

生成圖片

1. 為你想變更的圖層命名。做法請見 Modifications。
2. 傳送一個 POST 請求到 /v1/templates/createImage，並帶上 JSON 本文：

curl --request POST \
  --url https://api.bannerify.co/v1/templates/createImage \
  --header 'Content-Type: application/json' \
  --output banner.png \
  --data '{
    "apiKey": "YOUR_API_KEY",
    "templateId": "tpl_xxx",
    "modifications": [
      { "name": "headline", "text": "Summer sale" }
    ]
  }'

3. 讀取回應。本文就是圖片檔案，Content-Type 標頭會指出格式：image/png、image/jpeg 或 image/webp。

請務必傳送 Content-Type: application/json 標頭。沒有這個標頭的請求會以 INTERNAL_SERVER_ERROR 失敗。

選項

欄位	型別	預設值	說明
apiKey	string		你的 API 金鑰。必填
templateId	string		要繪製的範本。必填
modifications	array、object 或 JSON 字串	[]	要變更的值。請見 Modifications
format	png、jpeg 或 webp	png	圖片格式。值有區分大小寫，所以 jpg 和 JPEG 會失敗
quality	1 到 100 的整數	90	jpeg 和 webp 的編碼品質。png 會忽略它

圖片的大小由範本決定。請求無法變更畫布。

PNG 是無損格式。JPEG 和 WebP 的檔案較小，quality 則用來調整檔案大小與細節之間的取捨。

在儀表板中試用範本

Generate 底下的 Form 頁面可以讓你不寫程式碼就測試範本。它的標題是 Template Playground。

1. 在 Select Template 中選擇範本，並在 API Key 中選擇金鑰。在你選擇其他金鑰之前，頁面會使用你的第一組金鑰。
2. 在 Elements 底下挑選圖層。對於文字圖層，可以在 Content 分頁修改 Text Content，或在 Style 分頁修改 Text Color。對於圖片圖層，請輸入 Image URL。圖層旁的眼睛按鈕可以隱藏該圖層。
3. 點選 Generate Preview。

頁面會用你選擇的金鑰傳送真正的 createImage 請求，所以每次預覽都會計為一次生成。Download 會儲存 PNG，Copy 則會把它放到剪貼簿。

查看你的生成紀錄

側邊欄的 Generations 頁面會依時間由新到舊，列出 API 為你的專案產生的每一張圖片和每一份 PDF。當你想確認某個請求傳送了什麼，或想重新找到儲存的檔案時，這個頁面很有用。

• 你可以依 Template 和 Time range 篩選清單：過去 24 小時、7 天或 30 天。
• 每一列都會顯示時間、範本、格式、大小，以及這次生成是否計費。
• Open 會開啟儲存的檔案。API 在回應中直接回傳的檔案，則會顯示 Not stored。
• Copy modifications 會複製請求傳送的值，可以直接再次傳送。
• Load more 會顯示更早的生成紀錄。

取得連結而不是檔案

POST /v1/templates/createStoredImage 接受相同的本文，並回傳網址，而不是位元組：

{
  "url": "https://images.bannerify.co/files/0b3c1c1e-5d6f-4c52-9e0a-8f6a4c0f2a11.png"
}

Bannerify 會儲存檔案，並透過 CDN 以公開網址提供。當你想把連結放進電子郵件、資料庫的資料列或免寫程式工具時，這很有用。在 Scale 和 Enterprise 方案中，你也可以傳送 s3Config 物件，把檔案儲存到你自己相容 S3 的儲存桶。它的欄位請見把檔案儲存到你自己的 S3 儲存桶。

儲存的圖片會計為一次生成。

使用 SDK

SDK 會替你傳送這個請求，並回傳位元組。

語言	頁面
JavaScript	建立圖片與 PDF
Python	建立圖片與 PDF
PHP	建立圖片與 PDF
Go	建立圖片與 PDF

處理錯誤

失敗的請求會回傳含有 error 物件的 JSON，而不是圖片。請讀取 error.code 決定下一步，需要協助時請把 error.requestId 傳給客服。所有錯誤碼請見處理錯誤。

相關頁面

• 生成 PDF：適用於發票、收據和證書。
• 從試算表生成圖片：用 CSV 或 XLSX 檔案填入範本。
• 簽署網址：在有人開啟連結時才繪製的圖片。
• 用量額度與限制：哪些情況會計為一次生成。