creatomate

README

Creatomate Go SDK

A Go SDK for the Creatomate API, providing 100% JSON-compatible output with the official Node.js package.

Installation

go get github.com/Lakeshore-Labs/creatomate-go

Features

• ✅ 100% JSON compatibility with the Node.js package
• ✅ Full element support (Video, Image, Text, Audio, Shapes, Compositions)
• ✅ Keyframe animations
• ✅ Text animations (Slide, Typewriter, Appear, etc.)
• ✅ Property expansion (Font, TextBackground)
• ✅ Automatic snake_case JSON field conversion
• ✅ Type-safe API with Go generics
• ✅ Context support for cancellation
• ✅ Comprehensive error handling

Quick Start

package main

import (
    "context"
    "fmt"
    "log"
    "time"
    
    creatomate "github.com/Lakeshore-Labs/creatomate-go"
    "github.com/Lakeshore-Labs/creatomate-go/elements"
    "github.com/Lakeshore-Labs/creatomate-go/properties"
)

func main() {
    // Create client
    client := creatomate.NewClient("your-api-key")
    
    // Create a simple video
    source := creatomate.NewSource(creatomate.SourceProperties{
        OutputFormat: properties.OutputFormatMP4,
        Width:        1920,
        Height:       1080,
        Duration:     10,
        Elements: []interface{}{
            elements.NewVideo(elements.VideoProperties{
                Source:   "https://example.com/video.mp4",
                Duration: "media",
            }),
        },
    })
    
    // Render
    ctx := context.Background()
    renders, err := client.Render(ctx, creatomate.RenderOptions{
        Source: source,
    }, 5*time.Minute)
    
    if err != nil {
        log.Fatal(err)
    }
    
    for _, render := range renders {
        fmt.Printf("Render completed: %s\n", render.URL)
    }
}

Examples

Text with Animations

font := creatomate.NewFont("Open Sans", 700)
font.Maximum = "10.4 vmin"

text := elements.NewText(elements.TextProperties{
    ElementProperties: elements.ElementProperties{
        Y:          "75%",
        Width:      "100%",
        Height:     "50%",
        Enter: creatomate.NewTextSlide(map[string]interface{}{
            "duration": 2,
            "easing":   "quadratic-out",
            "split":    "line",
        }),
    },
    Text:       "Hello Creatomate! 🔥",
    Font:       font,
    Background: creatomate.NewTextBackground("rgba(255,255,255,0.69)", "23%", "8%", "0%", "0%"),
    FillColor:  "#333333",
})

Keyframe Animations

shape := elements.NewShape(elements.ShapeProperties{
    ElementProperties: elements.ElementProperties{
        Width:  "50%",
        Height: "50%",
        XScale: []interface{}{
            creatomate.NewKeyframe("20%", 0),
            creatomate.NewKeyframeWithEasing("100%", 2, "elastic-out"),
        },
        ZRotation: []interface{}{
            creatomate.NewKeyframe(-90, 0),
            creatomate.NewKeyframeWithEasing(0, 2, "elastic-out"),
        },
    },
    FillColor: []interface{}{
        creatomate.NewKeyframe("#333333", 0),
        creatomate.NewKeyframe("#0079ff", 2),
    },
})

Compositions

composition := elements.NewComposition(elements.CompositionProperties{
    ElementProperties: elements.ElementProperties{
        Width: []interface{}{
            creatomate.NewKeyframe("100%", 1),
            creatomate.NewKeyframe("50%", 3),
        },
    },
    Elements: []interface{}{
        elements.NewImage(elements.ImageProperties{
            Source: "https://example.com/image.jpg",
        }),
        elements.NewText(elements.TextProperties{
            Text: "Grouped elements",
        }),
    },
})

API Reference

Client

client := creatomate.NewClient(apiKey)

// Render and wait for completion
renders, err := client.Render(ctx, options, timeout)

// Start render without waiting
renders, err := client.StartRender(ctx, options)

// Check render status
render, err := client.FetchRender(ctx, renderID)

Elements

• elements.NewVideo() - Video element
• elements.NewImage() - Image element
• elements.NewText() - Text element
• elements.NewAudio() - Audio element
• elements.NewShape() - Shape element
• elements.NewRectangle() - Rectangle shape
• elements.NewEllipse() - Ellipse shape
• elements.NewComposition() - Composition for grouping elements

Properties

All property types from the Node.js SDK are available:

• properties.OutputFormat - Output formats (MP4, GIF, PNG, JPG)
• properties.Fit - Content fitting modes
• properties.BlendMode - Layer blend modes
• properties.TextTransform - Text transformations
• properties.Easing - Animation easing functions
• And many more...

Testing

The package includes comprehensive tests that verify JSON output matches the Node.js package exactly:

