Bannerify Docs
ドキュメントを検索.../
Discordダッシュボード
ドキュメントAPI リファレンスSDK
ナビゲーション
ドキュメントAPI リファレンスSDK

基本ガイド

画像の生成

Bannerify API を使って、テンプレートから PNG、JPEG、WebP の画像を生成する方法を説明します。

テンプレート ID と変更する値を 1 回のリクエストで送ると、レスポンスボディが画像になります。Bannerify はリクエストを待たせている間に画像を描画するので、リクエストハンドラー、バックグラウンドジョブ、スクリプトのどこからでも呼び出せます。

前提条件

  • テンプレート。作り方はテンプレートのデザインで説明しており、ギャラリーには作成済みのテンプレートもあります。
  • API キー。ダッシュボードの API Keys ページで作成します。
  • テンプレート ID。テンプレートカードのメニューを開き、Copy Template ID を選びます。

画像を生成する

  1. 変更したいレイヤーに、名前を付けます。方法は Modificationsで説明しています。
  2. JSON ボディを付けて、/v1/templates/createImage に POST リクエストを送ります。
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" }
    ]
  }'
  1. レスポンスを読み取ります。ボディは画像ファイルで、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 リクエストを送るため、プレビューのたびに 1 回の生成として数えられます。Download で PNG を保存し、Copy でクリップボードにコピーします。

左にテンプレートのレイヤー、右に生成されたプレビューを表示した Template Playground
Template Playground。

生成履歴を確認する

サイドバーの Generations ページには、API がプロジェクトで作成したすべての画像と PDF が、新しい順に一覧表示されます。リクエストが何を送ったかを確認したいときや、保存したファイルをもう一度探したいときに役立ちます。

  • 一覧は、Template と Time range（過去 24 時間、7 日間、30 日間）で絞り込めます。
  • 各行には、時刻、テンプレート、形式、サイズ、課金対象かどうかが表示されます。
  • Open は、保存したファイルを開きます。API がレスポンスで返したファイルには、Not stored と表示されます。
  • Copy modifications は、リクエストが送った値を、そのまま再送できる形でコピーします。
  • Load more で、さらに古い生成履歴を表示します。
過去 7 日間の描画を新しい順に表示した Generations ページ
Generations ページ。

ファイルの代わりにリンクを取得する

POST /v1/templates/createStoredImage は、同じボディを受け取り、バイト列の代わりに URL を返します。

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

Bannerify はファイルを保存し、CDN から公開 URL で配信します。メール、データベースの行、ノーコードツールにリンクを入れたいときに便利です。Scale プランと Enterprise プランでは、s3Config オブジェクトを送ると、自分の S3 互換バケットにファイルを保存することもできます。フィールドは、自分の S3 バケットにファイルを保存するにまとめています。

保存した画像は、1 回の生成として数えられます。

SDK を使う

SDK は、このリクエストを代わりに送り、バイト列を返します。

言語 ページ
JavaScript 画像と PDF の作成
Python 画像と PDF の作成
PHP 画像と PDF の作成
Go 画像と PDF の作成

エラーを処理する

失敗したリクエストは、画像の代わりに error オブジェクトを含む JSON を返します。error.code を読んで次の対応を決め、サポートに問い合わせるときは error.requestId を送ってください。すべてのコードは、エラーの処理にまとめています。

関連ページ