add doc for create + render

Author: mscoutermarsh

getting-started/create-and-render.md

@@ -0,0 +1,208 @@
+---
+layout: page
+title: Single-Request Image Generation
+permalink: /getting-started/create-and-render/
+parent: Getting started
+nav_order: 6
+---
+# Single-Request Image Generation
+{: .no_toc }
+{: .fs-9 }
+
+Generate images from HTML/CSS in a single request with signed URLs.
+{: .fs-6 .fw-300 }
+
+<hr>
+
+Table of contents
+{: .text-delta }
+- TOC
+{:toc}
+
+<hr>
+
+{% include hint.md title="Recommendation" text="We recommend using the [standard API endpoint](/getting-started/using-the-api/) for most use cases. Only use this endpoint if you specifically need to generate image URLs from client-side code or need to avoid the two-step create-then-fetch process." %}
+
+## 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.
+
+{% include hint.md title="Security note" text="Never expose your API Key in client-side code. The API ID and generated token are safe to use client-side." %}
+
+## Creating an image
+
+To generate an image with a signed URL, construct a URL with your API ID and token:
+
+<pre class="http-method fs-4">
+  <span>get</span> https://hcti.io<b>/v1/image/create-and-render/:api_id/:token/:format</b>
+</pre>
+
+### URL Components
+
+| Component | Description |
+|:-------------|:------------------|
+| **api_id** | Your public API ID from the dashboard |
+| **token** | HMAC SHA256 hash of the query string using your API Key (see below for how to generate) |
+| **format** | Optional file format: `png` (default), `jpg`, or `webp` |
+
+### Parameters
+
+The parameters are the same as the [standard API endpoint](/getting-started/using-the-api/#parameters), but they must be passed as query parameters in the URL.
+
+| Name        | Type          | Description |
+|:-------------|:------------------|:------|
+| **html**† | `String` | This is the HTML you want to render. You can send an HTML snippet \(`<div>Your content</div>`\) or an entire webpage. |
+| **css** | `String` | The CSS for your image. When using with `url` it will be injected into the page. |
+| **url**† | `String` | The fully qualified URL to a public webpage. When passed this will override the html param and will generate a screenshot of the url. |
+
+{% include hint.md title="Required params" text="† Either `url` OR `html` is required, but not both. `css` is optional." %}
+
+<hr>
+
+### Additional parameters
+
+Optional parameters for greater control over your image.
+
+{% include additional_parameters.md %}
+
+<hr>
+
+### 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](https://www.freeformatter.com/hmac-generator.html):
+
+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
+
+```javascript
+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
+<?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">';
+```
+
+<hr>
+
+### 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
+```
+
+```javascript
+{
+  "error": "Bad Request",
+  "statusCode": 400,
+  "message": "HTML is Required"
+}
+```
+
+```
+STATUS: 401 UNAUTHORIZED
+```
+
+```javascript
+{
+  "error": "Unauthorized",
+  "statusCode": 401,
+  "message": "Invalid token"
+}
+```
+
+{% include code_footer.md version=1 %}