llms-full.txt

# HTML/CSS to Image API - Complete Documentation

> API for converting HTML and CSS to high-quality images (PNG, JPG, WebP, PDF). Renders exactly like Google Chrome.

Website: https://htmlcsstoimage.com
Documentation: https://docs.htmlcsstoimage.com
Dashboard: https://htmlcsstoimage.com/dashboard

---

## Authentication

The API uses HTTP Basic authentication.

- Username: Your **User ID** from the dashboard
- Password: Your **API Key** from the dashboard

Get credentials at: https://htmlcsstoimage.com/dashboard

---

## API Endpoints

### Create Image

```
POST https://hcti.io/v1/image
```

Creates an image from HTML/CSS or screenshots a URL.

**Required Parameters (one of):**

| Parameter | Type | Description |
|-----------|------|-------------|
| `html` | String | HTML to render. Can be a snippet or full page. |
| `url` | String | URL to screenshot. Must be publicly accessible. |

**Optional Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `css` | String | CSS styles for your HTML |
| `google_fonts` | String | Google Fonts to load. Multiple fonts: `Roboto|Open Sans` |
| `device_scale` | Double | Pixel ratio (0.1-3). Default: 2 (retina) |
| `viewport_width` | Integer | Browser viewport width in pixels |
| `viewport_height` | Integer | Browser viewport height in pixels |
| `viewport_mobile` | Boolean | Emulate a mobile viewport |
| `viewport_landscape` | Boolean | Render the viewport in landscape orientation |
| `viewport_touch` | Boolean | Enable touch support in the viewport |
| `media_type` | String | Emulate `screen` or `print` CSS media |
| `headers` | Object | Flat object of custom HTTP header names and values for URL screenshots. Up to 20 unique, case-insensitive names. |
| `additional_header_origins` | Array | Additional exact HTTP(S) origins allowed to receive custom headers. Up to 20 unique origins. |
| `include_headers_on_subrequests` | Boolean | Also send custom headers with subrequests to the requested URL's origin and any additional header origins. Default: false. |
| `identify_as_hcti` | Boolean | Add `X-HCTI-SCREENSHOT: 1` to the top-level URL request. |
| `selector` | String | CSS selector to capture specific element |
| `ms_delay` | Integer | Milliseconds to wait before capture (0-10000) |
| `max_wait_ms` | Integer | Maximum wait time cap (500-10000) |
| `render_when_ready` | Boolean | Wait for ScreenshotReady() JS call |
| `full_screen` | Boolean | Capture full scrollable page height |
| `block_consent_banners` | Boolean | Block cookie consent popups |
| `color_scheme` | String | `light` or `dark` mode |
| `timezone` | String | IANA timezone, e.g. `America/New_York` |
| `disable_twemoji` | Boolean | Use native emoji instead of Twemoji |
| `transparent_background` | Boolean | Render with a transparent background. Use PNG output. |
| `proxy_id` | String | Route the render's outbound traffic through one of your dashboard-configured HTTP proxies. Available on the 10k images/month plan or higher. See https://docs.htmlcsstoimage.com/guides/advanced/proxies/ |
| `storage_destination_id` | String | Save rendered files to one of your organization's configured storage destinations. Available on the 10,000 images/month plan or higher. See https://docs.htmlcsstoimage.com/guides/advanced/storage-destinations/ |

**Example Request:**

```bash
curl -X POST https://hcti.io/v1/image \
  -u 'your-user-id:your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "html": "<div style=\"padding:20px;background:#4f46e5;color:white;\">Hello World</div>",
    "google_fonts": "Roboto"
  }'
```

**Response (200 OK):**

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

---

### Get Image

```
GET https://hcti.io/v1/image/:image_id
```

Returns the generated image. Append file extension for format:

