How to Create Social Media Preview Images from HTML with CloudConvert

To create a social media preview image from HTML with CloudConvert, render your HTML card as a PNG or JPG with CloudConvert’s Website Screenshot API, publish the resulting image at a stable public URL, then put that URL in your page’s og:image metadata. CloudConvert creates the pixels; Open Graph metadata tells consumers which image represents the page.

CloudConvert documents URL and HTML-file input, headless Chrome rendering, PNG or JPG output, viewport controls, full-page capture, selector waits, and synchronous or asynchronous processing. Its API example creates a capture-website task and exports its output with export/url. Confirm the live API reference for current parameters before deployment: CloudConvert Website Screenshot API and Capture Website API reference.

1. Design the HTML card

Create a dedicated page or document for the image rather than trying to use a full website page as the card. Keep its content and layout intentional: a title, short supporting line, and any visual treatment that identifies the page. Choose the canvas dimensions and composition for the social networks you target. There is no universal dimension established here; the width in CloudConvert’s example is a capture parameter, not a social-platform recommendation.

For dependable rendering, make the document self-contained where practical. If the card references fonts, stylesheets, images, or other assets, ensure they are reachable from the rendering environment and inspect the output for missing resources. CloudConvert supports a deployed URL or an HTML-file input route, but the documented capability does not guarantee every external asset will load in every setup.

2. Capture the card with CloudConvert

The API workflow is useful when you want to automate capture and export as part of a job. The operation and task names below follow CloudConvert’s documented example. Supply the current parameters required by your CloudConvert account and the live API reference. Store the API key in a secret manager or environment variable; do not expose it in client-side code or commit it to a repository.

curl --request POST \
  --url https://api.cloudconvert.com/v2/jobs \
  --header 'Authorization: Bearer YOUR_CLOUDCONVERT_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "tasks": {
      "capture": {
        "operation": "capture-website",
        "url": "https://example.com/social-card.html",
        "output_format": "png",
        "width": 1200
      },
      "export": {
        "operation": "export/url",
        "input": "capture"
      }
    }
  }'

This illustrates the documented job structure, not a promise that every account or current API version accepts an identical request. Consult the live operation reference for authentication, accepted inputs, capture parameters, and job result handling. A job may be asynchronous; your automation should wait for completion and then obtain the exported file URL from the completed export task.

Use an HTML file instead of a deployed URL

CloudConvert also documents an HTML-file input path. Upload or provide the HTML file using the input method supported by the current API, then use the capture-website operation and export tasks as in the URL flow. The exact file import and task fields should be taken from the current API reference. Check whether relative assets are included and resolvable; a local HTML file that depends on files not supplied to the job can render without its styles or images.

Choose capture settings

Output format: CloudConvert documents PNG and JPG output. Select based on the visual content and verify the exported file.
Viewport and width: Set a canvas suitable for your card design. Do not treat CloudConvert’s example width as a universal network requirement.
Full-page capture: Available when the input is a page that needs to be captured beyond its initial viewport. For a purpose-built card, a fixed viewport may be easier to control.
Wait for content: If the target appears after initial load, configure a wait for a CSS selector using the supported capture option. This can make capture timing more reliable, but inspect for layout shifts and missing assets.
Sync or async processing: CloudConvert describes both synchronous and asynchronous processing. Use the mode and job handling appropriate to your integration, and handle completion before publishing the image.

3. Export and publish the image

The example chains capture-website to export/url. Retrieve the completed export result, then copy or store the image in a location with a stable URL that the intended social crawlers can reach. Make sure that URL serves the image itself and that access does not depend on an authenticated browser session.

Keep the image URL stable when possible. If you replace an image while retaining the same URL, a consumer may continue to use a previously fetched copy; platform-specific caching behavior is not established by the sources here. When changing artwork, using a versioned filename is a practical way to give the new file its own URL.

4. Add Open Graph metadata

Place metadata in the page’s HTML <head>. Use an absolute image URL. The Open Graph Protocol defines og:image as the image URL representing the shared object and lists og:title, og:type, og:url, and og:image as core properties. It also documents optional image properties including width, height, and alt text.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example page title</title>
  <meta property="og:title" content="Example page title">
  <meta property="og:type" content="website">
  <meta property="og:url" content="https://example.com/page">
  <meta property="og:image" content="https://example.com/images/page-preview.png">
  <meta property="og:image:alt" content="A description of the preview image">
