hitpaw-image-enhancer（hitpaw 图像增强器）

HitPaw Image & Video Enhancer Skill

A powerful OpenClaw skill that integrates HitPaw's state-of-the-art AI enhancement technology for both images and videos. Enhance, upscale, restore, and denoise with multiple AI models.

🎯 Features

Based on the official HitPaw API Documentation, this skill leverages industrial-grade AI models developed in-house by HitPaw's expert R&D team.

Core Strengths

• Quality: Industry-defining quality fit for professional use cases, from commercial photography to archival restoration
• Fidelity: Preserves the original details and identities in the source images, ensuring the output remains true to the input
• Efficiency: Optimized for low latency and high throughput, capable of processing distinct enhancement tasks at scale

📸 Image Enhancement

According to the Image API Introduction, our image processing services offer world-class capabilities designed to handle a wide variety of restoration scenarios:

Key Capabilities

• Upscale: Output high-resolution images from low-resolution input files using standard or high-fidelity models
• Face Recovery: Ensure high-quality facial details, offering both "Clear" (soft/beauty) and "Natural" (textured/realistic) restoration options
• Sharpen & Denoise: Bring images into focus by removing blur and sensor noise while preserving the original structure
• Generative Restoration: Leverage Diffusion technology to reconstruct details in severely degraded portraits or general images

Model Classes

The Image API offers two classes of AI models to suit different needs:

• Standard Models: Fast and efficient, prioritizing preserving original fidelity and details. Recommended for most professional and general restoration use cases
• Generative Models: Utilize Stable Diffusion to produce the highest quality outputs, capable of "imagining" missing details. Ideal for extremely low-quality inputs where traditional upscaling fails

Standard Models

As detailed in the Available Models documentation:

Generative Models

Powered by Stable Diffusion technology:

Technical Highlights:

• Generative models excel at texture generation and sharpening
• They can fill in missing details that traditional upscalers cannot recover
• Ideal for restoration tasks where source data is severely degraded

Example Image Use Cases

# General photo upscaling (landscape, architecture)
enhance-image -u landscape.jpg -m general_4x -o hd_landscape.jpg

# Portrait beautification (soft skin)
enhance-image -u selfie.jpg -m face_4x -o portrait_beautified.jpg

# Professional archival restoration (natural look)
enhance-image -u old_photo.png -m face_v2_2x -o restored.png --keep-exif

# Denoise grainy low-light photo
enhance-image -u night_photo.jpg -m sharpen_denoise_1x -o clean.jpg

# Generative reconstruction for severely degraded image
enhance-image -u blurry_face.jpg -m generative_portrait_2x -o ai_face.jpg

🎬 Video Enhancement

According to the Video API Introduction, our video processing services provide industrial-grade solutions for restoring and upscaling video content:

Key Capabilities

• Video Upscale: Convert SD or HD footage to 4K Ultra HD clarity using deep convolution and feature learning technologies
• Portrait Restoration: Specialized models to detect, stabilize, and enhance faces in video streams, removing motion blur and noise while maintaining identity
• General Restoration: A comprehensive solution based on GAN technology to de-noise, de-blur, and enhance details in general video content
• Generative Reconstruction: Utilizing Stable Diffusion for video to reconstruct textures and details in extremely low-quality footage

Core Pillars

• Temporal Stability: Unlike image-only models, our video engines ensure smooth transitions between frames, eliminating flickering and jitter
• Clarity: Recovering fine details and removing compression artifacts common in streaming or legacy media
• Performance: Optimized inference times to handle heavy video processing workloads efficiently

Model Classes

• Restoration & Upscale (Standard): Models like Ultra HD and General Restore focus on cleaning up the footage and increasing resolution without altering the fundamental content. They rely on pixel-perfect accuracy and temporal consistency
• Generative Video: Uses advanced logic-based reconstruction. Designed for "impossible" restoration tasks where the source video lacks sufficient data, generating realistic textures and details to fill the gaps

Available Video Models

From the Video Models Documentation:

Technical Highlights:

