How to use Urlbox to generate Open Graph social cards

To use Urlbox for Open Graph social cards, render a designed page or HTML snippet into an image, then put the resulting image URL in your page’s og:image metadata. Urlbox documents two ways to do this: embed a configured render link directly in the metadata, or call its JSON API from your server and use the returned render URL. The second approach is useful when you need to send HTML or manage the render in application code. Keep the API project secret on the server.

1. Design the card before rendering

Urlbox renders the URL or HTML you provide; plan the card’s visual content as part of that input. A dedicated card page is useful when its content changes by article, product, or campaign. Keep the important text and imagery within a safe central area so alternate crops do not cut them off.

Choose a target size and format that match where the card will be shown. Urlbox’s thumbnail guide demonstrates 1200×630 for an “og” crop, 1200×675 for a “twitter” crop, and a 400-pixel square crop. These are examples, not universal platform requirements. Confirm the needs of your target platform and design for them.

When adapting one source image to multiple dimensions, decide how it should fit:

• cover fills the output dimensions and crops excess content. Choose a position when the subject should stay anchored to a particular area.
• contain preserves the whole image and may leave a background-filled border.

Urlbox documents width, height, format, crop behavior, and position among its render options. Use the official Urlbox render options documentation to confirm the current parameter syntax for your account and chosen request method.

2. Choose a Urlbox request method

Method	Use it when	Trade-off
Render link	The render can be configured as a URL and embedded directly as the Open Graph image.	It is synchronous and convenient for markup, but you need a render URL that represents the desired output.
JSON API	You need to submit HTML, handle a render in server-side code, or use synchronous or asynchronous job handling.	Your application must make the request and handle the result. Keep the project secret out of browser code.

Urlbox says render links can be embedded in Open Graph tags. Its API documentation describes JSON requests authenticated with a project secret in the Authorization header. Consult the render links documentation and API authentication documentation for current syntax and authentication details.

3. Configure a render link and add Open Graph metadata

First prepare a URL that displays the card design, or use the Urlbox options to render suitable HTML. Configure the render dimensions and format for the target preview, then obtain the render link. Urlbox’s overview specifically describes embedding its render link directly in metadata.

Put the render URL in the document’s head. Replace the example URL with the actual Urlbox render URL you have configured:

<head>
  <meta property="og:title" content="A clear page title">
  <meta property="og:description" content="A short description of the page.">
  <meta property="og:type" content="website">
  <meta property="og:url" content="https://example.com/article">
  <meta property="og:image" content="YOUR_URLBOX_RENDER_URL">
</head>

Use an absolute, publicly reachable render URL in production. Set the title and description to describe the shared page, and ensure the card image corresponds to that page. The render URL itself is the image value; do not place the Urlbox project secret in public HTML.

4. Use the JSON API from a server

Use the API when you need to submit a larger HTML payload or want application code to coordinate rendering. The following examples show the request shape and authentication placement; supply the current endpoint, render options, and response handling from the official Urlbox API documentation. The research material for this article does not establish a specific endpoint path or response schema, so those values are intentionally not guessed.

cURL request pattern

curl -X POST "$URLBOX_API_ENDPOINT" \
  -H "Authorization: YOUR_PROJECT_SECRET" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/card/article-1",
    "width": 1200,
    "height": 630,
    "format": "png"
  }'

Python request pattern

import os
import requests

endpoint = os.environ["URLBOX_API_ENDPOINT"]
secret = os.environ["URLBOX_PROJECT_SECRET"]
payload = {
    "url": "https://example.com/card/article-1",
    "width": 1200,
    "height": 630,
    "format": "png",
}

response = requests.post(
    endpoint,
    headers={
        "Authorization": secret,
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=90,
)
response.raise_for_status()
print(response.headers.get("Content-Type"))
print(response.content[:100])

Node.js request pattern

const endpoint = process.env.URLBOX_API_ENDPOINT;
const secret = process.env.URLBOX_PROJECT_SECRET;

if (!endpoint || !secret) {
  throw new Error('Set URLBOX_API_ENDPOINT and URLBOX_PROJECT_SECRET');
}

const response = await fetch(endpoint, {
  method: 'POST',
  headers: {
    Authorization: secret,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com/card/article-1',
    width: 1200,
    height: 630,
    format: 'png',
  }),
});

