HTMLCSStoImage API

Use the HTMLCSStoImage API via direct curl calls to generate images from HTML/CSS or capture screenshots of web pages.

Official docs: https://docs.htmlcsstoimage.com/

---

When to Use

Use this skill when you need to:

• Generate images from HTML/CSS for social cards, thumbnails, certificates
• Screenshot web pages or specific elements on a page
• Create dynamic images with custom fonts and styling
• Generate OG images for social media sharing

---

Prerequisites

1. Sign up at HTMLCSStoImage and create an account
2. Go to your Dashboard to get your User ID and API Key
3. Store credentials in environment variables

export HCTI_USER_ID="your-user-id"
export HCTI_API_KEY="your-api-key"

Authentication

The API uses HTTP Basic Authentication:

• Username: Your User ID
• Password: Your API Key

Pricing

• Free tier: 50 images/month
• Paid plans available for higher volume

---

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

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:

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

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:

bash -c '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"' | jq .

---

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:

bash -c '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"' | jq .

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

---

4. Screenshot a Web Page (URL to Image)

Capture a screenshot of any public URL:

bash -c 'curl -s "https://hcti.io/v1/image" -X POST -u "${HCTI_USER_ID}:${HCTI_API_KEY}" --data-urlencode "url=https://example.com"' | jq .

---

5. Screenshot with Delay (for JavaScript)

Wait for JavaScript to render before capturing:

bash -c 'curl -s "https://hcti.io/v1/image" -X POST -u "${HCTI_USER_ID}:${HCTI_API_KEY}" --data-urlencode "url=https://example.com" -d "ms_delay=1500"' | jq .

ms_delay waits specified milliseconds before taking the screenshot.

---

6. Capture Specific Element (Selector)

Screenshot only a specific element on the page:

bash -c 'curl -s "https://hcti.io/v1/image" -X POST -u "${HCTI_USER_ID}:${HCTI_API_KEY}" --data-urlencode "url=https://example.com" -d "selector=h1"' | jq .

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:

bash -c '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"' | jq .

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

---

8. Custom Viewport Size

Set specific viewport dimensions:

bash -c 'curl -s "https://hcti.io/v1/image" -X POST -u "${HCTI_USER_ID}:${HCTI_API_KEY}" --data-urlencode "url=https://example.com" -d "viewport_width=1200" -d "viewport_height=630"' | jq .

Perfect for generating OG images (1200x630).

---

9. Full Page Screenshot

Capture the entire page height:

bash -c 'curl -s "https://hcti.io/v1/image" -X POST -u "${HCTI_USER_ID}:${HCTI_API_KEY}" --data-urlencode "url=https://example.com" -d "full_screen=true"' | jq .

---

10. Block Cookie Banners

Automatically hide consent/cookie popups:

bash -c 'curl -s "https://hcti.io/v1/image" -X POST -u "${HCTI_USER_ID}:${HCTI_API_KEY}" --data-urlencode "url=https://example.com" -d "block_consent_banners=true"' | jq .

---

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:

IMAGE_URL="$(bash -c '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')"

curl -s "${IMAGE_URL}?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:

IMAGE_URL="$(bash -c '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')"

echo "Original: ${IMAGE_URL}"
echo "Thumbnail: ${IMAGE_URL}?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