optidash

README

Optidash is a modern, AI-powered image optimization and processing API.
We will drastically speed-up your websites and save you money on bandwidth and storage.

---

The official Go integration for the Optidash API.

---

Documentation

See the Optidash API docs.

Installation

$ go get github.com/optidash-ai/optidash-go

Quick examples

Optidash API enables you to provide your images for optimization and processing in two ways - by uploading them directly to the API (Image Upload) or by providing a publicly available image URL (Image Fetch).

You may also choose your preferred response method on a per-request basis. By default, the Optidash API will return a JSON response with rich metadata pertaining to input and output images. Alternatively, you can use binary responses. When enabled, the API will respond with a full binary representation of the resulting (output) image. This Go integration exposes two convenience methods for interacting with binary responses: .toFile() and .toBuffer().

Image upload

Here is a quick example of uploading a local file for processing. It calls .toJSON() at a final step and instructs the API to return a JSON response.

package main

import (
    "fmt"
    "github.com/optidash-ai/optidash-go"
)

func main() {
    // Pass your Optidash API Key to the constructor
    opti, err := optidash.NewClient("your-api-key")

    if err != nil {
        panic(err)
    }

    // Upload an image from disk, resize it to 100 x 75,
    // automatically enhance, and adjust sharpness parameter.
    meta, err := opti.
        Upload("path/to/input.jpg").
        Optimize(optidash.P{
            "compression": "medium"
        }).
        Resize(optidash.P{
            "width": 100,
            "height": 75
        }).
        Auto(optidash.P{
            "enhance": true
        }).
        Adjust(optidash.P{
            "unsharp": 10
        }).
        ToJSON()

    if err != nil {
        panic(err)
    }

    // You'll find the full JSON metadata within the `meta` variable
}

Image fetch

If you already have your source visuals publicly available online, we recommend using Image Fetch by default. That way you only have to send a JSON payload containing image URL and processing steps. This method is also much faster than uploading a full binary representation of the image.

package main

import (
    "fmt"
    "github.com/optidash-ai/optidash-go"
)

func main() {
    // Pass your Optidash API Key to the constructor
    opti, err := optidash.NewClient("your-api-key")

    if err != nil {
        panic(err)
    }

    // Provide a publicly available image URL with `fetch()` method,
    // apply Gaussian blur using highly optimized PNG as the output format.
    // We'll also use `toFile()` method and stream the output image to disk
    meta, err := opti.
        Fetch("https://www.website.com/image.jpg").
        Optimize(optidash.P{
            "compression": "medium"
        }).
        Filter(optidash.P{
            "blur": optidash.P{
                "mode": "gaussian",
                "value": 10
            }
        }).
        Output(optidash.P{
            "format": "png"
        }).
        ToFile("path/to/output.png")

    if err != nil {
        panic(err)
    }

    // You'll find the full JSON metadata within the `meta` variable
}

License

This software is distributed under the MIT License. See the LICENSE file for more information.

Documentation

Index

• Variables
• type Client
  • func NewClient(key string) (*Client, error)
  • func (c *Client) Fetch(url string) *Request
  • func (c *Client) Upload(input interface{}) *Request
• type OptidashError
  • func (c *OptidashError) Error() string
• type P
• type Request
  • func (r *Request) Adjust(data P) *Request
  • func (r *Request) Auto(data P) *Request
  • func (r *Request) Border(data P) *Request
  • func (r *Request) CDN(data P) *Request
  • func (r *Request) Context(ctx context.Context) *Request
  • func (r *Request) CopyTo(input io.Writer) (*fastjson.Value, error)
  • func (r *Request) Crop(data P) *Request
  • func (r *Request) Flip(data P) *Request
  • func (r *Request) HTTPClient(client *http.Client) *Request
  • func (r *Request) Mask(data P) *Request
  • func (r *Request) Optimize(data P) *Request
  • func (r *Request) Output(data P) *Request
  • func (r *Request) Padding(data P) *Request
  • func (r *Request) Resize(data P) *Request
  • func (r *Request) Scale(data P) *Request
  • func (r *Request) Store(data P) *Request
  • func (r *Request) Stylize(data P) *Request
  • func (r *Request) ToFile(input string, perm os.FileMode) (*fastjson.Value, error)
  • func (r *Request) ToJSON() (*fastjson.Value, error)
  • func (r *Request) ToReader() (*fastjson.Value, io.ReadCloser, error)
  • func (r *Request) Watermark(data P) *Request
  • func (r *Request) Webhook(data P) *Request

Variables

var (
	ErrInvalidSourceType = errors.New("optidash: Invalid request source type")
	ErrBinaryWebhook     = errors.New("optidash: Webhooks are not supported when using binary responses")
	ErrBinaryStorage     = errors.New("optidash: External storage is not supported when using binary responses")
	ErrNoSuccess         = errors.New("optidash: Success is missing in the response")
)

In-code validation and other frequent error cases.

Types

type Client

type Client struct {
	Key    string
	Client *http.Client
}

