Astro Open Graph Images: Create and Publish Hosted Images

An Astro page needs a public image URL in its Open Graph metadata. With OGMagic, you create the image before publishing, store the returned URL with your content, and pass it to your layout. Social crawlers fetch the saved image without an API key.

This works for a static Astro build and for pages rendered on demand. Image creation belongs in your publishing workflow; the layout below only reads a saved URL.

Step 1: Create and save your image

Get a private API key from API key access. Run this JavaScript on a server or in a publishing script with OGMAGIC_API_KEY set in its environment. Keep the key out of browser code and public frontmatter.

// Run on your server, at build time, or when publishing content.
const response = await fetch("https://www.ogmagic.dev/api/images", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.OGMAGIC_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ title: "My article", template: "gradient-mesh" }),
});
if (!response.ok) throw new Error("Image creation failed");
const image = await response.json();
// Save image.url with your content; use it in og:image and twitter:image.

Store the returned image.url as an ogImage field on your post. You can also create an image in the editor and copy its saved URL. The sample image URL below is a placeholder: replace it with your own returned URL.

Step 2: Add social metadata to an Astro layout

Astro layouts accept props and render their children through a slot. Put the metadata in the document head so crawlers can read it from the server-rendered HTML.

---
// src/layouts/BaseLayout.astro
interface Props {
  title: string;
  description: string;
  ogImage: string;
}
const { title, description, ogImage } = Astro.props;
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{title}</title>
    <meta name="description" content={description} />
    <meta property="og:type" content="website" />
    <meta property="og:title" content={title} />
    <meta property="og:description" content={description} />
    <meta property="og:image" content={ogImage} />
    <meta property="og:image:width" content="1200" />
    <meta property="og:image:height" content="630" />
    <meta name="twitter:card" content="summary_large_image" />
    <meta name="twitter:title" content={title} />
    <meta name="twitter:description" content={description} />
    <meta name="twitter:image" content={ogImage} />
  </head>
  <body><slot /></body>
</html>

Use the dimensions returned by the API if you choose a custom Pro image size. See the Astro layout documentation for layout props and Markdown layout conventions.

Step 3: Pass your saved URL from each page

---
// src/pages/index.astro
import BaseLayout from "../layouts/BaseLayout.astro";
const ogImage = "https://www.ogmagic.dev/images/11111111-1111-4111-8111-111111111111.png";
---
<BaseLayout
  title="My Astro Site"
  description="Notes on building with Astro"
  ogImage={ogImage}
>
  <h1>My Astro Site</h1>
</BaseLayout>

For a blog, add ogImage to your content schema and pass post.data.ogImage to the same layout. Your existing collection loader and page rendering can stay in place. Create a new image when the title or design changes, then update that stored URL and republish the page.

Choose a template for your content

Browse the template library and preview the design in the editor. Pass its ID in the creation request's template field, along with your title, description, and domain. Use accent colors to customize the design; Pro also supports custom dimensions, and the hosted image API documentation lists the supported fields.

Creation, delivery, and caching

Creating an image and delivering it are separate operations. Run the authenticated POST when publishing content, then use the public saved URL for every page view and social share. Repeated identical creation requests reuse the saved image without another generation credit.

If you create images during an Astro build, those API requests take time and depend on API availability. Creating them earlier in your publishing workflow lets the build read stored URLs. Social platforms also cache previews, so inspect the final public page after changing its image.

Verify the published result

Open the published page with the Open Graph checker. Confirm the image URL is public, returns an image, and appears in the page's HTML. Preview layouts may differ between platforms.

Free access includes 50 new hosted images per 30 days and five templates. Pro is €10 / US $12 one-time for 500 new hosted images per 30 days and access to every template. Email access is required to save images.