• Generates realistic textures and eliminates flickering via multi-frame SD architecture
• Handles heavy compression, high-ISO noise, and complex motion blur
• Maintains identity consistency across frames

Example Video Use Cases

# Convert old 720p footage to 4K
enhance-video -u old_clip.mp4 -m ultrahd_restore_2x -r 3840x2160 -o 4k_remastered.mp4

# Restore grainy, noisy home video
enhance-video -u home_movie.avi -m general_restore_2x -r 1920x1080 -o cleaned.mp4

# Beautify faces in vlog/interview
enhance-video -u interview.mp4 -m face_soft_2x -r 1920x1080 -o soft_faces.mp4

# Stabilize and restore old family footage with multiple faces
enhance-video -u family_reunion.mov -m portrait_restore_2x -r 1920x1080 -o restored.mp4

# Generative AI restoration for severely degraded source
enhance-video -u heavily_compressed.mp4 -m generative_1x -r 1920x1080 -o regenerated.mp4

🚀 Why Choose HitPaw API?

Industry-Leading Quality: Professional-grade output suitable for commercial photography, archival restoration, and broadcast-quality video remastering

Unparalleled Fidelity: Strictly retains original details and subject identity, ensuring outputs remain true to inputs

Comprehensive Model Catalog: 16 specialized models covering virtually every restoration scenario

Scalable Performance: Optimized for low-latency, high-throughput workloads

📊 Quick Reference

Image Model Selection Guide

Video Model Selection Guide

Installation

clawhub install hitpaw-image-enhancer

Configuration

Set your HitPaw API key:

export HITPAW_API_KEY="your_api_key_here"

Or create a .env file in your OpenClaw workspace:

HITPAW_API_KEY=your_api_key_here

Get your API key at: https://playground.hitpaw.com/

Test the API directly in the browser: HitPaw Playground →

📸 Examples & Gallery

Note: All screenshots below are from official HitPaw website (hitpaw.com), showcasing real enhancement results. Place additional examples in the images/ folder.

Image Enhancement Examples

General Upscale (2x/4x)

From official HitPaw documentation:

*Demonstrates general image enhancement and upscaling capabilities*

Use case: Landscape photos, architecture, general photography

Unblur / Motion Blur Removal

*Shows blur removal and sharpening effects*

Use case: Action shots, low-light photos, camera shake recovery

🎬 Video Enhancement Gallery

Video screenshots coming soon. Currently using placeholder references.

See images/README.md for screenshot guidelines and recommended sources.

📊 Model Comparison Examples

Face Enhancement: Clear vs Natural

• Face Clear Model: Soft skin, beautification style
• Face Natural Model: Preserves natural texture and pores

Generative vs Standard Models

• Standard models: Fast, preserves original details
• Generative models: Reconstructs missing details, ideal for severely degraded inputs

IMAGE COMMAND

Usage: enhance-image

Command Line Options

Available Image Models

Examples

# Simple 2x upscale with general model
enhance-image -u photo.jpg -o enhanced.jpg -m general_2x

# Face enhancement 4x
enhance-image -u portrait.jpg -m face_4x -o portrait_4x.jpg --keep-exif

# High fidelity with custom DPI
enhance-image -u old-photo.png -m high_fidelity_2x -dpi 300 -o hd.png

# Batch processing
for img in *.jpg; do
  enhance-image -u "$img" -o "upscaled/$img" -m general_4x
done

VIDEO COMMAND

Usage: enhance-video

⚠️ Important Notes

• Resolution is required (--resolution or -r). Must be in WIDTHxHEIGHT format (e.g., 1920x1080).
• Ensure target resolution does not exceed max output resolution (36 MP total pixels) per API limits.
• Video processing can take minutes to hours depending on length. Use --timeout to extend if needed.
• Input video must be at a publicly accessible URL (local files not directly supported).

Command Line Options

Available Video Models

Examples

# Upscale to 1080p using general_restore_2x
enhance-video -u input.mp4 -o output_1080p.mp4 -m general_restore_2x -r 1920x1080

# Upscale to 4K with specific original resolution
enhance-video -u clip.mov -o 4k.mov -m general_restore_4x -r 3840x2160 --original-resolution 1920x1080