if (!response.ok) {
  throw new Error(`Urlbox request failed: ${response.status} ${await response.text()}`);
}

console.log('Content-Type:', response.headers.get('content-type'));

These are request patterns, not a guarantee that every response is a direct image body: follow Urlbox’s current API documentation for whether the selected mode returns an image, a render URL, or an asynchronous status URL. For asynchronous rendering, Urlbox documents a status URL that can be polled and webhook support. Store the final public render URL in your application or metadata after the render is ready.

5. Keep card images fresh without regenerating on every share

Urlbox documents a default 30-day cache for render links, along with ttl and cache-busting options. This can avoid repeatedly regenerating an unchanged card. When the design or content changes, use the documented cache controls to request a fresh render, then update the og:image value if needed.

Avoid forcing a new render for every page load of an embedded image. Urlbox warns that this regenerates the screenshot each time. Prefer a stable render URL and deliberate invalidation when the underlying card changes. If a social platform continues showing an older image, check both the render cache and that platform’s cached preview; verify the current render URL independently before changing metadata.

6. Validate the result

1. Open the card source URL and confirm it renders the intended design at the chosen dimensions.
2. Request the configured Urlbox render URL directly and confirm it returns the expected image.
3. Inspect the published page source and confirm og:image contains the absolute render URL, without credentials.
4. Check that the page title, description, and image describe the same content.
5. After changing the card, apply the documented cache controls and verify the updated render before relying on a social preview.

7. Troubleshooting

Symptom	Likely cause	Fix
The preview has no image	The page has no usable og:image, or its value is not publicly reachable.	Inspect the published HTML head and use the absolute Urlbox render URL. Open that URL directly to verify it returns an image.
The card is cropped incorrectly	The output dimensions, crop mode, or position do not suit the composition.	Set the intended width and height; choose cover or contain deliberately and adjust position. Keep essential content inside the crop-safe area.
Changes do not appear	The render link is cached, or a social platform retains an older preview.	Check the current render directly, use Urlbox’s documented TTL or cache-busting controls when updating it, and refresh the platform preview through its available mechanism.
An API call is unauthorized	The project secret is missing, invalid, or sent in the wrong header format.	Read the current authentication docs, verify the secret server-side, and send it in the documented Authorization header. Do not expose it in frontend code.
The server waits too long or receives a status URL	The render may be asynchronous or take longer than the caller expects.	Use the documented asynchronous flow: retain the returned status URL and poll it or configure a webhook. Avoid assuming a render link is an asynchronous job.
The rendered card looks blank or incomplete	The input URL or HTML may not have loaded the expected design before capture.	Verify the source page itself, its public accessibility, and the configured render options. For a larger HTML workflow, use the API path described by Urlbox.

8. Performance, reliability, and cost considerations

• Rendering strategy: A render link is synchronous and suited to a direct embed. Use asynchronous API handling when your application needs job tracking; Urlbox documents polling through a status URL and webhooks.
• Cache behavior: The documented 30-day default cache can reduce repeat work for stable cards. Set a deliberate TTL or cache-bust when content changes; do not trigger fresh generation on every image request.
• Credential safety: Keep the API project secret in server-side configuration. Never place it in HTML, client JavaScript, or a public repository.
• Cost planning: The reviewed Urlbox sources establish a 7-day free trial, but trial availability and terms can change. Confirm current pricing and trial details on Urlbox’s site before planning a production workload. Avoid inventing a per-render cost without checking the current plan and render settings.

9. Or skip the browser setup

If the card design already exists as a page, ScreenshotNeo can render it with one GET request. See the ScreenshotNeo API documentation for options.

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

ScreenshotNeo accepts cookie banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up free and get 1,000 screenshots a month with no card.

FAQ

Does Urlbox create the card design for me?

The documented workflow renders a URL or HTML you provide. Build the card design in that page or markup, then configure the render.

Can I use a render link directly in og:image?

Yes. Urlbox’s overview explicitly describes embedding a render link in meta tags for Open Graph images.

Should I render each card on every page view?

No. Urlbox warns that forcing fresh renders for each embedded image request regenerates the screenshot. Use caching and invalidate when the card changes.

Can I use one image for several social dimensions?

You can choose output dimensions and crop behavior, and Urlbox’s thumbnail guide demonstrates multiple crops. Check each target platform’s current requirements and keep the composition adaptable.