cd test
go test -v ./...

JSON Compatibility

This package produces identical JSON output to the official Node.js package. All property names are automatically converted to snake_case, and special types like Font and TextBackground are expanded into their constituent properties to match the API expectations.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Overview

Package creatomate provides a Go SDK for the Creatomate API.

Creatomate is a video generation API that allows you to create videos programmatically. This SDK provides a type-safe interface to the Creatomate API with full support for all elements, animations, and properties.

Basic Usage

client := creatomate.NewClient("your-api-key")

source := creatomate.NewSource(creatomate.SourceProperties{
    OutputFormat: properties.OutputFormatMP4,
    Width:        1920,
    Height:       1080,
    Duration:     10,
    Elements: []interface{}{
        elements.NewVideo(elements.VideoProperties{
            Source: "https://example.com/video.mp4",
        }),
    },
})

renders, err := client.Render(context.Background(), creatomate.RenderOptions{
    Source: source,
}, 5*time.Minute)

JSON Compatibility

This package is designed to produce JSON output that is 100% compatible with the official Creatomate Node.js SDK. All property names are automatically converted to snake_case, and special types like Font and TextBackground are expanded into their constituent properties.

Elements

The package supports all Creatomate elements:

• Video
• Image
• Text
• Audio
• Shape (Rectangle, Ellipse)
• Composition

Each element type has its own properties and can be animated using keyframes or animation presets.

Animations

Animations can be applied to elements using:

• Enter animations (played when element appears)
• Exit animations (played when element disappears)
• Keyframe animations (custom property animations over time)
• Text-specific animations (typewriter, slide, reveal, etc.)

Error Handling

The SDK provides typed errors for all API error conditions:

• BadRequestError
• InvalidApiKeyError
• InsufficientCreditsError
• RateLimitExceededError
• ConnectionError
• TimeoutError

Index

• Constants
• func DebugJSON(name string, value interface{})
• type BadRequestError
  • func NewBadRequestError(hint string) *BadRequestError
• type Client
  • func NewClient(apiKey string) *Client
  • func (c *Client) FetchRender(ctx context.Context, id string) (*Render, error)
  • func (c *Client) Render(ctx context.Context, options RenderOptions, timeout time.Duration) ([]Render, error)
  • func (c *Client) StartRender(ctx context.Context, options RenderOptions) ([]Render, error)
• type ConnectionError
  • func NewConnectionError() *ConnectionError
• type CreatomateError
  • func NewCreatomateError(message string) *CreatomateError
  • func (e *CreatomateError) Error() string
• type Font
  • func NewFont(family string, weight int) *Font
  • func (f *Font) ToMap() map[string]interface{}
• type InsufficientCreditsError
  • func NewInsufficientCreditsError() *InsufficientCreditsError
• type InvalidApiKeyError
  • func NewInvalidApiKeyError() *InvalidApiKeyError
• type Keyframe
  • func NewKeyframe[T any](value T, time float64) *Keyframe[T]
  • func NewKeyframeWithEasing[T any](value T, time float64, easing properties.Easing) *Keyframe[T]
• type RateLimitExceededError
  • func NewRateLimitExceededError() *RateLimitExceededError
• type Render
• type RenderOptions
• type RenderOutputFormat
• type RenderStatus
• type Source
  • func NewSource(properties SourceProperties) *Source
  • func (s *Source) ToMap() map[string]interface{}
• type SourceProperties
• type TextBackground
  • func NewTextBackground(color string, xPadding, yPadding, borderRadius, alignThreshold interface{}) *TextBackground
  • func (tb *TextBackground) ToMap() map[string]interface{}
• type TextSlide
  • func NewTextSlide(config map[string]interface{}) *TextSlide
  • func (ts *TextSlide) ToMap() map[string]interface{}
• type TimeoutError
  • func NewTimeoutError() *TimeoutError
• type ValueOrKeyframes

Constants

const (
	ClientVersion = "1.0.0"
	BaseURL       = "https://api.creatomate.com/v1"
)

Functions

func DebugJSON

func DebugJSON(name string, value interface{})

DebugJSON prints a nicely formatted JSON representation of any value

Types

type BadRequestError

type BadRequestError struct {
	CreatomateError
}

func NewBadRequestError

func NewBadRequestError(hint string) *BadRequestError

type Client

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

func NewClient

func NewClient(apiKey string) *Client

func (*Client) FetchRender

func (c *Client) FetchRender(ctx context.Context, id string) (*Render, error)

FetchRender fetches the status of the render.

func (*Client) Render

func (c *Client) Render(ctx context.Context, options RenderOptions, timeout time.Duration) ([]Render, error)

Render starts a new render and awaits its completion.

func (*Client) StartRender

