Go SDK

bannerify-go は、Go 向けの Bannerify クライアントです。リクエストごとに context.Context を受け取り、エラーを値として返します。

インストール

go get github.com/bannerify/bannerify-go

クライアントを作成する

API キーが必要です。ダッシュボードの API Keys ページで作成し、サーバー側で管理してください。

import "github.com/bannerify/bannerify-go"

client := bannerify.NewClient(os.Getenv("BANNERIFY_API_KEY"))

画像を生成する

Modification の Name 以外のフィールドは、すべてポインターです。例では、次のヘルパーでポインターを作っています。

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/bannerify/bannerify-go"
)

func ptr[T any](value T) *T { return &value }

func main() {
	client := bannerify.NewClient(os.Getenv("BANNERIFY_API_KEY"))

	result := client.CreateImage(context.Background(), "tpl_xxx", &bannerify.CreateImageOptions{
		Modifications: []bannerify.Modification{
			{Name: "headline", Text: ptr("Summer sale")},
		},
	})
	if result.Error != nil {
		fmt.Println(result.Error.Message)
		return
	}

	if err := os.WriteFile("banner.png", result.Result, 0o644); err != nil {
		fmt.Println(err)
	}
}

result.Result は、画像を保持する []byte です。

メソッド

メソッド	戻り値	用途
CreateImage	*Response	画像のバイト列を Result に取得する
CreatePDF	*Response	PDF を Result に取得する
RenderVideo (Beta)	iter.Seq[RenderVideoEvent]	動画をレンダリングし、進行状況を追う
RenderAndWaitVideo (Beta)	string と error	動画をレンダリングし、MP4 の URL を取得する
CreateVideo (Beta)	*CreatedVideo と error	待たずに動画を開始し、その ID をすぐに取得する
GetVideo (Beta)	*Video と error	ID から、動画のステータスと MP4 の URL を読み取る
WatchVideo (Beta)	iter.Seq[RenderVideoEvent]	ID から、動画の進行状況をもう一度追う
GenerateImageSignedURL	string と error	開かれたときにレンダリングされるリンクを作る

動画のメソッドは、動画のレンダリングで説明しています。Go SDK には、保存済み画像のメソッドがありません。保存済み画像を作成するを、REST で呼び出してください。

最初の 2 つは画像と PDF の作成で、最後の 1 つは署名付き URLで説明しています。

エラーを処理する

CreateImage と CreatePDF は *Response を返します。Result を読む前に、Error を確認してください。

type Response struct {
	Result []byte
	Error  *ErrorResponse
}

type ErrorResponse struct {
	Code    string
	Message string
	Docs    string
}

API が 200 以外のステータスで応答すると、SDK はコード HTTP_ERROR を返します。CreateImage では、メッセージにステータスとレスポンスボディが入ります。レスポンスボディは、API が返す JSON のエラーオブジェクトです。CreatePDF では、メッセージにステータスだけが入ります。

SDK は、ほかにもいくつかのエラーを自分で作ります。

コード	意味
INVALID_FORMAT	形式が png、jpeg、webp のいずれでもない
JSON_ERROR	SDK がリクエストボディをエンコードできなかった
REQUEST_ERROR	SDK がリクエストを組み立てられなかった
HTTP_ERROR	API が応答する前にリクエストが失敗した、または API が 200 以外のステータスで応答した
READ_ERROR	SDK がレスポンスボディを読み取れなかった
TIMEOUT_ERROR	動画のストリームが切れ、SDK が動画をもう一度読み取れなかった

GenerateImageSignedURL は、形式がサポートされていない場合に error を返します。

オプション

オプションは、API キーのあとに NewClient へ渡します。

client := bannerify.NewClient(
	os.Getenv("BANNERIFY_API_KEY"),
	bannerify.WithTimeout(30*time.Second),
)

オプション	既定値	説明
WithBaseURL(url)	https://api.bannerify.co/v1	API のベース URL
WithTimeout(duration)	60 秒	リクエストのタイムアウト
WithHTTPClient(client)	タイムアウト 60 秒のクライアント	自分の *http.Client。既定のクライアントを置き換えるため、タイムアウトはそのクライアントに設定してください