Hitpaw Image Enhancer

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

📸 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

Model Classes

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

#### Standard Models

As detailed in the Available Models documentation:

| Model | Multiplier | Description | Best For | |-------|------------|-------------|----------| | general_2x / general_4x | 2x / 4x | General Enhance Model | General photos, landscapes | | face_2x / face_4x | 2x / 4x | Portrait Model (Clear) | Soft/beauty style portrait enhancement | | face_v2_2x / face_v2_4x | 2x / 4x | Portrait Model (Natural) | Natural/realistic portrait enhancement | | high_fidelity_2x / high_fidelity_4x | 2x / 4x | High Fidelity Model | Professional photography, conservatively upscaling high-quality sources | | sharpen_denoise_1x | 1x | Sharp Denoise Model | Aggressive denoising with sharpening | | detail_denoise_1x | 1x | Detail Denoise Model | Gentle denoising with texture preservation |

#### Generative Models

Powered by Stable Diffusion technology:

| Model | Multiplier | Description | Best For | |-------|------------|-------------|----------| | generative_portrait_1x/2x/4x | 1x/2x/4x | Generative Portrait Model | Extremely low-quality portraits, "re-imagines" details | | generative_1x/2x/4x | 1x/2x/4x | Generative Enhance Model | Heavily compressed or very low-resolution general images |

Technical Highlights:

#### 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

Core Pillars

Model Classes

#### Available Video Models

From the Video Models Documentation:

| Model | Description | Use Case | |-------|-------------|----------| | ultrahd_restore_2x | Ultra HD Model | High-definition upscale; natural-looking 1080p→4K | | general_restore_1x / 2x / 4x | General Restore Model | General video restoration, de-noising, de-blurring | | portrait_restore_1x / 2x | Portrait Restore Model | Multi-face restoration with temporal stability | | face_soft_2x | Video Face Soft Model | Facial beautification with consistent appearance | | generative_1x | Generative Video Model | Extreme restoration of heavily degraded footage |

Technical Highlights:

#### 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

| Scenario | Recommended Model | |----------|-------------------| | General photo upscale | general_2x or general_4x | | Portrait beautification | face_2x or face_4x | | Portrait natural look | face_v2_2x or face_v2_4x | | Professional archival | high_fidelity_2x / high_fidelity_4x | | Grainy low-light | sharpen_denoise_1x | | Subtle denoise | detail_denoise_1x | | Severely degraded | generative_portrait_* or generative_* |

Video Model Selection Guide

| Scenario | Recommended Model | |----------|-------------------| | SD → 4K upscale | ultrahd_restore_2x | | General cleanup | general_restore_2x | | Interview/vlog beautification | face_soft_2x | | Old home movies (multiple faces) | portrait_restore_2x | | Severely compressed/ degraded | generative_1x |

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:

| Before | After | |--------|-------| | !Before | !After |

*Demonstrates general image enhancement and upscaling capabilities*

Use case: Landscape photos, architecture, general photography

#### Unblur / Motion Blur Removal

| Before | After | |--------|-------| | !Blurry | !Sharp |

*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.

| Scenario | Original Frame | Enhanced Frame | |----------|----------------|----------------| | General Upscale (1080p → 4K) | !Original | !Enhanced | | Portrait Restoration | !Before | !After | | Denoise & Cleanup | !Noisy | !Clean |

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

📊 Model Comparison Examples

Face Enhancement: Clear vs Natural

| Clear (Soft/Beauty) | Natural (Realistic) | |---------------------|---------------------| | !Face Clear | !Face Natural |

Generative vs Standard Models

| Standard (general_4x) | Generative (generative_portrait_2x) | |-----------------------|------------------------------------| | !Standard | !Generative |

IMAGE COMMAND

Usage: enhance-image

Command Line Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | --url, -u | string | required | URL of the image to enhance | | --output, -o | string | output.jpg | Output file path | | --model, -m | string | general_2x | Image model (see below) | | --extension, -e | string | .jpg | Output extension (.jpg, .png, .webp) | | --dpi | number | original | Target DPI for metadata | | --keep-exif | boolean | false | Preserve EXIF data from original | | --poll-interval | number | 5 | Polling interval in seconds | | --timeout | number | 300 | Maximum wait time in seconds |

#### Available Image Models

| Model | Multiplier | Best For | DPI Support | |-------|------------|----------|-------------| | general_2x / general_4x | 2x / 4x | General photos, landscapes | ✅ | | face_2x / face_4x | 2x / 4x | Portrait & face enhancement | ✅ | | face_v2_2x / face_v2_4x | 2x / 4x | Improved face model | ✅ | | high_fidelity_2x / high_fidelity_4x | 2x / 4x | High quality preservation | ✅ | | sharpen_denoise_1x | 1x | Denoise & sharpen | ✅ | | detail_denoise_1x | 1x | Detail preservation | ✅ | | generative_1x/2x/4x | — | Generative Enhance Model | ❌ |

#### 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

