Htmlcsstoimage

Troubleshooting

If requests fail, run zero doctor check-connector --env-name HCTI_API_KEY or zero doctor check-connector --url https://hcti.io/v1/image --method POST

How to Use

All examples below assume you have HCTI_USER_ID and HCTI_API_KEY set.

The base URL for the API is:

• https://hcti.io/v1/image

1. Simple HTML to Image

Generate an image from basic HTML.

Write to /tmp/hcti_html.txt:

<div style="padding:20px;background:blue;color:white;font-size:24px;">Hello World</div>

Then run:

curl -s "https://hcti.io/v1/image" -X POST -u "$HCTI_USER_ID:$HCTI_API_KEY" --data-urlencode "html@/tmp/hcti_html.txt"

Response:

{
  "url": "https://hcti.io/v1/image/abc123..."
}

The returned URL is permanent and served via Cloudflare CDN.

2. HTML with CSS Styling

Generate a styled card image.

Write to /tmp/hcti_html.txt:

<div class="card"><h1>Welcome</h1><p>This is a styled card</p></div>

Write to /tmp/hcti_css.txt:

.card { padding: 40px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); border-radius: 12px; color: white; font-family: sans-serif; text-align: center; } h1 { margin: 0 0 10px 0; } p { margin: 0; opacity: 0.9; }

Then run:

curl -s "https://hcti.io/v1/image" -X POST -u "$HCTI_USER_ID:$HCTI_API_KEY" --data-urlencode "html@/tmp/hcti_html.txt" --data-urlencode "css@/tmp/hcti_css.txt"

3. Use Google Fonts

Generate an image with custom fonts.

Write to /tmp/hcti_html.txt:

<div class="title">Beautiful Typography</div>

Write to /tmp/hcti_css.txt:

.title { font-family: Playfair Display; font-size: 48px; padding: 40px; background: #1a1a2e; color: #eee; }

Then run:

curl -s "https://hcti.io/v1/image" -X POST -u "$HCTI_USER_ID:$HCTI_API_KEY" --data-urlencode "html@/tmp/hcti_html.txt" --data-urlencode "css@/tmp/hcti_css.txt" -d "google_fonts=Playfair Display"

Multiple fonts: google_fonts=Playfair Display|Roboto|Open Sans

4. Screenshot a Web Page (URL to Image)

Capture a screenshot of any public URL:

Write to /tmp/hcti_url.txt:

https://example.com

curl -s "https://hcti.io/v1/image" -X POST -u "$HCTI_USER_ID:$HCTI_API_KEY" --data-urlencode "url@/tmp/hcti_url.txt"

5. Screenshot with Delay (for JavaScript)

Wait for JavaScript to render before capturing:

Write to /tmp/hcti_url.txt:

https://example.com

curl -s "https://hcti.io/v1/image" -X POST -u "$HCTI_USER_ID:$HCTI_API_KEY" --data-urlencode "url@/tmp/hcti_url.txt" -d "ms_delay=1500"

ms_delay waits specified milliseconds before taking the screenshot.

6. Capture Specific Element (Selector)

Screenshot only a specific element on the page:

curl -s "https://hcti.io/v1/image" -X POST -u "$HCTI_USER_ID:$HCTI_API_KEY" --data-urlencode "url@/tmp/hcti_url.txt" -d "selector=h1"

Use any CSS selector: #id, .class, div > p, etc.

7. High Resolution (Retina)

Generate 2x or 3x resolution images.

Write to /tmp/hcti_html.txt:

<div style="padding:20px;font-size:18px;">High Resolution Image</div>

Then run:

curl -s "https://hcti.io/v1/image" -X POST -u "$HCTI_USER_ID:$HCTI_API_KEY" --data-urlencode "html@/tmp/hcti_html.txt" -d "device_scale=2"

device_scale accepts values 1-3 (default: 1).

8. Custom Viewport Size

Set specific viewport dimensions:

curl -s "https://hcti.io/v1/image" -X POST -u "$HCTI_USER_ID:$HCTI_API_KEY" --data-urlencode "url@/tmp/hcti_url.txt" -d "viewport_width=1200" -d "viewport_height=630"

Perfect for generating OG images (1200x630).

9. Full Page Screenshot

Capture the entire page height:

curl -s "https://hcti.io/v1/image" -X POST -u "$HCTI_USER_ID:$HCTI_API_KEY" --data-urlencode "url@/tmp/hcti_url.txt" -d "full_screen=true"

10. Block Cookie Banners

Automatically hide consent/cookie popups:

curl -s "https://hcti.io/v1/image" -X POST -u "$HCTI_USER_ID:$HCTI_API_KEY" --data-urlencode "url@/tmp/hcti_url.txt" -d "block_consent_banners=true"

11. Download Image Directly

Add ?dl=1 to the image URL to trigger download.

Write to /tmp/hcti_html.txt:

<div style="padding:20px;background:green;color:white;">Download Me</div>

Then run:

curl -s "https://hcti.io/v1/image" -X POST -u "$HCTI_USER_ID:$HCTI_API_KEY" --data-urlencode "html@/tmp/hcti_html.txt" | jq -r '.url'

This will output the image URL. Copy the URL and download with:

curl -s "https://hcti.io/v1/image/<your-image-id>?dl=1" --output image.png

12. Resize on the Fly

Add width/height query parameters to resize.

Write to /tmp/hcti_html.txt:

<div style="padding:40px;background:purple;color:white;font-size:32px;">Resizable</div>

Then run:

curl -s "https://hcti.io/v1/image" -X POST -u "$HCTI_USER_ID:$HCTI_API_KEY" --data-urlencode "html@/tmp/hcti_html.txt" | jq -r '.url'

This outputs the image URL. Add query parameters to resize:

Original: https://hcti.io/v1/image/<your-image-id>
Thumbnail: https://hcti.io/v1/image/<your-image-id>?width=200&height=200

Response Format

Success (200):

{
  "url": "https://hcti.io/v1/image/be4c5118-fe19-462b-a49e-48cf72697a9d"
}

Error (400):

{
  "error": "Bad Request",
  "statusCode": 400,
  "message": "HTML is Required"
}

Guidelines

1. Use --data-urlencode for HTML/CSS: Properly encodes special characters
2. URLs must be public: Pages requiring login cannot be screenshotted
3. Use ms_delay for JS-heavy pages: Give time for JavaScript to render
4. Choose appropriate device_scale: 2x for retina displays, 1x for standard
5. Image URLs are permanent: They're cached on Cloudflare CDN globally
6. Use selectors for cropping: More efficient than full page + manual crop