自分の S3 バケットにファイルを保存する

初期設定では、Bannerify は保存ファイルを CDN に保存し、images.bannerify.co のリンクを返します。リクエストに s3Config オブジェクトを追加すると、Bannerify はファイルをあなたのバケットに書き込み、そのコピーへのリンクを返します。ファイルを自分のストレージに置きたい場合や、自分のドメインで配信したい場合に使います。カスタム S3 ストレージは、Scale プランと Enterprise プランに含まれます。

前提条件

Scale プランまたは Enterprise プランのプランのワークスペース。Free プランまたは Automate プランのワークスペースから s3Config 付きのリクエストを送ると、FORBIDDEN で失敗し、生成としては数えられません。
S3 互換のバケットと、そこにオブジェクトをアップロードできるアクセスキー。Bannerify はファイルをアップロードするだけで、バケット内のものを読み取ったり削除したりはしません。
Bannerify の API キーとテンプレート。

ファイルをバケットに保存する

createStoredImage または createStoredPdf リクエストのボディに、s3Config を追加します。

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 を使うのは、2 つの保存エンドポイントだけです。createImage、createPdf、signedurl のエンドポイントは、ファイルを保存しません。

s3Config のフィールド

フィールド	必須	説明
`endPoint`	はい	プロトコルを除いた S3 エンドポイントのホスト（例: `s3.amazonaws.com`）
`region`	はい	バケットのリージョン（例: `us-east-1`）
`bucket`	はい	バケット名
`accessKey`	はい	アクセスキー
`secretKey`	はい	シークレットキー
`port`	いいえ	エンドポイントのポート。初期値は `443` です。`useSSL` をオフにするときに設定します
`useSSL`	いいえ	HTTPS で接続します。初期値は `true` です
`pathStyle`	いいえ	バケット名を、ホスト名（`https://bucket.endpoint/file`）ではなく、URL のパス（`https://endpoint/bucket/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 SDK と PHP SDK は s3Config を送信できず、Go SDK には保存画像のメソッドがなく、createStoredPdf をラップする SDK もありません。それらの言語では、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 からファイルをアップロードするか、リンクをメッセージに投稿します。