- `.png` (default)
- `.jpg`
- `.webp`
- `.pdf`

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `width` | Integer | Resize width (max 5000) |
| `height` | Integer | Resize height (max 5000) |
| `dpi` | Integer | DPI metadata (30-600) |
| `dl` | Integer | Set to 1 for download attachment |

**Cropping Parameters:**

| Parameter | Description |
|-----------|-------------|
| `aspect_ratio` | Crop to ratio, e.g. `16_9`, `1_1` |
| `x_1`, `x_2` | X-axis crop coordinates |
| `y_1`, `y_2` | Y-axis crop coordinates |
| `crop_width` | Width of crop region |
| `crop_height` | Height of crop region |

---

### Delete Image

```
DELETE https://hcti.io/v1/image/:image_id
```

Permanently deletes the image. Returns 202 Accepted.

---

### Batch Create Images

```
POST https://hcti.io/v1/image/batch
```

Create up to 25 images in a single request.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `default_options` | Object | Default params for all images |
| `variations` | Array | Array of image objects (max 25) |

**Example:**

```json
{
  "default_options": {
    "css": "body { font-family: sans-serif; }",
    "device_scale": 2
  },
  "variations": [
    { "html": "<div>Image 1</div>" },
    { "html": "<div>Image 2</div>" },
    { "html": "<div>Image 3</div>" }
  ]
}
```

---

### Batch Delete Images

```
DELETE https://hcti.io/v1/image/batch
```

```json
{
  "ids": ["abc123", "def456", "ghi789"]
}
```

---

### List Images

```
GET https://hcti.io/v1/images
```

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `count` | Integer | Number to return (max 50) |
| `page_token` | String | Pagination token |

---

### Check Usage

```
GET https://hcti.io/v1/usage
```

Returns image creation counts by hour, day, month, and billing period.

---

## Templates

Templates allow reusable image designs with variable substitution. Templates can be created by sending HTML/CSS to the Templates API or by building visually in the dashboard with the Template Editor.

Template Editor docs:
- Overview: https://docs.htmlcsstoimage.com/template-editor/
- Quick Start: https://docs.htmlcsstoimage.com/template-editor/quick-start/
- Canvas: https://docs.htmlcsstoimage.com/template-editor/canvas/
- Variables: https://docs.htmlcsstoimage.com/template-editor/variables/
- Blocks: https://docs.htmlcsstoimage.com/template-editor/blocks/
- Advanced: https://docs.htmlcsstoimage.com/template-editor/advanced/

For editor templates, use the Variables guide to decide which values should be passed with `template_values`. Rich Text and HTML blocks can discover Handlebars variables from their content. Other supported properties can be connected to variables in the editor.

### Create Template

```
POST https://hcti.io/v1/template
```

### Create Image from Template

```
POST https://hcti.io/v1/image
```

```json
{
  "template_id": "t-your-template-id",
  "template_values": {
    "title": "My Title",
    "author": "John Doe"
  }
}
```

---

## Automatic Open Graph Images

OG Image Configs generate social cards for existing public websites, stores, CMSs, and static sites without requiring an API request or HMAC signature for every page.

An exact website origin is connected to a domain ID. The path after that domain ID maps to the same path on the configured origin:

| Public page | HCTI image URL |
|-------------|----------------|
| `https://example.com/` | `https://hcti.io/v1/og/DOMAIN_ID/` |
| `https://example.com/articles/hello` | `https://hcti.io/v1/og/DOMAIN_ID/articles/hello` |

Rendering modes:
- **Page Screenshot:** Capture the page viewport or an element selected with `hcti:selector`.
- **Template Values:** Render an HCTI template using mapped page metadata or explicit `html:tv:VARIABLE_NAME` meta tags.

Behavior:
- Dashboard defaults can be overridden with supported `hcti:` page metadata. Page metadata takes precedence.
- Refresh intervals control when HCTI checks the source page for new metadata.
- A numeric `hcti:content_version` gives changed content at the same page path a new image identity.
- Query strings are ignored for source-page selection and cache busting.
- Image sizing can use one universal image, adapt one render to platform-specific bounds, or render each platform size separately.

