---
name: htmlcsstoimage
description: HTML/CSS to Image API for rendering. Use when user mentions "HTML to
  image", "render HTML", "screenshot", or "convert to image".
---

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

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

Then run:

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

Response:
```json
{
  "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`:

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

Write to `/tmp/hcti_css.txt`:

```css
.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
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`:

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

Write to `/tmp/hcti_css.txt`:

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

Then run:

```bash
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
```

```bash
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
```

```bash
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:

```bash
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`:

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

Then run:

```bash
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:

```bash
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:

```bash
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:

```bash
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`:

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

Then run:

```bash
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:

```bash
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`:

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

Then run:

```bash
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):**
```json
{
  "url": "https://hcti.io/v1/image/be4c5118-fe19-462b-a49e-48cf72697a9d"
}
```

**Error (400):**
```json
{
  "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