用 MCP 工具生成檔案

Bannerify MCP 伺服器有六個工具。助理會依據你的請求挑選工具，所以你很少需要直接指定工具名稱。每個工具都只會作用於所連接的工作區。如果還沒有連接，請先連接 MCP 用戶端。

工具

工具	功能	是否計為一次生成	引數
list_templates	列出工作區中的範本。加上 includeLayers 時，也會列出可以變更的圖層	否	includeLayers（boolean，選填）
get_template	讀取一個範本及其圖層	否	templateId（string）
get_project	讀取工作區：它的 ID、名稱、方案和建立日期	否	無
create_image	繪製範本並回傳圖片	是	templateId（string）、modifications（object，選填）、format（png、jpeg 或 webp，預設為 png）
create_pdf	把範本繪製成 PDF，並回傳連結	是	templateId（string）、modifications（object，選填）
create_image_from_shapes	不使用範本，直接用形狀組合出圖片	是	canvas（object，選填）、shapes（array）、format（png、jpeg 或 webp，預設為 png）

範本 ID 請完全照 list_templates 回傳的內容使用。

尋找範本

請助理列出範本和它們的圖層：

列出我的 Bannerify 範本，以及每個範本的圖層。

工具會為每個範本回傳一個項目。沒有 includeLayers 時，項目只包含 ID 和名稱。有的話，每個圖層都會附上要在 modifications 中使用的名稱：

[
  {
    "id": "tpl_xxx",
    "name": "Lifecycle email",
    "layers": [
      { "name": "headline", "id": "shape:abc123", "type": "text", "suggestInput": "text" },
      { "name": "photo", "id": "shape:def456", "type": "image", "suggestInput": "src" },
      { "name": "qr", "id": "shape:ghi789", "type": "qrcode", "suggestInput": null }
    ]
  }
]

suggestInput 指出要設定的欄位：文字圖層是 text，圖片圖層是 src，其他類型則是 null。沒有名稱的圖層會顯示為 Untitled。

圖層名稱來自範本編輯器，你可以連按兩下圖層來重新命名。名稱如何對應到圖層，請見 Modifications。

傳入圖層的值

modifications 是以圖層名稱為鍵的物件。字串會設定圖層的文字，物件則會設定該圖層的欄位。REST API 使用的陣列格式在這裡無效。

圖層	範例值
文字	{ "headline": "Summer sale" }
圖片	{ "photo": { "src": "https://example.com/photo.png" } }
QR 碼	{ "qr": { "qrcode": "https://example.com/restart" } }
表格	{ "prices": { "columns": ["Plan", "Price"], "rows": [{ "Plan": "Automate", "Price": "$29" }] } }
任何圖層	{ "tag": { "visible": false } }

create_image 的完整範例：

{
  "templateId": "tpl_xxx",
  "format": "png",
  "modifications": {
    "headline": "Welcome back, An",
    "photo": { "src": "https://example.com/hero.png" },
    "qr": { "qrcode": "https://example.com/restart" }
  }
}

沒有列出的圖層會維持範本中的值，與任何圖層都不相符的名稱則會被忽略。每種圖層類型的欄位，請見 Modifications。

讀取結果

create_image 會直接回傳圖片，並附上一行說明格式與位元組大小的文字。如何顯示或儲存圖片，由你的用戶端決定。

create_pdf 會儲存檔案並回傳連結：

Generated a PDF from template tpl_xxx. Download: https://images.bannerify.co/files/mcp/0b3c1c1e-5d6f-4c52-9e0a-8f6a4c0f2a11.pdf

PDF 只有一頁，大小與畫布相同，文字可以選取和搜尋。詳情請見生成 PDF。

不用範本組合圖片

沒有合適的範本時，請使用 create_image_from_shapes。給工具一個畫布和一份形狀清單，它會依序繪製這些形狀並回傳圖片，因此助理可以設計一次性的橫幅或發票。

canvas 物件是選填的。除非你設定下列欄位，否則大小為 1200 × 630 像素，背景為白色：

