html-to-image-render

HTML to Image

Use this skill when the task is to render a local .html file into an image via the remote html2image API.

Workflow

1. Read the contents of the HTML file from disk.
2. If necessary, first check the interface agreement in references/html-to-image-api.md .
3. Run scripts/render-html-to-image.ts, passing in the input HTML path and the output image path.
4. Confirm that the generated image file has landed at the target location.

Script Description

The built-in script does these things:

• Reads the HTML file as UTF-8
• Calls POST https://html2image.hanfangyuan.cn/api/html2image
• Decodes the returned image_base64
• Writes the image to the local disk

Example:

npx -y tsx skills/html-to-image-render/scripts/render-html-to-image.ts \
  --input ./demo/card.html \
  --output ./out/card.png \
  --element-id card \
  --image-type png

Running this script depends on a locally available npx, and temporarily executes the TypeScript file via npx -y tsx . On the first run it usually downloads tsx。

Parameter Description

Required Parameters

• --input: The input local HTML file path.
• --output: The output image file path.

Optional Parameters

• --element-id: The id of the element to screenshot; pass the raw id value, without #。
• --image-type: Supports png and jpeg。
• --device-scale-factor: Device pixel ratio; the larger it is, the clearer, but the image is usually also larger.
• --viewport-width / --viewport-height: The rendering viewport size.
• --render-wait-ms: Extra waiting time before the screenshot, suitable for waiting for asynchronous resources such as fonts and images.
• --element-padding: When --element-id is specified, the extra margin added to the screenshot area; the default value is 0。

Notes

• The runtime environment requires an available npx。
• If images are used in the HTML, publicly accessible image links must be used; local image paths are not supported.
• The output file extension should be consistent with --image-type .
• Pay attention to whether the size of the actual screenshot area can fully accommodate the target HTML. In particular, when the card width and height are larger than the default viewport, you must explicitly adjust --viewport-width and --viewport-height, to avoid the screenshot being cropped or the image being incomplete.
• Only adjust the viewport and waiting time parameters when the default rendering result does not meet the requirements; however, if the HTML's design size itself is larger than the default viewport, you should first adjust the viewport to be no smaller than the target element size.
• If the interface returns 400, it is usually that the element corresponding to element_id does not exist.
• If the interface returns 422, it is usually an invalid parameter range.