Next.js OG image: metadata file vs ImageResponse vs hosted API

When to use each Next.js OG image path

Feature comparison

Limits below are from the Next.js and Vercel docs linked in each section. OG Pilot cache behavior is from the API docs. Latency and public list prices stay marked until there is a source.

Recommended OG size on the Vercel side is 1200×630 (Vercel OG Image Generation). ImageResponse defaults to that size too.

Metadata file: opengraph-image and twitter-image

Next.js App Router treats opengraph-image and twitter-image as file conventions. Drop a static .jpg, .jpeg, .png, or .gif in the segment and Next.js adds the meta tags. Put the alt text in opengraph-image.alt.txt or twitter-image.alt.txt. The build fails if a static opengraph-image is over 8MB or a static twitter-image is over 5MB.

A code file (.js, .ts, .tsx) default-exports a function that returns a Response. ImageResponse satisfies that. Optional exports are alt, size, and contentType. Generated images are statically optimized unless they touch request-time APIs or uncached data. generateImageMetadata returns more than one image from the same file. Since Next.js 16, params is a Promise. The convention shipped in v13.3.0.

Source: Next.js opengraph-image.

app/blog/[slug]/opengraph-image.png
app/blog/[slug]/opengraph-image.alt.txt   ← plain text alt

Next.js adds, for that segment:
<meta property="og:image" content="<generated>" />
<meta property="og:image:type" content="<generated>" />
<meta property="og:image:width" content="<generated>" />
<meta property="og:image:height" content="<generated>" />
<meta property="og:image:alt" content="text from the .alt.txt file" />

twitter-image.(jpg|jpeg|png|gif) does the same for twitter:image.
Supported static types: .jpg, .jpeg, .png, .gif.

import { ImageResponse } from "next/og"

export const alt = "Blog post"
export const size = { width: 1200, height: 630 }
export const contentType = "image/png"

// Next.js 16: params is a Promise. On 15 and earlier it is a plain object.
export default async function Image({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)

  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 64,
          background: "white",
          width: "100%",
          height: "100%",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
          padding: 48,
        }}
      >
        {post.title}
      </div>
    ),
    { ...size },
  )
}

You do not also set openGraph.images for a file in the same segment. Next.js already emits the tags. Reach for generateMetadata when the image URL is external, including a hosted API.

ImageResponse and @vercel/og

ImageResponse from next/og uses @vercel/og, Satori, and Resvg to convert JSX into PNG. The default size is 1200×630. Only flexbox and a CSS subset work. display: grid does not. The bundle, including JSX, CSS, fonts, and images, must stay under 500KB. Fonts are ttf, otf, and woff, and ttf or otf parse faster. The supported CSS list lives in Satori.

App Router projects already include @vercel/og. Other frameworks install the package. Vercel documents it as compatible with any framework deployed on Vercel, and as supported on the Node.js runtime. Pages Router plus the Node.js runtime does not support return new Response(…) with vercel/og. App Router with Node.js or Edge, and Pages Router with Edge, do. In production, @vercel/og sets cache-control: public, immutable, no-transform, max-age=31536000. Change the URL when the artwork must change. If crawlers fetch /api/og, allow that path in robots.txt.

Sources: Next.js ImageResponse, Vercel OG Image Generation, @vercel/og API.

// app/api/og/route.tsx
import { ImageResponse } from "next/og"
// App Router includes @vercel/og. No separate install.

export function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const title = searchParams.get("title") ?? "Hello"

  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 56,
          background: "#fff7ed",
          width: "100%",
          height: "100%",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
        }}
      >
        {title}
      </div>
    ),
    { width: 1200, height: 630 },
  )
}

// app/blog/[slug]/page.tsx — point metadata at the absolute URL
export async function generateMetadata() {
  const ogImage = "https://example.com/api/og?title=Hello"
  return {
    openGraph: { images: [ogImage] },
    twitter: { card: "summary_large_image", images: [ogImage] },
  }
}

When a hosted OG image API wins

OG Pilot returns a CDN URL you place in og:image. Signing stays on your server: the JavaScript SDK reads OG_PILOT_API_KEY and OG_PILOT_DOMAIN, signs a JWT, and createImage returns the URL. buildPathFromNextProps fills the path claim from App Router props. Pass iat when you want the documented 24-hour cache window. Omit it and the cache does not expire on its own. Social crawlers then fetch the image from the CDN, which is the caching model for multi-framework sites that are not on Vercel.

• Same templates on Next.js, Rails, Astro, Python, PHP, and WordPress.
• Design stays in templates (blog_post, product, page, and others) instead of a 500KB Satori bundle.
• Agents call the remote MCP endpoint. Install steps: /docs/mcp.

Source: https://ogpilot.com/docs. The same API is what the Rails and Astro guides use. WordPress sites can use the plugin instead of generateMetadata.

import { buildPathFromNextProps, configure, createImage } from "og-pilot-js"

configure((config) => {
  config.apiKey = process.env.OG_PILOT_API_KEY
  config.domain = process.env.OG_PILOT_DOMAIN
})

export async function generateMetadata(props) {
  const path = await buildPathFromNextProps("/blog/[slug]", props)
  const ogImage = await createImage(
    {
      template: "blog_post",
      title: "Post title",
      description: "Post excerpt",
    },
    { path, iat: Date.now() },
  )

  return {
    openGraph: { images: [ogImage] },
    twitter: { card: "summary_large_image", images: [ogImage] },
  }
}

POST https://ogpilot.com/api/v1/images
Content-Type: application/json

{"token":"YOUR_JWT_TOKEN"}

Keep the API key out of client components. Prefer the SDK over hand-rolled JWT signing.

MCP install pointer

The remote endpoint is https://ogpilot.com/mcp. Documented tools include generate_og_image, debug_open_graph, compress_image, and extract_color_palette. Connector JSON differs by client, so follow /docs/mcp instead of a guessed config. After you publish a card, check it in the Open Graph debugger.

Remote MCP URL: https://ogpilot.com/mcp
Docs: https://ogpilot.com/docs/mcp
OAuth: follow the custom connector guide on /docs/mcp (OAuth 2.1 + PKCE)

Latency and cost — labeled, not invented

• Latency: NEED VERIFY. Time a metadata-file hit, a Vercel function region, and an OG Pilot CDN URL on your own pages. A warm social cache is a different number from the first fetch.
• Cost: NEED CITE. Function and bandwidth prices belong to your host's pricing page. OG Pilot plans are shown in billing after signup. This page does not publish a cost per 1,000 images.
• Engineering cost is the part the matrix cannot price: Satori CSS, font subsetting, and the 500KB cap versus a template you do not host.

Decision checklist

1. One unchanging card for the segment? Add a static opengraph-image file and an alt text file.
2. Card follows the route, and Next.js should write the tags? Use opengraph-image.tsx.
3. Many routes, one JSX layout, still on Next.js? Use a Route Handler and generateMetadata.
4. More than one framework, a non-Vercel host, or an agent? Use the hosted API and MCP.
5. Put an absolute og:image URL in the HTML, then re-scrape after the artwork changes.

Next.js OG image questions