videoupscaler

README

VideoUpscaler Go SDK (videoupscaler-go)

Official, zero-dependency Go client SDK for the AI Video Upscaler REST API. Upscale and enhance videos to 1080p, 2K, and 4K Ultra HD directly from Go services, media pipelines, worker queues, and CLI tools.

Whether you are building an automated 4K Video Upscaler microservice, running a high-throughput Batch Video Upscaler worker pool, or chaining enhancement stages with the AI Video Denoiser, 60fps AI Frame Interpolation, and AI Video Stabilizer, videoupscaler-go provides a clean, context-aware, idiomatic Go interface.

---

Features

• Zero External Dependencies: Built strictly on the Go 1.21+ standard library (net/http, context, encoding/json).
• 4K AI Super-Resolution: Upscale .mp4, .mov, and .webm footage to 1080p, 2k, or 4k via the 4K Video Upscaler engine.
• Multi-Stage AI Enhancement: Combine super-resolution with AI Video Denoiser, 60fps AI Frame Interpolation, AI Video Stabilizer, deinterlacing, deflickering, face restoration, and HDR output (hdr10, hlg).
• Built-in Long Polling & Idempotency: Automatic UUIDv4 Idempotency-Key generation on POST /upscale and server-side long-polling (?wait=45) in WaitForCompletion to minimize network overhead.
• Concurrency-Ready: Designed for goroutine worker pools and Batch Video Upscaler workflows.

---

Installation

Requires Go 1.21 or newer:

go get github.com/arkyu2077/videoupscaler-go@v0.1.0

Import the package in your Go code:

import "github.com/arkyu2077/videoupscaler-go"

---

Authentication

1. Sign in to VideoUpscaler and open Settings → API Keys.
2. Create an API key (vu_live_...) and export it in your environment:

export VIDEOUPSCALER_API_KEY="vu_live_..."

For full endpoint specifications, webhook payload schemas, and rate limits, see the API & Workflow Documentation.

---

Quickstart: Upscale a Video to 4K

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/arkyu2077/videoupscaler-go"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Minute)
	defer cancel()

	client := videoupscaler.NewClient(os.Getenv("VIDEOUPSCALER_API_KEY"))

	// 1. Check account credit balance
	account, err := client.GetAccount(ctx)
	if err != nil {
		log.Fatalf("get account failed: %v", err)
	}
	fmt.Printf("Available credits: %.1f (%.1f credits/sec)\n", account.Credits, account.CreditsPerSecond)

	// 2. Submit a 4K upscaling + enhancement task
	task, err := client.Upscale(ctx, videoupscaler.UpscaleRequest{
		VideoURL:   "https://cdn.example.com/archive/clip-720p.mp4",
		Resolution: videoupscaler.Resolution4K,
		Ops: &videoupscaler.UpscaleOps{
			Engine:        "flashvsr",
			Denoise:       0.4,
			Stabilize:     true,
			FPSMultiplier: 2, // 60fps AI frame interpolation
		},
	})
	if err != nil {
		log.Fatalf("submit upscale failed: %v", err)
	}
	fmt.Printf("Submitted task %s (status: %s)\n", task.ID, task.Status)

	// 3. Wait for completion using built-in long-polling
	completed, err := client.WaitForCompletion(ctx, task.ID)
	if err != nil {
		log.Fatalf("upscale failed: %v", err)
	}
	fmt.Printf("4K Output Ready: %s\n", completed.OutputURL)
}

---

Concurrent Batch 4K Upscaling Example

Go's concurrency primitives pair naturally with the Batch Video Upscaler API. Below is a worker-bounded batch pipeline that upscales multiple videos to 4K concurrently:

package main

import (
	"context"
	"fmt"
	"os"
	"sync"

	"github.com/arkyu2077/videoupscaler-go"
)