</head>
<body>
  <h1>Example page</h1>
</body>
</html>

Add og:image:width and og:image:height when you know the actual dimensions of the published image and want to supply the optional structured properties. The Open Graph specification says image alt text should describe the image rather than act as a caption. If you specify multiple values for a property, the specification says the first value is preferred in conflicts. Platform-specific interpretation can vary, so check the current requirements of each destination.

5. Verify the result

Open the exported image and confirm the intended composition, fonts, colors, and assets appear.
Request the published image URL and confirm it is publicly reachable and returns the expected image.
Inspect the page source or rendered HTML to confirm the metadata is in the head and og:image is an absolute URL.
Use the target social platform’s current preview or debugging tools to inspect what it reads. Platform tools and cache behavior were not verified in this guide, so consult current platform documentation.

CloudConvert API or HTML-to-PNG converter?

CloudConvert documents both a Website Screenshot API/job workflow and an HTML-to-PNG web converter. The API is the documented route for automation and task chaining; the web converter is a file conversion route. Choose based on whether you need an automated pipeline, whether your source is a URL or local HTML file, how much control you need over capture timing and viewport, and how you intend to handle the output. The available research does not establish a controlled comparison of their reliability, cost, or rendering fidelity.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF, and the parameter names used by other screenshot APIs also work. See the ScreenshotNeo API docs.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/social-card.html -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com/social-card.html"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com/social-card.html'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Every feature is on every plan. A screenshot service renders the page; you still need to publish the result and set its URL in og:image. Sign up for 1,000 free screenshots a month, with no card.

Troubleshooting

Symptom	Likely cause	What to do
CloudConvert job fails	Invalid or outdated operation parameters, authentication problems, or an unsupported input setup.	Check the job error and current Capture Website API reference; verify the key and the URL or file input configuration.
Export task has no usable image URL	The job or export task has not completed, or the task chain does not reference the capture task correctly.	Wait for job completion, inspect task status and errors, and confirm the export task takes the capture task as input.
Image is blank or incomplete	The page content may not have appeared when capture began, or required CSS, fonts, and images were unavailable.	Wait for a selector that identifies the finished card; ensure assets can be fetched and inspect the result for missing dependencies.
Wrong crop or layout	Viewport dimensions do not match the card composition, or the page layout changes at that viewport.	Set a viewport that matches the designed canvas and review responsive breakpoints. Choose full-page capture only when the whole page is intended.
Preview does not show the generated image	The metadata may be missing, use a relative URL, point to a private image, or the destination may still show a cached preview.	Confirm the absolute `og:image` URL is reachable, inspect the page head, and use the destination’s current preview/debugging workflow.
Preview is cropped unexpectedly	The destination applies platform-specific image handling.	Check that platform’s current image rules and test the actual preview. The sources used here do not establish universal crop or dimension rules.

Performance, reliability, and cost

Rendering a purpose-built card avoids capturing unnecessary page content and makes layout easier to reason about. Keep external dependencies reachable, wait only for the content the design needs, and use asynchronous job handling when your application should not keep a request open while capture finishes. These are integration practices, not measured performance claims.

For reliability, handle capture and export as separate job stages, check each task’s result, and publish only after the exported file is ready. Retain enough job and URL information to diagnose failures. A successful capture does not by itself prove the image is publicly reachable or that a social platform has refreshed its preview.

CloudConvert’s pricing is dynamic and depends on purchase settings; consult its current pricing before estimating recurring volume. The sources do not support a cost or fidelity comparison between CloudConvert’s API and its HTML-to-PNG converter. For ScreenshotNeo, the stated plans are Free with 1,000 shots/month, Starter $5 for 3,000, Growth $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000, and Business $249 for 1,000,000; yearly billing gives two months free. Only clean shots are billed, and each response identifies the page verdict and billing status in headers.

FAQ

Does CloudConvert create the Open Graph metadata?

No. CloudConvert renders and exports the image. Your page must declare the published image URL in og:image.

Can I use a local HTML design?

CloudConvert documents an HTML-file input route. Check the current API instructions for the file import fields and ensure referenced assets are supplied or reachable.

Should I use PNG or JPG?

CloudConvert documents both. Select the output suitable for the card and confirm that the exported file is the format and visual result you intend to publish.

No universal size is established by the sources in this guide. Check the current requirements for each network you target.