Single-Request Image Generation

Generate images from HTML/CSS in a single request with signed URLs.

---

Table of contents

• Key benefits
• Creating an image
  • URL Components
  • Parameters
  • Additional parameters
  • Understanding HMAC authentication
  • Testing token generation online
  • JavaScript example
  • PHP example
  • Example response
• Need help?

---

Key benefits

This endpoint allows you to generate image URLs that directly render images when accessed:

• No POST request needed: Generate image URLs client-side without making API calls
• Client-side friendly: Use signed URLs to keep your API Key secure
• Simplified workflow: Skip the image creation step and go straight to image rendering

Unlike the standard endpoint that requires a POST request followed by using the returned URL, this endpoint lets you construct a signed URL that will generate and return the image when accessed.

Each API key has an associated API ID (public) and API Key (secret). The token is generated by creating an HMAC SHA256 hash of the query string (without the ?) using your API Key as the secret.

Creating an image

To generate an image with a signed URL, construct a URL with your API ID and token:

  get https://hcti.io/v1/image/create-and-render/:api_id/:token/:format

URL Components

Parameters

The parameters are the same as the standard API endpoint, but they must be passed as query parameters in the URL.

---

Additional parameters

Optional parameters for greater control over your image.

---

Understanding HMAC authentication

HMAC (Hash-based Message Authentication Code) is a mechanism for calculating a message authentication code involving a hash function in combination with a secret key. In this API:

1. The message is your query string (without the leading ?), e.g., html=<div>Hello</div>&css=div{color:red}
2. The secret key is your API Key
3. The hash function used is SHA-256
4. The resulting token is used in the URL path to authenticate the request

This allows you to create signed URLs without exposing your API Key. If any part of the query string is changed without updating the token, the url will be invalid.

Testing token generation online

You can test token generation using online tools like FreeFormatter’s HMAC Generator:

1. Enter your query string (e.g., html=<div>Hello</div>) as the String
2. Enter your API Key as the Secret Key
3. The Computed MAC in lowercase hex format is your token

For example:

• Input String: html=<div>Hello</div>
• Secret Key: your-api-key-here
• Computed MAC: a659c427bc8eb94c32a3ca9cf92a1ad873da2b36be436f3084b8b76eaa6e7b65

Your final URL would be:

https://hcti.io/v1/image/create-and-render/your-api-id-here/a659c427bc8eb94c32a3ca9cf92a1ad873da2b36be436f3084b8b76eaa6e7b65/png?html=<div>Hello</div>

JavaScript example

const crypto = require('crypto');

function generateToken(queryString, apiKey) {
  return crypto
    .createHmac('sha256', apiKey)
    .update(queryString)
    .digest('hex');
}

// Example 1: Using HTML and CSS
const apiId = 'your_api_id_here';
const apiKey = 'your_api_key_here';
const format = 'png';
const queryString = 'html=<div>Hello World</div>&css=div{color:red}';
const token = generateToken(queryString, apiKey);

// Generate the URL
const imageUrl = `https://hcti.io/v1/image/create-and-render/${apiId}/${token}/${format}?${queryString}`;

// Example 2: Using a URL parameter
const websiteUrl = 'https://example.com';
const encodedUrl = encodeURIComponent(websiteUrl);
const urlQueryString = `url=${encodedUrl}`;
const urlToken = generateToken(urlQueryString, apiKey);

// Generate the URL for website screenshot
const screenshotUrl = `https://hcti.io/v1/image/create-and-render/${apiId}/${urlToken}/${format}?${urlQueryString}`;

// Now these URLs can be used directly in an <img> tag or as a link
// <img src="imageUrl" alt="Generated image" />

PHP example

<?php
// Example 1: Using HTML and CSS
$apiId = 'your_api_id_here';
$apiKey = 'your_api_key_here';
$format = 'png';

// Create query string
$html = '<div>Hello from PHP</div>';
$css = 'div{color:blue;font-family:Arial}';
$queryString = 'html=' . urlencode($html) . '&css=' . urlencode($css);

// Generate token
$token = hash_hmac('sha256', $queryString, $apiKey);

// Generate the URL
$imageUrl = "https://hcti.io/v1/image/create-and-render/$apiId/$token/$format?$queryString";
echo "Generated image URL: $imageUrl\n";

// Example 2: Using a URL parameter
$websiteUrl = 'https://example.com';
$urlQueryString = 'url=' . urlencode($websiteUrl);
$urlToken = hash_hmac('sha256', $urlQueryString, $apiKey);

// Generate the URL for website screenshot
$screenshotUrl = "https://hcti.io/v1/image/create-and-render/$apiId/$urlToken/$format?$urlQueryString";
echo "Screenshot URL: $screenshotUrl\n";

// Use the URLs directly in your HTML
// echo '<img src="' . htmlspecialchars($imageUrl) . '" alt="Generated image">';

---

Example response

When you access a valid signed URL, the API will return the generated image directly with the appropriate content type header (image/png, image/jpeg, or image/webp depending on the format).

If there’s an error, you’ll receive a JSON response:

STATUS: 400 BAD REQUEST

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

STATUS: 401 UNAUTHORIZED

{
  "error": "Unauthorized",
  "statusCode": 401,
  "message": "Invalid token"
}

---

Need help?

Talk to a human. Please email us support@htmlcsstoimage.com with any questions and we’ll gladly help you get started.

---