Use an OG Image Config when images correspond to public page paths. Use the image API, templates, or signed image URLs when arbitrary values must be passed at request time.

Documentation:
- Setup: https://docs.htmlcsstoimage.com/getting-started/og-images/
- Supported page parameters: https://docs.htmlcsstoimage.com/getting-started/og-images/supported-parameters/
- Platform and CMS guides: https://docs.htmlcsstoimage.com/guides/og-images/
- Caching and refreshes: https://docs.htmlcsstoimage.com/guides/debugging/og-image-caching/
- Signed Image URLs: https://docs.htmlcsstoimage.com/getting-started/create-and-render/

---

## HTTP Proxies

Route a render's outbound traffic through your own HTTP proxy. Useful for restricting access to internal content, controlling the egress IP, or getting past bot detection.

- Configure proxies in the dashboard at https://htmlcsstoimage.com/dashboard/proxies (URL, port, optional auth, optional bypass hosts).
- Use a proxy by passing `proxy_id` on the create image request.
- Disabling a proxy does not affect images that have already been generated.
- Available on the 10,000 images/month plan or higher.

Full guide: https://docs.htmlcsstoimage.com/guides/advanced/proxies/

---

## Storage Destinations

Save rendered files to an Amazon S3 or S3-compatible bucket owned by your organization.

- Configure and test destinations at https://htmlcsstoimage.com/dashboard/storage-destinations
- Supported providers: Amazon S3, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Wasabi, Google Cloud Storage, and other S3-compatible services.
- Cloudflare R2 includes an optional **Data jurisdiction** setting. Choose **Default** for unrestricted and location-hint buckets, **European Union** for EU jurisdiction buckets, or **FedRAMP** for FedRAMP jurisdiction buckets. Changing it requires another connection test.
- Pass `storage_destination_id` on HTML/CSS, URL, batch, or template create requests.
- By default, HCTI retains its normal copy and also writes to your bucket.
- **Disable HCTI Storage** keeps rendered files out of HCTI storage and the HCTI CDN.
- When you choose to **Disable HCTI Storage**, the image create response contains a `/v1/store/...` URL. Send an authenticated `PUT` request to that URL using valid API credentials from the same organization as the image. Missing or invalid credentials return HTTP 401.
- HTTP 200 and 424 store responses return a JSON `StoreImageResult` with `outcome`, `baseResult`, `transformationResult`, `success`, `message`, and `statusCode`. Incomplete results also include `error` and `referenceId`; other failures use the standard API error format.
- `outcome` is `complete` (HTTP 200), `partial` (HTTP 424; base stored but transformation failed), or `failed` (HTTP 424; base not stored).
- Each object result reports `status` (`stored`, `already_stored`, `failed`, or `not_attempted`), `target` (`hcti_storage` or `storage_destination`), `bucket`, and `key`.
- Objects use the access settings configured on the destination bucket; HCTI does not make them public. Deleting an image or destination in HCTI does not delete rendered objects already written to the bucket.
- Available on the 10,000 images/month plan or higher.

Full guide: https://docs.htmlcsstoimage.com/guides/advanced/storage-destinations/

Provider setup guides:

- Amazon S3: https://docs.htmlcsstoimage.com/guides/advanced/storage-destinations/s3/
- Cloudflare R2: https://docs.htmlcsstoimage.com/guides/advanced/storage-destinations/r2/
- Backblaze B2: https://docs.htmlcsstoimage.com/guides/advanced/storage-destinations/backblaze-b2/
- DigitalOcean Spaces: https://docs.htmlcsstoimage.com/guides/advanced/storage-destinations/digitalocean-spaces/
- Wasabi: https://docs.htmlcsstoimage.com/guides/advanced/storage-destinations/wasabi/
- Google Cloud Storage: https://docs.htmlcsstoimage.com/guides/advanced/storage-destinations/google-cloud-storage/
- Other S3-compatible services: https://docs.htmlcsstoimage.com/guides/advanced/storage-destinations/s3-compatible/