func (c *Client) StartRender(ctx context.Context, options RenderOptions) ([]Render, error)

StartRender starts a render, but doesn't wait for it to finish.

type ConnectionError

type ConnectionError struct {
	CreatomateError
}

func NewConnectionError

func NewConnectionError() *ConnectionError

type CreatomateError

type CreatomateError struct {
	Message string
}

func NewCreatomateError

func NewCreatomateError(message string) *CreatomateError

func (*CreatomateError) Error

func (e *CreatomateError) Error() string

type Font

type Font struct {
	Family  string      `json:"family"`
	Weight  *int        `json:"weight,omitempty"`
	Style   *string     `json:"style,omitempty"`
	Size    interface{} `json:"size,omitempty"`    // number or string
	Minimum interface{} `json:"minimum,omitempty"` // number or string
	Maximum interface{} `json:"maximum,omitempty"` // number or string
}

Font represents font properties that get expanded in JSON

func NewFont

func NewFont(family string, weight int) *Font

NewFont creates a new Font with family and weight

func (*Font) ToMap

func (f *Font) ToMap() map[string]interface{}

ToMap expands font properties for JSON serialization

type InsufficientCreditsError

type InsufficientCreditsError struct {
	CreatomateError
}

func NewInsufficientCreditsError

func NewInsufficientCreditsError() *InsufficientCreditsError

type InvalidApiKeyError

type InvalidApiKeyError struct {
	CreatomateError
}

func NewInvalidApiKeyError

func NewInvalidApiKeyError() *InvalidApiKeyError

type Keyframe

type Keyframe[T any] struct {
	Time   float64           `json:"time"`
	Value  T                 `json:"value"`
	Easing properties.Easing `json:"easing,omitempty"`
}

Keyframe represents an animation keyframe

func NewKeyframe

func NewKeyframe[T any](value T, time float64) *Keyframe[T]

NewKeyframe creates a new keyframe with time and value

func NewKeyframeWithEasing

func NewKeyframeWithEasing[T any](value T, time float64, easing properties.Easing) *Keyframe[T]

NewKeyframeWithEasing creates a new keyframe with time, value, and easing

type RateLimitExceededError

type RateLimitExceededError struct {
	CreatomateError
}

func NewRateLimitExceededError

func NewRateLimitExceededError() *RateLimitExceededError

type Render

type Render struct {
	ID            string                 `json:"id"`
	Status        RenderStatus           `json:"status"`
	ErrorMessage  string                 `json:"error_message,omitempty"`
	URL           string                 `json:"url"`
	SnapshotURL   string                 `json:"snapshot_url,omitempty"`
	TemplateID    string                 `json:"template_id,omitempty"`
	TemplateName  string                 `json:"template_name,omitempty"`
	TemplateTags  []string               `json:"template_tags,omitempty"`
	OutputFormat  string                 `json:"output_format"`
	RenderScale   float64                `json:"render_scale"`
	Width         int                    `json:"width,omitempty"`
	Height        int                    `json:"height,omitempty"`
	FrameRate     float64                `json:"frame_rate,omitempty"`
	Duration      float64                `json:"duration,omitempty"`
	FileSize      int64                  `json:"file_size,omitempty"`
	Modifications map[string]interface{} `json:"modifications,omitempty"`
	WebhookURL    string                 `json:"webhook_url,omitempty"`
	Metadata      string                 `json:"metadata,omitempty"`
}

type RenderOptions

type RenderOptions struct {
	OutputFormat  RenderOutputFormat     `json:"output_format,omitempty"`
	FrameRate     float64                `json:"frame_rate,omitempty"`
	RenderScale   float64                `json:"render_scale,omitempty"`
	MaxWidth      int                    `json:"max_width,omitempty"`
	MaxHeight     int                    `json:"max_height,omitempty"`
	TemplateID    string                 `json:"template_id,omitempty"`
	Tags          []string               `json:"tags,omitempty"`
	Source        interface{}            `json:"source,omitempty"` // Can be *Source or map[string]interface{}
	Modifications map[string]interface{} `json:"modifications,omitempty"`
	WebhookURL    string                 `json:"webhook_url,omitempty"`
	Metadata      string                 `json:"metadata,omitempty"`
}

type RenderOutputFormat

type RenderOutputFormat string

const (
	RenderOutputFormatJPG RenderOutputFormat = "jpg"
	RenderOutputFormatPNG RenderOutputFormat = "png"
	RenderOutputFormatGIF RenderOutputFormat = "gif"
	RenderOutputFormatMP4 RenderOutputFormat = "mp4"
)

type RenderStatus

type RenderStatus string