func upscaleBatch(ctx context.Context, urls []string, concurrency int) {
	client := videoupscaler.NewClient(os.Getenv("VIDEOUPSCALER_API_KEY"))
	sem := make(chan struct{}, concurrency)
	var wg sync.WaitGroup

	for _, videoURL := range urls {
		wg.Add(1)
		go func(src string) {
			defer wg.Done()
			sem <- struct{}{}
			defer func() { <-sem }()

			task, err := client.Upscale(ctx, videoupscaler.UpscaleRequest{
				VideoURL:   src,
				Resolution: videoupscaler.Resolution4K,
			})
			if err != nil {
				fmt.Printf("[FAIL] %s: %v\n", src, err)
				return
			}

			done, err := client.WaitForCompletion(ctx, task.ID)
			if err != nil {
				fmt.Printf("[FAIL] %s (task %s): %v\n", src, task.ID, err)
				return
			}
			fmt.Printf("[DONE] %s -> %s\n", src, done.OutputURL)
		}(videoURL)
	}

	wg.Wait()
}

---

API Overview

Method	Description	REST Endpoint
NewClient(apiKey, opts...)	Creates a configured *Client instance	—
client.Upscale(ctx, req)	Submits a video for 1080p, 2K, or 4K AI upscaling	POST /api/v1/upscale
client.GetTask(ctx, taskID, waitSec)	Gets task status with optional server long-polling (0–45s)	GET /api/v1/tasks/{id}
client.WaitForCompletion(ctx, taskID)	Polls until completed or failed	GET /api/v1/tasks/{id}?wait=45
client.ListTasks(ctx, page, limit)	Lists recent upscaling tasks (paginated)	GET /api/v1/tasks
client.GetAccount(ctx)	Returns remaining credit balance and pricing rate	GET /api/v1/account

---

Official Ecosystem & Integrations

Alongside the Go SDK, VideoUpscaler offers official packages and no-code connectors across the ecosystem:

• Web Platform: AI Video Upscaler
  • 4K Video Upscaler — Upscale low-res footage to crisp 1080p, 2K, and 4K.
  • Batch Video Upscaler — Process entire folders and multi-clip queues in parallel.
  • AI Video Denoiser — Remove low-light grain, sensor noise, and compression artifacts.
  • 60fps AI Frame Interpolation — Convert 24/30fps footage into silky-smooth 60fps or slow-motion.
  • AI Video Stabilizer — Eliminate handheld camera shake without heavy cropping.
• Workflow & Automation Hub: n8n, Make, Zapier & MCP Integrations
• Developer Docs: API & Workflow Documentation
• npm Packages:
  • videoupscaler on npm — Node.js SDK & CLI
  • videoupscaler-mcp on npm — Model Context Protocol (MCP) server for Claude Desktop, Cursor, and AI agents
  • n8n-nodes-videoupscaler on npm — Official community node for n8n workflow automation

---

License

Released under the MIT License.

Documentation

Overview

