API Reference

Developer Documentation

Everything you need to integrate Metaframe's high-speed Satori edge engine natively into your tech stack. Build, secure, and deliver dynamic Open Graph images in milliseconds.

Authentication & Endpoint

All requests execute through our Vercel Edge Runtime pipeline. You authenticate by passing your strict API key securely as a query parameter.

Base URL (GET)

GET https://metaframe.dev/api/og/generate?title=Hello&key=mf_live_123

Query Parameters

Control the dynamic payload of your images. Formatting (layouts, logos, colors) is handled securely in your backend dashboard.

Parameter	Type	Description
key *	string	Your environment API key (determines config & quota).
title	string	The primary bold header embedded in the layout.
desc	string	A secondary subtitle string for additional context.

AI IDE Integration

Using Cursor, Windsurf, Claude Code, GitHub Copilot, Gemini CLI, or any other agent IDE? Skip the manual wiring. Copy the prompt below and paste it directly into your agent — it will write the entire integration for you in seconds.

One-Prompt Integration · Compatible with all Agent IDEs

I am integrating Metaframe for high-performance Open Graph image generation.
Please update my Next.js App Router layout to export a `generateMetadata` function.

Requirements:
1. The Open Graph API route is `https://metaframe.dev/api/og/generate`.
2. Append query parameters for dynamic generation: `title` (URI encoded) and `key`.
3. Use my Metaframe API Key for the `key` parameter — find it in your Metaframe dashboard at metaframe.dev/dashboard.
4. Do not install any headless browser libraries; Metaframe natively handles the Satori edge rendering.
5. Set the standard `width: 1200, height: 630` parameters inside the openGraph metadata images array.
6. For each dynamic page, encode the page title using encodeURIComponent() before appending it.
7. Return the fully formed metadata object.

CursorWindsurfClaude CodeGitHub CopilotGemini CLICodexVS Code AgentAntigravityGooseOpenCode

Manual Integration Snippets

Prefer to write it yourself? Generate dynamic links inside your application framework. Always properly encode dynamic data passing into the parameters.

Next.js (App Router Metadata)

export async function generateMetadata({ params }) {const dynamicTitle = await fetchTitle(params.slug);const encodedTitle = encodeURIComponent(dynamicTitle);return {openGraph: {images: [{url: `https://metaframe.dev/api/og/generate?title=\${encodedTitle}&key=mf_live_your_key`,}],},};}

Standard HTML

<meta property="og:image" content="https://metaframe(...)key=mf_live"/> <meta name="twitter:image" content="https://metaframe(...)key=mf_live"/>

Rate Limiting

To preserve edge stability, all endpoints are strictly rate protected by Upstash Redis sliding window limits.

Free Tier: 50 requests / 10 seconds
Pro Tier: 250 requests / 10 seconds
Returns HTTP 429 Too Many Requests

Error Handling

If an image generation fails, the API does not return JSON. Instead, it returns an explicit error image payload directly to the browser.

401Missing or Invalid API Key
402Max Monthly Quota Reached
500Edge Runtime Failure