How to Generate Social Cards with Cloudinary URL Transformations
Build shareable social cards from Cloudinary images with crop, text, and logo overlays, then add the finished image URL to your page metadata.
To generate a social card with Cloudinary URL transformations, start with an image uploaded to your Cloudinary product environment, resize and crop it to your chosen canvas, then add a text layer and optional logo layer. Use gravity and offsets to position overlays, constrain the text layer width so long titles wrap, and put the resulting image URL in your page’s social image metadata. Cloudinary’s SDK URL helpers can build the URL when you prefer not to encode transformation syntax by hand. See the Cloudinary image transformation documentation and confirm dimensions and preview behavior against the current requirements of each platform you target.
1. Prepare the source image and card content
Upload a background image to your Cloudinary account and note its cloud name and public ID. Choose a short title, an optional subtitle, and, if needed, a logo asset. Keep the text concise: overlay width can wrap long text, but wrapping alone does not guarantee that every title will fit cleanly.
Plan the canvas for the destinations you support. A Cloudinary-hosted guest tutorial uses 1200×627 as a frequently recommended Open Graph example, but that is a dated example, not a universal or currently verified requirement. Check each target platform’s current image dimensions, file constraints, and preview behavior before settling on a shared canvas.
2. Build a card URL with transformations
Cloudinary delivery URLs generally follow this form:
https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id>.<extension>Transformation components are optional and can be chained in order, separated by slashes. For example, this URL resizes and crops a background, then places a text overlay:
https://res.cloudinary.com/demo/image/upload/w_1200,h_627,c_fill,q_auto,f_auto/l_text:Arial_56_bold:Building%20with%20Cloudinary,co_white,g_south_west,x_64,y_56,w_900/fl_layer_apply/v1234567890/social/background.jpgReplace demo, the version, and the public ID with values from your Cloudinary asset. This is a syntax illustration; use an uploaded image and valid values in your own account. The base transformation uses width, height, fill crop, automatic quality, and automatic format. The text layer sets a font, size, weight, white color, placement gravity, offsets, and a width constraint. fl_layer_apply closes and applies the layer in its own URL component.
Text and logo layers
Text overlays use the l_text:<font_family>_<font_size>:<text> form and can take styling options. URL-encode characters in the text that have special meaning in URLs, such as spaces. Constrain width to encourage wrapping for long titles. Test the actual rendered result: fonts, line breaks, offsets, and background contrast affect legibility.
Image overlays use l_... syntax and are also closed with fl_layer_apply. For a logo with a public ID such as brand/logo, use colons in the overlay ID in place of folder slashes. Remote image overlays use l_fetch: followed by a base64-encoded remote URL when constructing the URL directly; Cloudinary SDK helpers can perform that encoding.
https://res.cloudinary.com/<cloud_name>/image/upload/w_1200,h_627,c_fill,q_auto,f_auto/l_text:Arial_56_bold:Building%20with%20Cloudinary,co_white,g_south_west,x_64,y_56,w_900/fl_layer_apply/l_brand:logo,w_140,g_north_east,x_48,y_40/fl_layer_apply/v1234567890/social/background.jpgTransformation syntax and SDK parameter names can differ. Check the documentation for the SDK and version used by your application rather than assuming raw URL components map one-to-one to SDK arguments.
3. Choose URL construction or an SDK helper
| Approach | Good fit | Tradeoff |
|---|---|---|
| Construct the URL directly | You want the full transformation string visible, or need a portable URL example. | You must correctly encode text, remote URLs, separators, and layer boundaries. |
| Generate it with a Cloudinary SDK | Your application already uses a Cloudinary SDK or framework integration. | Argument names and helpers are SDK-specific; consult that SDK’s current documentation. |
Cloudinary SDKs provide URL and image-tag helpers. The first request for a transformed image can create the derived result on demand, and that output is cached on Cloudinary’s CDN. This makes a transformation URL convenient to reuse, while changes to the transformation produce a different derived result.
For example, the following is the general shape of a server-side URL helper call in JavaScript. The exact import and parameter format depend on the installed Cloudinary SDK version; adapt it using that SDK’s documentation:
// Pseudocode: use your installed Cloudinary SDK's URL helper and option names.
const cardUrl = cloudinaryUrl("social/background", {
transformation: [
{ width: 1200, height: 627, crop: "fill", quality: "auto", fetch_format: "auto" },
{ overlay: { text: "Building with Cloudinary", font_family: "Arial", font_size: 56, font_weight: "bold" }, color: "white", gravity: "south_west", x: 64, y: 56, width: 900 },
{ flags: "layer_apply" }
]
});This snippet is intentionally marked as pseudocode, not a drop-in SDK call. Check the installed SDK’s API for valid syntax, especially for overlay text and applying layers.
4. Put the generated image URL in page metadata
Use the generated URL as the social image URL in your page metadata. The exact metadata fields and platform-specific behavior are outside the transformation sources summarized here, so follow the current documentation for your site framework and target services.
<!-- Replace the URL with the generated Cloudinary card URL. -->
<meta property="og:image" content="https://res.cloudinary.com/<cloud_name>/image/upload/...">After deploying the page, inspect the page’s rendered metadata and use the target platform’s current preview or debugging tool. A correct transformation URL does not by itself guarantee that a platform has fetched or refreshed its preview.
5. Handle title length, positioning, and platform differences
- Long titles: Set a text overlay width to wrap text, shorten the title where possible, and verify that it does not collide with other content.
- Positioning: Use gravity to anchor the layer, then adjust horizontal and vertical offsets. Recheck alignment after changing canvas dimensions or text length.
- Logo overlays: Confirm the logo public ID and folder syntax. Use a readable logo size and leave enough margin from the edges.
- Different destinations: Do not assume one dimension or crop works everywhere. Check current platform guidance and inspect the actual preview.
- Remote overlays: Encode the remote URL correctly for
l_fetch:, or use an SDK helper to handle the encoding.
6. Troubleshoot common problems
| Symptom | Likely cause | What to check |
|---|---|---|
| Transformation URL fails or does not produce the intended image | A malformed component, separator, or asset path. | Check the URL structure, transformation order, cloud name, version, and public ID. |
| Text is missing or appears garbled | Text contains URL-sensitive characters or the text-layer syntax is invalid. | Encode the text and verify the l_text component and styling options. |
| Text extends beyond the card | The title is too long or the text layer has no suitable width constraint. | Set a width, shorten the title, and inspect the rendered wrapping. |
| Overlay appears in the wrong place | Gravity or offsets do not match the chosen canvas and layer dimensions. | Adjust gravity and offsets, then regenerate and inspect the output. |
| Logo overlay cannot be found | The overlay ID does not match the asset public ID or folder syntax. | Check the asset ID and use colons rather than slashes for folders in overlay IDs. |
| Remote overlay does not load | The URL after l_fetch: was not encoded as required. |
Base64-encode the remote URL or use the Cloudinary SDK helper. |
| The social preview is stale or differs from the image URL | The platform may still show a previously fetched preview, or page metadata may not reference the new URL. | Inspect deployed metadata and use the platform’s current preview/debugging workflow. |
7. Performance, reliability, and cost considerations
On-demand transformations avoid requiring you to manually create every card variant in advance. The first request can create a derived image, and Cloudinary caches derived output on its CDN. Reuse stable URLs when card content has not changed; when title, logo, or background changes, update the transformation or source asset and verify the resulting URL.
Static prebuilt images and runtime-generated transformations have different operational tradeoffs: prebuilding gives you an artifact to validate before release, while transformations let the URL describe the output. The research sources do not benchmark these approaches or establish their relative costs, so choose based on your rendering workflow and check Cloudinary’s current plan and transformation terms for your account.
8. Or skip the browser setup
If the goal is to capture a live webpage as a shareable image rather than compose a card from a Cloudinary source asset, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It returns a PNG, JPEG, WebP, or PDF from one GET request. See the ScreenshotNeo API documentation for its parameters.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes cookie banners, 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, and paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
9. FAQ
Can I use any image as the background?
Use an image stored in your Cloudinary product environment and confirm you have the rights to use it. The transformation flow described here starts from a hosted source image.
Does the 1200×627 example guarantee a correct preview everywhere?
No. It is an example from a guest tutorial, not a verified universal requirement. Check current guidance for every target platform.
Should I build the URL by hand?
Use raw URL construction when visibility and portability matter; use the SDK when it already fits your application and you want its helpers to handle URL generation and encoding.