Command Line Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | --url, -u | string | required | URL of the video to enhance | | --output, -o | string | output.mp4 | Output file path | | --model, -m | string | general_restore_2x | Video model (see below) | | --resolution, -r | string | required | Target resolution in WxH (e.g., 1920x1080) | | --original-resolution | string | — | Original resolution (e.g., 1280x720) - optional | | --extension, -e | string | .mp4 | Output extension (.mp4, .mov, .avi) | | --fps | number | — | Target FPS (preserves original if omitted) | | --keep-audio | boolean | true | Preserve audio track | | --poll-interval | number | 10 | Polling interval in seconds | | --timeout | number | 600 | Maximum wait time in seconds |

#### Available Video Models

| Model | Description | Use Case | |-------|-------------|----------| | general_restore_1x / 2x / 4x | General video restoration | General upscaling | | face_soft_2x | Face-softening enhancement | Portrait videos | | portrait_restore_1x / 2x | Portrait restoration | Face-focused content | | ultrahd_restore_2x | Ultra HD upscaling | Highest quality upscale | | generative_1x | Generative fill | AI-powered restoration |

#### 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

Video Enhancement

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

Error Handling

Common errors and solutions:

| Error | Cause | Fix | |-------|-------|-----| | Invalid API key | Wrong or expired key | Update HITPAW_API_KEY | | Insufficient coins | Account balance too low | Top up at HitPaw Playground | | Unsupported model | Model name typo or not available | Check model table above | | Invalid extension | Output format not supported | Use .jpg/.png/.webp for images; .mp4/.mov/.avi for videos | | Invalid video URL | URL not publicly accessible | Ensure video is reachable via HTTPS | | Input/target resolution over limit | Exceeds 36 MP total pixels (e.g., 7680x4320 = ~33 MP) | Reduce resolution | | Video duration over limit | Video longer than 1 hour | Trim video first | | Rate limit exceeded | Too many requests | Wait and retry with exponential backoff | | Video processing failed | Corrupt video or unsupported codec | Try different input format or re-encode |

Error Codes

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

General Errors

| error_code | HTTP Status | Message | |------------|-------------|---------| | 100400000 | 400 | No access | | 100400001 | 400 | Invalid URL | | 100400002 | 400 | Bad Request | | 100401000 | 401 | Token is expired | | 100403000 | 403 | Invalid request parameters | | 100403001 | 403 | Access denied | | 100403002 | 403 | You don't have permission to access this resource | | 100429000 | 429 | Too many requests, please try again later | | 100500000 | 500 | Internal error | | 100500001 | 500 | Database error | | 100500002 | 500 | Cache error | | 100500003 | 500 | Failed to create file | | 100500004 | 500 | Signature verification failed | | 100500005 | 500 | Configuration error | | 100500006 | 500 | Unknown error | | 100500007 | 500 | Operation timeout |

API-Specific Errors

| error_code | HTTP Status | Message | |------------|-------------|---------| | 110400000 | 400 | api_key is not valid | | 110400002 | 400 | The task does not exist | | 110400003 | 400 | The task failed, please try again | | 110400005 | 400 | The model is not supported, please try again | | 110400007 | 400 | The extension is not valid | | 110400008 | 400 | The video URL is not valid | | 110400009 | 400 | The input resolution is over limit | | 110400010 | 400 | The target resolution is over limit | | 110400011 | 400 | The video duration is over limit | | 110402000 | 402 | The coins are not enough | | 110402001 | 402 | The coins are not enough | | 110402004 | 402 | The Demo try times exceeded |

Error Response Format

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

Rate Limiting

Best Practices

Polling for Job Status

Error Handling

Resource Limits

API Key Management

File URL Requirements

Technical Details

API Compatibility

This skill implements the official HitPaw API as documented:

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

Polling Strategy

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

Resolution & Format Limits

Image Model Specs:

| Model Category | DPI Support | Max Input | Max Output | Formats | |----------------|-----------|----------|----------|--------| | Enhancement & Denoise (general_*, face_*, high_fidelity_*, *_denoise_*) | ✅ | 70 MP | 432 MP | bmp, jpeg, jpg, png, jfif, tga, tiff, webp, heif | | Generative (generative_*, generative_portrait_*) | ❌ | 34 MP | 34 MP | Same formats |

Video Model Specs:

| Property | Limit | |----------|-------| | Max Input Resolution | No limit | | Max Output | 36 MP total pixels | | Duration | 0.5 seconds – 1 hour | | Input Formats | dv, mlv, m2ts, m2t, m2v, nut, ser, 3g2, 3gp, asf, avi, divx, f4v, flv, h261, h263, m4v, mkv, mov, mp4, mpeg, mpeg4, mpg, mxf, ogv, rm, rmvb, webm, wmv, gif | | Output Formats | mp4, mov, mkv, m4v, avi, gif |

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:

Audio Preservation

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

Support

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

# 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

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 →

Polling for Job Status

Error Handling

Resource Limits

API Key Management

File URL Requirements