Skip to main content

FAQ & Troubleshooting

This guide provides answers to frequently asked questions and troubleshooting steps for common issues encountered when integrating and using the HitPaw Enhancement API.

1. Account & Billing​

Q: How are API requests billed?

HitPaw API uses a credit-based billing system. Credits (coins) are deducted based on the specific API you call:

  • Image Enhancement: Billed per image based on the selected model category and output resolution tier (10 to 480 credits per image).
  • Video Enhancement: Billed per second of output video, depending on the model, resolution, and frame rate.
  • Image Segmentation: Flat rate of 20 credits per image.
  • Image Moderation: Flat rate of 5 credits per image.

For a detailed breakdown of pricing tiers, please refer to the API Pricing Guide.

Q: I purchased credits, but my API calls still return 110402000 (The coins are not enough). What should I do?

Purchased credits are typically synchronized with your API account within 1 to 3 minutes. If you are still seeing insufficient balance errors after 5 minutes, please perform the following checks:

  1. Log in to the HitPaw API Platform and verify that your credit balance has updated.
  2. Double-check the Apikey header in your request to ensure it matches the API Key of the account you recharged.
  3. If the balance is correct on the platform but API calls still fail, please contact our engineering support at [email protected].

2. API Keys & Authentication​

Q: Where do I find or create my API key?

You can manage and create your API keys on the HitPaw API Platform. Once logged in, go to the API Keys section to generate a new key or copy your existing key.

Q: What are the API rate limits?

Our APIs implement rate limiting to ensure platform stability. If you exceed the allowed request frequency, the API will return an HTTP 429 status code with error code 100429000.

Recommended Action: Implement an exponential backoff strategy in your retry mechanism (e.g., waiting 1s, then 2s, 4s, etc.) before retrying the request.

3. Media Handling & Limits​

Q: Why does my task fail with a download error or Invalid URL?

This usually occurs when the HitPaw servers fail to fetch the image or video from the URL provided in img_url, video_url, or file_url. Common reasons include:

  • The URL is not publicly accessible (e.g., hosted on localhost or behind a private intranet).
  • The hosting server has anti-bot protections, hotlinking restrictions, or geo-blocking that blocks requests from our servers.
  • The URL requires authentication headers, cookies, or has expired.

Best Practice Solution: We highly recommend using our OSS Pre-sign Upload API. By uploading your media files directly to our secure storage first and submitting the generated access_url, you bypass external network instability and guarantee a 100% download success rate.

Q: My task status remains stuck in CONVERTING (e.g., over 15 minutes) or fails silently. What causes this?

A prolonged CONVERTING state typically stems from one of two reasons:

1. Network Timeouts (Most Common)
Our servers may have encountered network timeouts or permissions barriers while trying to download the source file from your external storage provider (such as Firebase Storage, AWS S3, or Google Cloud Storage).
Solution: Use our OSS Pre-sign Upload API to upload the image or video directly to our local environment before triggering the task. This ensures maximum stability. (Note: Staged source files uploaded to our storage are kept for only 7 days).

2. High Server Load & Queueing
If you are already using our OSS Pre-sign Upload API and still experience long CONVERTING times, it indicates a temporary surge in API requests causing a queue on our GPU servers.
Solution: This is normal during peak traffic. Please ensure your application implements adequate timeout limits (e.g., waiting longer) and continues to poll the status. Do not assume the task has failed until the API explicitly returns an ERROR status.

Q: What are the input media file limits?

Please observe the following limits to prevent validation errors:

  • Image Enhancement: Maximum input resolution is 70 megapixels (MP) for standard models, and 34 megapixels (MP) for generative diffusion models.
  • Video Enhancement: Maximum output resolution is 36 megapixels (MP). Video duration must be between 0.5 seconds and 1 hour.

If your media exceeds these limits, please compress or crop the file before submission.

Q: Which image and video formats are supported?

We support a wide array of formats:

  • Images: .jpg, .jpeg, .png, .webp, .bmp, .jfif, .tga, .tiff, and .heif.
  • Videos: .mp4, .mov, .avi, .mkv, .flv, .mpeg, .webm, .wmv, and .gif (using standard codecs).
Q: Why do my ultra-high-resolution output videos (e.g., 7.5K) stutter when playing in QuickTime or PotPlayer?

This is a common hardware decoding limitation, not a corrupted video or an algorithm issue.

Any output video with a resolution exceeding 4K (e.g., 7.5K) may experience playback stuttering in default media players like QuickTime or PotPlayer due to their hardware acceleration limits.

Solution: To play ultra-high-resolution videos smoothly, we recommend using professional media players optimized for efficient decoding:

4. Task Status & Webhooks​

Q: How often should I poll the /api/task-status endpoint?

To avoid hitting rate limits and generating unnecessary server load, we recommend the following polling intervals:

  • Image Processing Tasks: Poll every 2 to 5 seconds.
  • Video Processing Tasks: Poll every 5 to 10 seconds (as video processing takes longer).

Ensure you set a maximum number of polling attempts (e.g., 60 to 120 attempts) to prevent infinite loops in your application.

Q: How long are the enhanced files stored on HitPaw servers?

For privacy and resource efficiency, all processed output files (available via res_url) are automatically deleted after 7 days. You must download and persist these files to your own storage provider before they expire.

Need More Help?​

If you encounter an issue not covered here or require custom enterprise limits, please reach out to our engineering support team at [email protected].