# Go SDK

> Learn how to generate images and PDFs with the bannerify-go module.

Canonical: https://bannerify.co/docs/sdk/go/overview

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

## Install

```bash
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.

```go
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:

```go
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](https://bannerify.co/docs/sdk/go/apis/render-video) covers the video methods. The Go SDK has no method for stored images. Call [Create stored image](https://bannerify.co/docs/api-reference/endpoint/create-stored-image) over REST.

[Create images and PDFs](https://bannerify.co/docs/sdk/go/apis/create-image) covers the first two, and [Signed URL](https://bannerify.co/docs/sdk/go/apis/signed-url) covers the last one.

## Handle errors

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

```go
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.

```go
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 |

## Related

- [Previous: Signed URLs in PHP](https://bannerify.co/docs/sdk/php/apis/signed-url)
- [Next: Create images and PDFs in Go](https://bannerify.co/docs/sdk/go/apis/create-image)
- [Documentation index](https://bannerify.co/docs/llms.txt)