Package videoupscaler provides the official Go client SDK for the VideoUpscaler AI API (https://videoupscaler.co).

VideoUpscaler enables developers to upscale and enhance videos up to 1080p, 2K, and 4K resolution with AI-powered super-resolution, denoising, frame interpolation, and video stabilization.

Key Capabilities & Documentation

• AI Video Upscaler Platform: https://videoupscaler.co
• 4K Video Upscaler (1080p, 2K & 4K AI Super-Resolution): https://videoupscaler.co/4k-video-upscaler
• Batch Video Upscaler (Concurrent Multi-Clip Pipelines): https://videoupscaler.co/batch-video-upscaler
• Workflow Integrations (n8n, Make, Zapier & MCP): https://videoupscaler.co/integrations
• API & Workflow Documentation: https://videoupscaler.co/docs/workflows

Quickstart

client := videoupscaler.NewClient(os.Getenv("VIDEOUPSCALER_API_KEY"))
task, err := client.Upscale(ctx, videoupscaler.UpscaleRequest{
	VideoURL:   "https://example.com/input.mp4",
	Resolution: videoupscaler.Resolution4K,
})
if err != nil {
	log.Fatal(err)
}
completed, err := client.WaitForCompletion(ctx, task.ID)
if err != nil {
	log.Fatal(err)
}
fmt.Println("4K Video URL:", completed.OutputURL)

Index

• Constants
• type APIError
  • func (e *APIError) Error() string
• type Account
• type Client
  • func NewClient(apiKey string, opts ...Option) *Client
  • func (c *Client) GetAccount(ctx context.Context) (*Account, error)
  • func (c *Client) GetTask(ctx context.Context, taskID string, waitSeconds int) (*Task, error)
  • func (c *Client) ListTasks(ctx context.Context, page, limit int) (*TaskList, error)
  • func (c *Client) Upscale(ctx context.Context, req UpscaleRequest) (*Task, error)
  • func (c *Client) WaitForCompletion(ctx context.Context, taskID string) (*Task, error)
• type Option
  • func WithBaseURL(baseURL string) Option
  • func WithHTTPClient(httpClient *http.Client) Option
  • func WithPollInterval(d time.Duration) Option
  • func WithUserAgent(ua string) Option
  • func WithWaitChunkSeconds(seconds int) Option
• type Task
  • func (t *Task) IsTerminal() bool
• type TaskList
• type UpscaleOps
• type UpscaleRequest

Constants

const (
	// DefaultBaseURL is the default endpoint for the VideoUpscaler v1 REST API.
	DefaultBaseURL = "https://videoupscaler.co/api/v1"

	// DefaultPollInterval is the default interval between polling requests in WaitForCompletion
	// when long-polling returns immediately.
	DefaultPollInterval = 2 * time.Second

	// DefaultWaitChunkSeconds is the default server-side long-poll duration per GetTask call during WaitForCompletion.
	DefaultWaitChunkSeconds = 45

	// Resolution1080p upscales video to Full HD (1920x1080).
	Resolution1080p = "1080p"
	// Resolution2K upscales video to 2K QHD (2560x1440).
	Resolution2K = "2k"
	// Resolution4K upscales video to 4K Ultra HD (3840x2160).
	Resolution4K = "4k"

	// StatusQueued indicates the task is waiting for a GPU worker.
	StatusQueued = "queued"
	// StatusProcessing indicates the task is actively being processed.
	StatusProcessing = "processing"
	// StatusCompleted indicates the task finished and OutputURL is ready.
	StatusCompleted = "completed"
	// StatusFailed indicates the task failed; check Task.Error for details.
	StatusFailed = "failed"
)

Types

type APIError

type APIError struct {
	StatusCode int
	Code       string
	Message    string
}

APIError is returned when the VideoUpscaler API responds with a non-2xx HTTP status.

func (*APIError) Error

func (e *APIError) Error() string

type Account

type Account struct {
	Credits          float64 `json:"credits"`
	CreditsPerSecond float64 `json:"credits_per_second"`
	Plan             string  `json:"plan,omitempty"`
}

Account represents the current user's credit balance and pricing tier.

type Client

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

Client is an idiomatic, zero-dependency HTTP client for the VideoUpscaler AI API (https://videoupscaler.co).

func NewClient

func NewClient(apiKey string, opts ...Option) *Client

NewClient creates a new VideoUpscaler API client. Obtain an API key from https://videoupscaler.co/settings/apikeys.

func (*Client) GetAccount

func (c *Client) GetAccount(ctx context.Context) (*Account, error)

GetAccount retrieves the credit balance and per-second rate for the authenticated account (GET /account).

func (*Client) GetTask

func (c *Client) GetTask(ctx context.Context, taskID string, waitSeconds int) (*Task, error)

GetTask retrieves the current status of a task by ID (GET /tasks/{id}). When waitSeconds > 0 (up to 45), the server long-polls until the task completes or the timeout expires.

func (*Client) ListTasks

func (c *Client) ListTasks(ctx context.Context, page, limit int) (*TaskList, error)

ListTasks returns a paginated list of recent upscaling tasks (GET /tasks?page=&limit=).

func (*Client) Upscale

func (c *Client) Upscale(ctx context.Context, req UpscaleRequest) (*Task, error)

Upscale submits a new video upscaling job (POST /upscale). If req.Resolution is empty, it defaults to "4k" (https://videoupscaler.co/4k-video-upscaler). If req.IdempotencyKey is empty, a random UUIDv4 key is generated automatically.

func (*Client) WaitForCompletion

func (c *Client) WaitForCompletion(ctx context.Context, taskID string) (*Task, error)

WaitForCompletion polls GetTask until the task reaches StatusCompleted or StatusFailed, or until ctx is canceled. If the task fails, an error is returned alongside the failed *Task.

type Option

type Option func(*Client)

Option configures a Client instance.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the default API base URL (https://videoupscaler.co/api/v1).

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient provides a custom *http.Client for API requests.

func WithPollInterval

func WithPollInterval(d time.Duration) Option

WithPollInterval configures the delay between poll attempts in WaitForCompletion.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets a custom User-Agent header on outgoing requests.

func WithWaitChunkSeconds

func WithWaitChunkSeconds(seconds int) Option

WithWaitChunkSeconds configures the long-poll wait parameter (0-45 seconds) used by WaitForCompletion.

type Task

type Task struct {
	ID             string      `json:"id"`
	Status         string      `json:"status"`
	Resolution     string      `json:"resolution,omitempty"`
	VideoURL       string      `json:"video_url,omitempty"`
	OutputURL      string      `json:"output_url,omitempty"`
	CreditsUsed    float64     `json:"credits_used,omitempty"`
	DurationSec    float64     `json:"duration_seconds,omitempty"`
	Error          string      `json:"error,omitempty"`
	CreatedAt      string      `json:"created_at,omitempty"`
	CompletedAt    string      `json:"completed_at,omitempty"`
	Ops            *UpscaleOps `json:"ops,omitempty"`
	IdempotencyKey string      `json:"idempotency_key,omitempty"`
}

Task represents an asynchronous video upscaling job.

func (*Task) IsTerminal

func (t *Task) IsTerminal() bool

IsTerminal reports whether the task has reached a final state ("completed" or "failed").

type TaskList

type TaskList struct {
	Tasks []Task `json:"tasks"`
	Page  int    `json:"page,omitempty"`
	Limit int    `json:"limit,omitempty"`
	Total int    `json:"total,omitempty"`
}

TaskList contains a paginated list of tasks returned by ListTasks.

type UpscaleOps

type UpscaleOps struct {
	// Engine selects the AI model ("flashvsr", "real-esrgan", " anime"). Defaults to "flashvsr".
	Engine string `json:"engine,omitempty"`
	// Denoise strength from 0.0 to 1.0 (https://videoupscaler.co/denoise-video).
	Denoise float64 `json:"denoise,omitempty"`
	// Deinterlace removes interlacing artifacts from legacy footage.
	Deinterlace bool `json:"deinterlace,omitempty"`
	// Deflicker smooths temporal luminance flicker.
	Deflicker bool `json:"deflicker,omitempty"`
	// Stabilize applies AI motion stabilization (https://videoupscaler.co/stabilize-video).
	Stabilize bool `json:"stabilize,omitempty"`
	// FaceRestore enhances facial details during upscaling.
	FaceRestore bool `json:"faceRestore,omitempty"`
	// FPSMultiplier increases frame rate (e.g. 2 for 60fps interpolation: https://videoupscaler.co/frame-interpolation).
	FPSMultiplier int `json:"fpsMultiplier,omitempty"`
	// SlowMotion outputs interpolated frames as smooth slow-motion video.
	SlowMotion bool `json:"slowMotion,omitempty"`
	// HDR tone-mapping or PQ/HLG output mode ("none", "hdr10", "hlg").
	HDR string `json:"hdr,omitempty"`
}

UpscaleOps specifies optional AI video enhancement filters to run alongside upscaling. Learn more at https://videoupscaler.co/docs/workflows.

type UpscaleRequest

type UpscaleRequest struct {
	// VideoURL is the publicly accessible HTTP(S) URL of the source video (.mp4, .mov, .webm).
	VideoURL string `json:"video_url"`
	// Resolution is the target output resolution: "1080p", "2k", or "4k" (default "4k").
	Resolution string `json:"resolution"`
	// Ops configures optional AI enhancement stages (denoise, frame interpolation, stabilization, etc.).
	Ops *UpscaleOps `json:"ops,omitempty"`
	// WebhookURL is an optional HTTPS endpoint that receives a POST callback when the task finishes.
	WebhookURL string `json:"webhook_url,omitempty"`
	// IdempotencyKey prevents duplicate billing if a request is retried. Auto-generated if empty.
	IdempotencyKey string `json:"-"`
}

UpscaleRequest defines parameters for submitting a video upscaling job via POST /upscale.