---

## MCP Server Integration

For AI assistants like Cursor, Claude Desktop, Windsurf, Cline, and Zed.

**Server URL:** `https://mcp.hcti.io`

**Available Tools:**
- `create_image` - Generate image from HTML/CSS
- `create_url_image` - Screenshot a URL
- `create_templated_image` - Use a template
- `create_batch_images` - Create multiple images
- `create_template` - Save a template
- `list_templates` - View templates

**Cursor Setup:**

```json
{
  "mcpServers": {
    "hcti": {
      "type": "http",
      "url": "https://mcp.hcti.io"
    }
  }
}
```

---

## n8n Integration

Use the HTML/CSS to Image integration to generate images, website screenshots, PDFs, and signed render-on-demand URLs in n8n workflows.

**Package:** `@html-css-to-image/n8n-nodes-html-css-to-image`

**Docs:** https://docs.htmlcsstoimage.com/integrations/n8n/

**npm:** https://www.npmjs.com/package/@html-css-to-image/n8n-nodes-html-css-to-image

**Available operations:**
- Create an image or PDF from HTML and CSS
- Take a screenshot of a webpage URL
- Render a saved template with dynamic values
- Generate signed template or webpage URLs
- Return URL metadata, a binary PNG/JPG/WebP/PDF file, or both

---

## Official TypeScript Client (npm)

Use the official npm package for typed requests and helper methods in Node.js/TypeScript projects.

**Package:** `@html-css-to-image/client`  
**Install:** `npm install @html-css-to-image/client`  
**Docs:** https://docs.htmlcsstoimage.com/example-code/typescript/  
**npm:** https://www.npmjs.com/package/@html-css-to-image/client

---

## Code Examples

### Python

```python
import requests

HCTI_API_ENDPOINT = "https://hcti.io/v1/image"
HCTI_API_USER_ID = 'your-user-id'
HCTI_API_KEY = 'your-api-key'

data = {
    'html': "<div class='box'>Hello, world!</div>",
    'css': ".box { color: white; background-color: #0f79b9; padding: 10px; }"
}

image = requests.post(
    url=HCTI_API_ENDPOINT,
    data=data,
    auth=(HCTI_API_USER_ID, HCTI_API_KEY)
)

print(image.json()['url'])
```

### JavaScript (Node.js)

```javascript
const fetch = require('node-fetch');

const data = {
  html: "<div class='box'>Hello, world!</div>",
  css: ".box { color: white; background-color: #0f79b9; padding: 10px; }"
};

const response = await fetch('https://hcti.io/v1/image', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from('user-id:api-key').toString('base64')
  },
  body: JSON.stringify(data)
});

const result = await response.json();
console.log(result.url);
```

### cURL

```bash
curl -X POST https://hcti.io/v1/image \
  -u 'user-id:api-key' \
  -H 'Content-Type: application/json' \
  -d '{"html": "<h1>Hello World</h1>"}'
```

---

## Common Use Cases

1. **Social Cards (OG Images)** - Use path-based OG Image Configs for public sites and CMSs, or templates and the image API for application data
2. **Website Screenshots** - Capture any public URL
3. **Dynamic Images** - Certificates, receipts, personalized graphics
4. **Email Images** - Generate images for email campaigns

---

## FAQ

**Is there a rate limit?**
No rate limits. Create images until you reach your plan limit.

**How long do image URLs last?**
Forever, as long as your account is active.

**What file formats are supported?**
PNG (default), JPG, WebP, and PDF.

**Do you support custom fonts?**
Yes, via `google_fonts` parameter or embedding font links in HTML.

---

## Support

Email: support@htmlcsstoimage.com

We're experts at debugging HTML rendering issues and love helping developers succeed.