Client is the Optidash HTTP API client

func NewClient

func NewClient(key string) (*Client, error)

NewClient returns a new client using the given config. The *Config has to be generated using the NewConfig() function.

func (*Client) Fetch

func (c *Client) Fetch(url string) *Request

Fetch accepts a URL to a resource which the API should download. Returns a new API request builder.

func (*Client) Upload

func (c *Client) Upload(input interface{}) *Request

Upload accepts either a io.Reader (a stream) or a string (a file to read). Returns a new API request builder.

type OptidashError

type OptidashError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

OptidashError is an error returned by the Optidash API.

func (*OptidashError) Error

func (c *OptidashError) Error() string

Error implements the error interface.

type P

type P map[string]interface{}

P is a short name for all hashes passed to the Optidash API.

type Request

type Request struct {
	// contains filtered or unexported fields
}

Request is a generator that allows creation of Optidash API requests.

func (*Request) Adjust

func (r *Request) Adjust(data P) *Request

Adjust adds an visual parameters adjustment to the transformation flow. Check out Optidash docs for more details.

func (*Request) Auto

func (r *Request) Auto(data P) *Request

Auto adds an automatic image enhancement step to the transformation flow. Check out Optidash docs for more details.

func (*Request) Border

func (r *Request) Border(data P) *Request

Border adds adding a border to the image to the transformation flow. Check out Optidash docs for more details.

func (*Request) CDN

func (r *Request) CDN(data P) *Request

CDN configures CDN settings of the platform. Check out Optidash docs for more details.

func (*Request) Context

func (r *Request) Context(ctx context.Context) *Request

Context sets the context of the HTTP request.

func (*Request) CopyTo

func (r *Request) CopyTo(input io.Writer) (*fastjson.Value, error)

CopyTo executes a request, waits for the results and copies it into the passed io.Writer. It returns 2 variables:

• meta map containing the result information
• error that should be nil if everything succeeded

Due to the fact that CopyTo performs a binary request, using Webhook and Store is forbidden.

func (*Request) Crop

func (r *Request) Crop(data P) *Request

Crop adds an image cropping step to the transformation flow. Check out Optidash docs for more details.

func (*Request) Flip

func (r *Request) Flip(data P) *Request

Flip adds an image flipping step to the transformation flow. Check out Optidash docs for more details.

func (*Request) HTTPClient

func (r *Request) HTTPClient(client *http.Client) *Request

HTTPClient replaces the client used to execute the request.

func (*Request) Mask

func (r *Request) Mask(data P) *Request

Mask adds application of an elliptical mask to the transformation flow. Check out Optidash docs for more details.

func (*Request) Optimize

func (r *Request) Optimize(data P) *Request

Optimize adds an image optimization step to the transformation flow. Check out Optidash docs for more details.

func (*Request) Output

func (r *Request) Output(data P) *Request

Output sets the output format and encoding. Check out Optidash docs for more details.

func (*Request) Padding

func (r *Request) Padding(data P) *Request

Padding adds an image padding step to the transformation flow. Check out Optidash docs for more details.

func (*Request) Resize

func (r *Request) Resize(data P) *Request

Resize adds an image resizing step to the transformation flow. Check out Optidash docs for more details.

func (*Request) Scale

func (r *Request) Scale(data P) *Request

Scale adds an image scaling step to the transformation flow. Check out Optidash docs for more details.

func (*Request) Store

func (r *Request) Store(data P) *Request

Store specifies where the image should be stored after transformations. Check out Optidash docs for more details.

func (*Request) Stylize

func (r *Request) Stylize(data P) *Request

Stylize adds filter application to the transformation flow. Check out Optidash docs for more details.

func (*Request) ToFile

func (r *Request) ToFile(input string, perm os.FileMode) (*fastjson.Value, error)

ToFile executes a request, waits for the results and saves them into a file created on given path. If a file does not exist, it creates one with the passed `perm` file permissions. It returns 2 variables:

• meta map containing the result information
• error that should be nil if everything succeeded

Due to the fact that ToFile performs a binary request, using Webhook and Store is forbidden.

func (*Request) ToJSON

func (r *Request) ToJSON() (*fastjson.Value, error)

ToJSON runs the request and returns a fastjson.Value with a result from the API.

func (*Request) ToReader

func (r *Request) ToReader() (*fastjson.Value, io.ReadCloser, error)

ToReader executes the request, waits for the result and returns a set of 3 variables:

• meta map containing the result you would normally get in the body
• io.ReadCloser containing the resulting file
• error that should be nil if everything succeeded

Due to the fact that ToReader performs a binary request, using Webhook and Store is forbidden.

func (*Request) Watermark

func (r *Request) Watermark(data P) *Request

Watermark adds a watermark application to the transformation flow. Check out Optidash docs for more details.

func (*Request) Webhook

func (r *Request) Webhook(data P) *Request

Webhook sets a webhook as a response delivery method. Check out Optidash docs for more details.