Skip to main content

API Documentation

Base URL​

https://api-base.hitpaw.com

Authentication​

All API requests require authentication.

Endpoints​

Endpoint: POST /api/video-enhancer

Description: Submit a video enhancement task for video super-resolution processing.

Request Body:

{
  "video_url": "string",
  "model_name": "string",
  "resolution": [1920, 1080],
  "extension": "string",
  "original_resolution": [1280, 720]
}

Request Parameters:

ParameterTypeRequiredDescription
video_urlstringYesURL of the video to be enhanced
model_namestringYesModel name to use for enhancement
resolutionarray[integer]YesTarget resolution [width, height]
extensionstringNoFile extension (default: ".mp4")
original_resolutionarray[integer]NoOriginal video resolution [width, height]
Use Pre-sign Upload for Better Reliability

If you encounter download failures or network instability when our servers attempt to fetch your resources via video_url, we highly recommend using our OSS Pre-sign Upload API to securely upload your files first. Provide the generated access_url as your video_url to guarantee a 100% success rate for resource retrieval.

Response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "job_id": "f5007c0b-e902-4070-8c75-f337d896168f",
        "consume_coins": 75
    }
}

Response Fields:

FieldTypeDescription
job_idstringUnique identifier for the enhancement job
consume_coinsintegerNumber of coins consumed for this task

Example Request (cURL):

curl -X POST https://api-base.hitpaw.com/api/video-enhancer \
  -H "Content-Type: application/json" \
  -H "Apikey: YOUR_API_KEY" \
  -d '{
    "video_url": "https://example.com/video.mp4",
    "model_name": "video_enhance_v2",
    "resolution": [1920, 1080],
    "extension": ".mp4",
    "original_resolution": [1280, 720]
  }'

Example Request (Python):

import requests
import json

url = "https://api-base.hitpaw.com/api/video-enhancer"

headers = {
    "Content-Type": "application/json",
    "Apikey": "YOUR_API_KEY"
}

payload = {
    "video_url": "https://example.com/video.mp4",
    "model_name": "video_enhance_v2",
    "resolution": [1920, 1080],
    "extension": ".mp4",
    "original_resolution": [1280, 720]
}

response = requests.post(url, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(f"Job ID: {result['job_id']}")
    print(f"Consume Coins: {result['consume_coins']}")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Available Models​

Use the following values for the model_name parameter:

Display NameAPI model_name Value
Face Soft Model 2xface_soft_2x
Portrait Restore Model 1x/2xportrait_restore_1x / portrait_restore_2x
General Restore Model 1x/2x/4xgeneral_restore_1x / general_restore_2x / general_restore_4x
Ultra HD Model 2xultrahd_restore_2x
Generative Model 1xgenerative_1x

Model Specifications​

API model_nameSupported Input FormatsMax Input ResolutionSupported Output FormatsMax Output ResolutionDuration
All Video Modelsdv,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,3gp2,dmsm,dvdmedia,dvr-ms,trp,vob,vro,gif,xvidNo limitmp4, mov, mkv, m4v, avi, gif36 MP (Total Pixels)0.5s to 1 hour

Task Status​

Endpoint: POST /api/task-status

Description: Query the status of a submitted enhancement job. Use this endpoint to poll for job completion.

Request Body:

{
  "job_id": "string"
}

Request Parameters:

ParameterTypeRequiredDescription
job_idstringYesJob ID returned from photo-enhancer or video-enhancer endpoint

Response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "job_id": "string",
    "status": "string",
    "res_url": "string",
    "original_url": "string"
    }
}

Response Fields:

FieldTypeDescription
job_idstringJob identifier
statusstringCurrent job status (see status values below)
res_urlstringURL of the processed/enhanced file (available when status is "COMPLETED")
original_urlstringURL of the original input file

Status Values:

StatusDescription
CONVERTINGJob is currently being processed
COMPLETEDJob has completed successfully, result is available
ERRORJob failed due to an error

Example Request (cURL):

curl -X POST https://api-base.hitpaw.com/api/task-status \
  -H "Content-Type: application/json" \
  -H "Apikey: YOUR_API_KEY" \
  -d '{
    "job_id": "abc123def456"
  }'

Example Request (Python):

import requests
import json
import time

url = "https://api-base.hitpaw.com/api/task-status"

headers = {
    "Content-Type": "application/json",
    "Apikey": "YOUR_API_KEY"
}

payload = {
    "job_id": "abc123def456"
}

# Poll for job completion
max_attempts = 60
attempt = 0

while attempt < max_attempts:
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    
    if response.status_code == 200:
        result = response.json()
        status = result['status']
        
        print(f"Attempt {attempt + 1}: Status = {status}")
        
        if status == "COMPLETED":
            print(f"Job completed successfully!")
            print(f"Result URL: {result['res_url']}")
            print(f"Original URL: {result['original_url']}")
            break
        elif status == "ERROR":
            print(f"Job failed with error")
            break
        elif status == "CONVERTING":
            print(f"Job is still processing, waiting 5 seconds...")
            time.sleep(5)
        
        attempt += 1
    else:
        print(f"Error: {response.status_code}")
        print(response.text)
        break

