README
¶
Pixaven is a modern, GPU-powered image processing API.
We transform, enhance, adjust, crop, stylize, filter and watermark your images with blazing speed.
The official Go integration for the Pixaven API.
Documentation
See the Pixaven API docs.
Installation
$ go get github.com/pixaven/pixaven-go
Quick examples
Pixaven API enables you to provide your images for 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 Pixaven 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/pixaven/pixaven-go"
)
func main() {
// Pass your Pixaven API Key to the constructor
pix, err := pixaven.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 := pix.
Upload("path/to/input.jpg").
Resize(pixaven.P{
"width": 100,
"height": 75
}).
Auto(pixaven.P{
"enhance": true
}).
Adjust(pixaven.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/pixaven/pixaven-go"
)
func main() {
// Pass your Pixaven API Key to the constructor
pix, err := pixaven.NewClient("your-api-key")
if err != nil {
panic(err)
}
// Provide a publicly available image URL with `fetch()` method,
// apply Gaussian blur using PNG as the output format.
// We'll also use `toFile()` method and stream the output image to disk
meta, err := pix.
Fetch("https://www.website.com/image.jpg").
Filter(pixaven.P{
"blur": pixaven.P{
"mode": "gaussian",
"value": 10
}
}).
Output(pixaven.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
- type P
- type PixavenError
- 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) 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
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidSourceType = errors.New("pixaven: Invalid request source type") ErrBinaryWebhook = errors.New("pixaven: Webhooks are not supported when using binary responses") ErrBinaryStorage = errors.New("pixaven: External storage is not supported when using binary responses") ErrNoSuccess = errors.New("pixaven: Success is missing in the response") )
In-code validation and other frequent error cases.
Functions ¶
This section is empty.
Types ¶
type Client ¶
Client is the Pixaven HTTP API client
func NewClient ¶
NewClient returns a new client using the given config. The *Config has to be generated using the NewConfig() function.
type PixavenError ¶
PixavenError is an error returned by the Pixaven API.
func (*PixavenError) Error ¶
func (c *PixavenError) Error() string
Error implements the error interface.
type Request ¶
type Request struct {
// contains filtered or unexported fields
}
Request is a generator that allows creation of Pixaven API requests.
func (*Request) Adjust ¶
Adjust adds an visual parameters adjustment to the transformation flow. Check out Pixaven docs for more details.
func (*Request) Auto ¶
Auto adds an automatic image enhancement step to the transformation flow. Check out Pixaven docs for more details.
func (*Request) Border ¶
Border adds adding a border to the image to the transformation flow. Check out Pixaven docs for more details.
func (*Request) CDN ¶
CDN configures CDN settings of the platform. Check out Pixaven docs for more details.
func (*Request) CopyTo ¶
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 ¶
Crop adds an image cropping step to the transformation flow. Check out Pixaven docs for more details.
func (*Request) Flip ¶
Flip adds an image flipping step to the transformation flow. Check out Pixaven docs for more details.
func (*Request) HTTPClient ¶
HTTPClient replaces the client used to execute the request.
func (*Request) Mask ¶
Mask adds application of an elliptical mask to the transformation flow. Check out Pixaven docs for more details.
func (*Request) Output ¶
Output sets the output format and encoding. Check out Pixaven docs for more details.
func (*Request) Padding ¶
Padding adds an image padding step to the transformation flow. Check out Pixaven docs for more details.
func (*Request) Resize ¶
Resize adds an image resizing step to the transformation flow. Check out Pixaven docs for more details.
func (*Request) Scale ¶
Scale adds an image scaling step to the transformation flow. Check out Pixaven docs for more details.
func (*Request) Store ¶
Store specifies where the image should be stored after transformations. Check out Pixaven docs for more details.
func (*Request) Stylize ¶
Stylize adds filter application to the transformation flow. Check out Pixaven docs for more details.
func (*Request) ToFile ¶
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 ¶
ToJSON runs the request and returns a fastjson.Value with a result from the API.
func (*Request) ToReader ¶
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.
Source Files