欄位	說明
width, height	以像素為單位的大小，每邊 16 到 4096
background	純色。預設為白色
backgroundImage	HTTPS 網址、資料網址，或 CSS 漸層，例如 linear-gradient(to right, #4f46e5, #9333ea)。它的優先順序高於 background
objectFit	背景圖片如何填滿畫布：cover（預設）、contain 或 none

每個形狀都有 type、x、y、width 和 height，單位為像素，從畫布左上角算起。第一個形狀在最下層，最後一個在最上層。另外有三個欄位適用於每種類型：opacity（0 到 1）、rotation（度數，順時針）和 style。

類型	必填	選填
text	text	fontSize（預設 24）、align（left、center 或 right）、lineClamp、color、fontFamily、fontWeight
frame	無	backgroundColor、borderColor、borderWidth、borderRadius
image	src	objectFit（fill、contain、cover、none 或 scale-down；預設為 cover）、borderRadius
qrcode	qrcode	backgroundColor
barcode	barcode	無
icon	icon	color
star	無	star（1 到 5，預設 1）、color
table	columns、rows	footer、variant、stripe、compact、fontFamily、align（left、center 或 right）

幾項規則：

• icon 接受 Iconoir 的名稱，例如 check-circle 或 arrow-right。Iconoir 沒有的名稱會讓呼叫失敗。
• src 接受 HTTPS 網址或資料網址。遠端圖片的載入規則與範本相同：PNG、JPEG、WebP 或 SVG，下載失敗時會回傳 FETCH_IMAGE_ERROR。
• 表格的每一列，每個欄位都只有一個值。這與 modifications 不同，在 modifications 中，一列是一個物件。variant 可以是 line、grid（預設）、minimal、striped、compact、bordered 或 primary-header。
• style 接受駝峰式命名的 CSS 屬性名稱，例如 padding、boxShadow、lineHeight 和 letterSpacing。繪製引擎不支援的鍵會讓呼叫失敗，並顯示 Unrecognized key 訊息。大小請用 width 和 height 設定，不要用 style。
• 形狀上的欄位，例如 color 或 borderRadius，優先於 style 中相同的鍵。
• 顏色可以是十六進位值、rgb()、hsl() 或 CSS 顏色名稱。

限制	值
形狀	1 到 100 個
畫布	每邊 16 到 4096 像素，總共最多 12,000,000 像素
文字	4,000 個字元
表格	12 欄、200 列
src 和 backgroundImage	8,192 個字元
qrcode 的值	2,000 個字元
barcode 的值	200 個字元

完整範例，一張發票：

{
  "canvas": { "width": 800, "height": 560, "background": "#f8fafc" },
  "shapes": [
    { "type": "frame", "x": 0, "y": 0, "width": 800, "height": 120, "backgroundColor": "#0f172a" },
    { "type": "text", "x": 48, "y": 44, "width": 400, "height": 40, "text": "INVOICE", "fontSize": 30, "color": "#ffffff" },
    { "type": "text", "x": 500, "y": 52, "width": 252, "height": 24, "text": "INV-1042", "fontSize": 18, "align": "right", "color": "#94a3b8" },
    {
      "type": "table",
      "x": 48,
      "y": 176,
      "width": 704,
      "height": 180,
      "columns": ["Item", "Qty", "Total"],
      "rows": [["Logo pack", 1, "$29.00"], ["Banner credits", 500, "$19.00"]],
      "footer": ["", "Due", "$48.00"],
      "variant": "striped",
      "compact": true
    },
    { "type": "text", "x": 48, "y": 392, "width": 300, "height": 28, "text": "Thank you for your business.", "fontSize": 16, "color": "#475569" },
    { "type": "qrcode", "x": 632, "y": 384, "width": 120, "height": 120, "qrcode": "https://bannerify.co/invoices/1042" }
  ]
}

Bannerify 會在繪製之前檢查整個請求，所以無效的請求不會使用一次生成。有效的請求則與從範本生成相同，會被計算。請見用量額度與限制。

處理錯誤

失敗的呼叫會回傳 isError: true，以及下列兩種形式之一的文字訊息：

形式	意義
CODE: message，例如 NOT_FOUND: template tpl_xxx not found	來自 Bannerify 的錯誤。錯誤碼列在下一張表
Invalid arguments. <field>: <message>	引數與工具不符，訊息會指出欄位。這種形式沒有錯誤碼

錯誤碼	意義	該怎麼做
NOT_FOUND	這個工作區中沒有該範本。其他工作區的範本也找不到	執行 list_templates，並使用結果中的 ID
USAGE_EXCEEDED	工作區已達到每月或每日的生成次數上限	等到下一個週期，或請見用量額度與限制
BAD_REQUEST	create_image_from_shapes 中的顏色或樣式值無效，或 modifications 中的值不符合圖層欄位	修正訊息指出的值。對於 modifications，訊息會給出圖層在你物件中的位置，從 0 開始算，例如 modifications[0].src
FETCH_IMAGE_ERROR	無法下載圖片，或圖片太大而無法解碼	使用會回傳圖片的公開網址
INTERNAL_SERVER_ERROR	繪製失敗，或 icon 名稱在 Iconoir 中不存在	再試一次，並檢查圖示名稱

權杖不存在或已過期時，會在任何工具執行之前收到 HTTP 401 和錯誤 invalid_token，所以工具永遠不會回傳 UNAUTHORIZED。之後你的用戶端會重新登入。RATE_LIMITED 和 TOO_MANY_REQUESTS 不會發生，因為 MCP 伺服器沒有請求速率限制。REST API 的錯誤碼請見處理錯誤。

瞭解更多

• 連接 MCP 用戶端
• Modifications
• 圖層類型