if attempt >= max_attempts:
    print("Max polling attempts reached")

Error Codes​

The API uses the following error codes:

General Errors​

Error CodeHTTP StatusMessage
100400000400No access
100400001400Invalid URL
100400002400Bad Request
100401000401Token is expired
100403000403Invalid request parameters
100403001403Access denied
100403002403You don't have permission to access this resource
100429000429Too many requests, please try again later
100500000500Internal error
100500001500Database error
100500002500Cache error
100500003500Failed to create file
100500004500Signature verification failed
100500005500Configuration error
100500006500Unknown error
100500007500Operation timeout

API-Specific Errors​

Error CodeHTTP StatusMessage
110400000400api_key is not valid
110400002400The task does not exist
110400003400The task failed, please try again
110400005400The model is not supported, please try again
110400007400The extension is not valid
110400008400The video URL is not valid
110400009400The input resolution is over limit
110400010400The target resolution is over limit
110400011400The video duration is over limit
110402000402The coins are not enough
110402001402The coins are not enough
110402004402The Demo try times exceeded

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
  • Please implement exponential backoff in your retry logic

Best Practices​

  1. 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 for status values: CONVERTING (continue polling), COMPLETED (success), ERROR (failed)

  2. Error Handling:

    • Always check the HTTP status code and error code in the response
    • Implement appropriate retry logic for transient errors (5xx errors)
    • Don't retry for client errors (4xx errors) without fixing the request
    • Log error responses for debugging purposes

  3. Resource Limits:

    • Verify video duration limits before submission
    • Ensure input and target resolutions are within allowed limits
    • Check file extension validity before uploading

  4. API Key Management:

    • Store API keys securely using environment variables or secure vaults
    • Never commit API keys to version control
    • Rotate API keys periodically for security

  5. File URL Requirements:

    • Ensure image and video URLs are publicly accessible
    • Use HTTPS URLs for better security
    • Verify URLs are valid before submitting requests

Complete Workflow Example (Python)​

Here's a complete example showing the entire workflow from submission to result retrieval:

import requests
import json
import time

class HitPawAPIClient:
    def __init__(self, api_key, base_url="https://api-base.hitpaw.com"):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {
            "Content-Type": "application/json",
            "Apikey": api_key
        }
    
    def enhance_video(self, video_url, model_name, resolution, extension=".mp4", 
                     original_resolution=None):
        """Submit a video enhancement job"""
        url = f"{self.base_url}/api/video-enhancer"
        payload = {
            "video_url": video_url,
            "model_name": model_name,
            "resolution": resolution,
            "extension": extension
        }
        
        if original_resolution:
            payload["original_resolution"] = original_resolution
        
        response = requests.post(url, headers=self.headers, data=json.dumps(payload))
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Error {response.status_code}: {response.text}")
    
    def check_status(self, job_id):
        """Check job status"""
        url = f"{self.base_url}/api/task-status"
        payload = {"job_id": job_id}
        
        response = requests.post(url, headers=self.headers, data=json.dumps(payload))
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Error {response.status_code}: {response.text}")
    
    def wait_for_completion(self, job_id, max_attempts=120, poll_interval=5):
        """Poll job status until completion or error"""
        attempt = 0
        
        while attempt < max_attempts:
            try:
                result = self.check_status(job_id)
                status = result['status']
                
                print(f"[Attempt {attempt + 1}/{max_attempts}] Status: {status}")
                
                if status == "COMPLETED":
                    print("✓ Job completed successfully!")
                    return result
                elif status == "ERROR":
                    raise Exception("Job failed with ERROR status")
                elif status == "CONVERTING":
                    print(f"  Still processing... waiting {poll_interval} seconds")
                    time.sleep(poll_interval)
                
                attempt += 1
            except Exception as e:
                print(f"Error checking status: {str(e)}")
                raise
        
        raise Exception(f"Job did not complete within {max_attempts * poll_interval} seconds")

# Usage example
if __name__ == "__main__":
    # Initialize client
    client = HitPawAPIClient(api_key="YOUR_API_KEY")
    
    try:

        # Example : Video Enhancement
        print("=== Video Enhancement ===")
        video_result = client.enhance_video(
            video_url="https://example.com/video.mp4",
            model_name="video_enhance_v2",
            resolution=[1920, 1080],
            original_resolution=[1280, 720]
        )
        print(f"Job ID: {video_result['job_id']}")
        print(f"Coins consumed: {video_result['consume_coins']}")
        
        # Wait for completion
        final_result = client.wait_for_completion(video_result['job_id'])
        print(f"Result URL: {final_result['res_url']}")
        
    except Exception as e:
        print(f"Error: {str(e)}")

Support​

For API key requests, billing questions, or technical support, please contact our support team.

Ready to Start?

Get started by Purchasing an API Key Now to unlock full access to the HitPaw Enhancement API.