Go SDK | Bannerify Docs

bannerify-go is the Bannerify client for Go. It takes a context.Context on each request and returns errors as values.

Install

go get github.com/bannerify/bannerify-go

Create a client

You need an API key. Create one on the API Keys page of the dashboard and keep it on the server.

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

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

Generate an image

Every Modification field except Name is a pointer. The examples build them with this helper:

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 is a []byte that holds the image.

Methods

Method	Returns	Use it to
`CreateImage`	`*Response`	Get the image bytes in `Result`
`CreatePDF`	`*Response`	Get a PDF in `Result`
`RenderVideo` (Beta)	`iter.Seq[RenderVideoEvent]`	Render a video and follow its progress
`RenderAndWaitVideo` (Beta)	`string` and `error`	Render a video and get its MP4 URL
`CreateVideo` (Beta)	`*CreatedVideo` and `error`	Start a video and get its id at once, without waiting
`GetVideo` (Beta)	`*Video` and `error`	Read the status and the MP4 URL of a video by its id
`WatchVideo` (Beta)	`iter.Seq[RenderVideoEvent]`	Follow the progress of a video again by its id
`GenerateImageSignedURL`	`string` and `error`	Build a link that renders when someone opens it

Render videos covers the video methods. The Go SDK has no method for stored images. Call Create stored image over REST.

Create images and PDFs covers the first two, and Signed URL covers the last one.

Handle errors

CreateImage and CreatePDF return a *Response. Check Error before you read Result.

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

type ErrorResponse struct {
	Code    string
	Message string
	Docs    string
}

When the API answers with a status other than 200, the SDK returns the code HTTP_ERROR. For CreateImage the message holds the status and the response body, which is the JSON error object from the API. For CreatePDF the message holds the status only.

The SDK creates a few other errors itself.

Code	Meaning
`INVALID_FORMAT`	The format is not `png`, `jpeg`, or `webp`
`JSON_ERROR`	The SDK could not encode the request body
`REQUEST_ERROR`	The SDK could not build the request
`HTTP_ERROR`	The request failed before the API answered, or the API answered with a status other than 200
`READ_ERROR`	The SDK could not read the response body
`TIMEOUT_ERROR`	A video stream dropped and the SDK could not read the video again

GenerateImageSignedURL returns an error when the format is not supported.

Options

Pass options to NewClient after the API key.

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

Option	Default	Description
`WithBaseURL(url)`	`https://api.bannerify.co/v1`	The API base URL
`WithTimeout(duration)`	60 seconds	Request timeout
`WithHTTPClient(client)`	A client with a 60 second timeout	Your own `*http.Client`. It replaces the default client, so set the timeout on it