const (
	RenderStatusPlanned      RenderStatus = "planned"
	RenderStatusWaiting      RenderStatus = "waiting"
	RenderStatusTranscribing RenderStatus = "transcribing"
	RenderStatusRendering    RenderStatus = "rendering"
	RenderStatusSucceeded    RenderStatus = "succeeded"
	RenderStatusFailed       RenderStatus = "failed"
)

type Source

type Source struct {
	Properties SourceProperties
}

func NewSource

func NewSource(properties SourceProperties) *Source

func (*Source) ToMap

func (s *Source) ToMap() map[string]interface{}

type SourceProperties

type SourceProperties struct {
	// The output format of the render, which can be jpg, png, gif, or mp4.
	OutputFormat properties.OutputFormat `json:"output_format"`

	// Only for MP4 renders. Sets the constant rate factor (CRF) ranging from 17 to 51.
	CRF int `json:"crf,omitempty"`

	// Only for GIF renders. With 'best', the GIF generation takes much longer.
	GifQuality properties.GifQuality `json:"gif_quality,omitempty"`

	// Only for GIF renders. A number ranging from 0 to 200 indicating the compression level.
	GifCompression int `json:"gif_compression,omitempty"`

	// The width of the output in pixels.
	Width int `json:"width,omitempty"`

	// The height of the output in pixels.
	Height int `json:"height,omitempty"`

	// The frame rate of the rendered video.
	FrameRate float64 `json:"frame_rate,omitempty"`

	// The duration of the output in seconds.
	Duration float64 `json:"duration,omitempty"`

	// Only for GIF renders. Set to true to make the GIF repeat.
	Loop bool `json:"loop,omitempty"`

	// If a snapshot image is desired, specify the time in seconds.
	SnapshotTime float64 `json:"snapshot_time,omitempty"`

	// The style of the Emojis used in text elements.
	EmojiStyle properties.EmojiStyle `json:"emoji_style,omitempty"`

	// The background fill.
	Fill ValueOrKeyframes[*properties.Fill] `json:"fill,omitempty"`

	// The background fill color.
	FillColor ValueOrKeyframes[string] `json:"fill_color,omitempty"`

	// The fill method used: solid, linear, and radial.
	FillMode ValueOrKeyframes[string] `json:"fill_mode,omitempty"`

	// The start position of the gradient on the x-axis.
	FillX0 ValueOrKeyframes[interface{}] `json:"fill_x0,omitempty"`

	// The start position of the gradient on the y-axis.
	FillY0 ValueOrKeyframes[interface{}] `json:"fill_y0,omitempty"`

	// The end position of the gradient on the x-axis.
	FillX1 ValueOrKeyframes[interface{}] `json:"fill_x1,omitempty"`

	// The end position of the gradient on the y-axis.
	FillY1 ValueOrKeyframes[interface{}] `json:"fill_y1,omitempty"`

	// The radius of the radial gradient.
	FillRadius ValueOrKeyframes[interface{}] `json:"fill_radius,omitempty"`

	// Custom fonts array.
	Fonts []properties.FontDefinition `json:"fonts,omitempty"`

	// Elements that make up the render.
	Elements []interface{} `json:"elements,omitempty"`
}

type TextBackground

type TextBackground struct {
	Color          string      `json:"color"`
	XPadding       interface{} `json:"x_padding,omitempty"`       // number or string
	YPadding       interface{} `json:"y_padding,omitempty"`       // number or string
	BorderRadius   interface{} `json:"border_radius,omitempty"`   // number or string
	AlignThreshold interface{} `json:"align_threshold,omitempty"` // number or string
}

TextBackground represents text background properties that get expanded in JSON

func NewTextBackground

func NewTextBackground(color string, xPadding, yPadding, borderRadius, alignThreshold interface{}) *TextBackground

NewTextBackground creates a new TextBackground

func (*TextBackground) ToMap

func (tb *TextBackground) ToMap() map[string]interface{}

ToMap expands text background properties for JSON serialization

type TextSlide

type TextSlide struct {
	Duration         float64 `json:"duration,omitempty"`
	Easing           string  `json:"easing,omitempty"`
	Split            string  `json:"split,omitempty"`             // "letter", "word", "line"
	Scope            string  `json:"scope,omitempty"`             // "element", "text"
	BackgroundEffect string  `json:"background_effect,omitempty"` // "scaling-clip", etc.
}

TextSlide represents a text slide animation

func NewTextSlide

func NewTextSlide(config map[string]interface{}) *TextSlide

NewTextSlide creates a new text slide animation

func (*TextSlide) ToMap

func (ts *TextSlide) ToMap() map[string]interface{}

ToMap converts the text slide to a map for JSON serialization

type TimeoutError

type TimeoutError struct {
	CreatomateError
}

func NewTimeoutError

func NewTimeoutError() *TimeoutError

type ValueOrKeyframes

type ValueOrKeyframes[T any] interface{}