# Denoise with portrait model
enhance-video -u portrait_video.avi -m portrait_restore_2x -r 1920x1080 -o clean_portrait.mp4

# Add color to B&W (if generative model supports)
enhance-video -u bw_vintage.mp4 -m generative_1x -r 1920x1080 -o colorized.mp4

Coin Consumption

Image Enhancement

• 2x/4x models: ~75 coins per image
• 1x models: ~50 coins per image
• Generative models: ~100+ coins per image

Video Enhancement

Coin costs depend on video length, model, and resolution. Approximate rates:

• Upscale models: ~200-400 coins per minute
• Restoration models: ~150-300 coins per minute

Always check current rates at: https://playground.hitpaw.com/

Error Handling

Common errors and solutions:

Error Codes

The API returns structured error codes. Always check both HTTP status and the error_code field.

General Errors

API-Specific Errors

Error Response Format

{
  "error_code": 110400000,
  "message": "api_key is not valid"
}

Rate Limiting

• The API implements rate limiting to ensure fair usage
• Error code 100429000 will be returned if you exceed the rate limit
• Implement exponential backoff in your retry logic

Best Practices

Polling for Job Status

• Poll the /api/task-status endpoint at reasonable intervals (recommended: every 5–10 seconds)
• Implement exponential backoff for failed requests
• Set a maximum number of polling attempts to avoid infinite loops
• Check status values: CONVERTING (keep polling), COMPLETED (success), ERROR (failed)

Error Handling

• Always check the HTTP status code AND error_code in the response
• Implement retry logic for transient errors (5xx errors)
• Do NOT retry 4xx client errors without first fixing the request
• Log error responses for debugging

Resource Limits

• Images: Max input resolution 70 MP (Enhancement/Denoise) / 34 MP (Generative); Max output 432 MP (Enhancement/Denoise)
• Videos: Max output 36 MP total pixels; Duration 0.5s – 1 hour
• Verify file extension validity before submitting

API Key Management

• Store API keys securely using environment variables
• Never commit API keys to version control
• Rotate API keys periodically

File URL Requirements

• Ensure image and video URLs are publicly accessible
• Use HTTPS URLs
• Use Pre-sign OSS Upload for unreliable URLs: https://developer.hitpaw.com/common/oss-presign-put-api

Technical Details

API Compatibility

This skill implements the official HitPaw API as documented:

• Base URL: https://api-base.hitpaw.com
• Image endpoint: POST /api/photo-enhancer
• Video endpoint: POST /api/video-enhancer
• Status endpoint: POST /api/task-status

Both endpoints return a job_id. Use the status endpoint to poll until COMPLETED, then download from res_url.

Polling Strategy

• Images: default poll every 5s, timeout 300s (5 min)
• Videos: default poll every 10s, timeout 600s (10 min)
• Implement exponential backoff when encountering 5xx errors or rate limit (429)

For longer videos, increase --timeout as needed (e.g., --timeout 3600 for 1 hour).

Resolution & Format Limits

Image Model Specs:

Video Model Specs:

Examples: 3840×2160 = 8.3 MP ✅, 7680×4320 = 33.2 MP ✅, 8192×4608 = 37.7 MP ❌

For videos, resolution is required. Choose based on your needs:

• Keep original size? Set resolution to original dimensions (use --original-resolution for better quality).
• Upscale? Multiply original width/height by factor (2x, 4x).
• Downscale? Rare but possible; just specify smaller dimensions.

Audio Preservation

By default, enhance-video keeps the audio track (--keep-audio, default true). Use --no-keep-audio to strip audio.

Support

• Image API Docs: https://developer.hitpaw.com/image/API-reference
• Video API Docs: https://developer.hitpaw.com/video/API-reference
• Playground: https://playground.hitpaw.com/
• Contact: support@hitpaw.com

This skill is an unofficial integration with HitPaw API. You must have a valid API key and comply with HitPaw's terms. The skill author is not responsible for any charges incurred.

License

MIT © HitPaw-Official