Python SDK | Bannerify Docs

bannerify 是 Python 3.8 以上版本的 Bannerify 用戶端。它以值的形式回傳錯誤，所以請求失敗時不會引發例外。

安裝

Examples

Open only what you need

pip

pip install bannerify

uv add bannerify

建立用戶端

你需要一組 API 金鑰。請到儀表板的 API Keys 頁面建立，並把它留在伺服器上。

import os

from bannerify import BannerifyClient

client = BannerifyClient(os.environ["BANNERIFY_API_KEY"])

用戶端會持有一個 HTTP 連線池。用完時請呼叫 client.close()，或把用戶端當作情境管理器使用：

with BannerifyClient(os.environ["BANNERIFY_API_KEY"]) as client:
    result = client.create_image("tpl_xxx")

生成圖片

result = client.create_image(
    "tpl_xxx",
    modifications=[{"name": "headline", "text": "Summer sale"}],
)

if "error" in result:
    raise RuntimeError(result["error"]["message"])

with open("banner.png", "wb") as file:
    file.write(result["result"])

result["result"] 存放圖片的位元組。

方法

方法	結果	用途
`create_image`	`bytes`	取得圖片的位元組
`create_pdf`	`bytes`	取得 PDF
`create_stored_image`	網址字串	取得託管的圖片網址
`render_video` (Beta)	事件的迭代器	渲染影片並追蹤進度
`render_and_wait_video` (Beta)	網址字串	渲染影片並取得它的 MP4 網址
`create_video` (Beta)	已建立影片的 dict	不等待就開始影片，並立即取得它的 ID
`get_video` (Beta)	影片的 dict	依 ID 讀取影片的狀態和 MP4 網址
`watch_video` (Beta)	事件的迭代器	依 ID 再次追蹤影片的進度
`generate_image_signed_url`	網址字串	建立一個在有人開啟時渲染的連結

前三個方法請見建立圖片和 PDF，影片方法請見渲染影片，最後一個請見簽署網址。

處理錯誤

除了 generate_image_signed_url 之外，每個方法都會回傳含有 result 鍵或 error 鍵的 dict，兩者不會同時出現。

{"result": b"..."}

{"error": {"code": "NOT_FOUND", "message": "...", "docs": "...", "requestId": "..."}}

API 回傳的錯誤包含全部四個鍵。docs 連結到該代碼的頁面，需要針對某個請求尋求協助時，請把 requestId 提供給支援團隊。各個代碼請見錯誤。

SDK 自己會建立幾種錯誤。它們有 code、message 和 docs，但沒有 requestId。

代碼	意義
`INVALID_FORMAT`	格式不是 `png`、`jpeg` 或 `webp`
`TIMEOUT`	請求超過逾時時間
`TIMEOUT_ERROR`	影片串流中斷，且 SDK 無法再次讀取影片
`REQUEST_ERROR`	請求在 API 回應之前就失敗，例如連線中斷
`HTTP_ERROR`	API 回應了錯誤，但 SDK 無法讀取
`EXCEPTION`	SDK 內部發生的其他例外。`message` 是例外的文字

generate_image_signed_url 會回傳字串，當格式不受支援時會引發 ValueError。

選項

client = BannerifyClient(
    os.environ["BANNERIFY_API_KEY"],
    timeout=30.0,
)

選項	預設值	說明
`base_url`	`https://api.bannerify.co/v1`	API 的基本網址
`timeout`	`60.0`	請求逾時時間，單位為秒

Modification 模型

modification 是一個 dict。你也可以傳入 bannerify 的 Modification 模型，用戶端會幫你轉換。

from bannerify import Modification

client.create_image("tpl_xxx", modifications=[Modification(name="headline", text="Hello")])