OpenGraph.ioOpenGraph.io
Log inStart Free
Embed

Universal Embed API

Send any URL, get back embeddable HTML. Known providers pass through natively, pages that publish an oEmbed endpoint are discovered automatically, and everything else returns a hosted card. One call, one response shape, no provider-specific code.

Start Free View DocsTry Playground
GETapi.opengraph.io/api/3.0/oembed
?url=https://example.com/article/how-we-ship
&maxwidth=640
Response 200 OK
type“rich”
source“og_frame”
provider_name“Example”
width640
height360
html“<iframe src="..." />”
1B+URLs processed
1,000sof developers

Powering link previews, metadata extraction, screenshots, Markdown conversion, embeds, and URL intelligence workflows at scale.

How it works

From URL to embed in one request

You do not choose a resolution strategy. Send the URL and the API works down three tiers until it has something embeddable.

01

Send any URL

Pass the target as ?url=https://example.com or as a path-encoded segment. Add maxwidth and maxheight when your layout needs a specific size.

02

We resolve it in three tiers

Known providers are passed straight through. Pages that advertise their own oEmbed endpoint are discovered and fetched. Everything else gets a hosted embed card built from its metadata.

03

Render the html field

One field renders every tier. The source field tells you which path produced the embed, so you can label it, cache it, or style it differently.

Universal coverage

Native embeds when they exist. A card when they do not.

Plain oEmbed works well right up until a URL is not on the provider list, and then it returns nothing useful. That is most of the web. The Embed API closes the gap by building a hosted card from the page metadata, so your rendering code never has to handle an empty response.

  • Every public URL returns embeddable HTML, not an error
  • No provider-specific branching in your own code
  • One response shape across all three resolution tiers
  • Articles, products, and docs pages embed as rich cards
  • User-submitted links stop degrading into bare anchors
  • Broken providers degrade to a card instead of failing the request
Start Free oEmbed compatibility details
youtube.com/watch?v=…
source: native
Provider embedtype: "rich" · html: <iframe …>
example.com/article/…
source: og_frame
Hosted embed cardtype: "rich" · built from OG metadata
Resolution tiers

Three paths to an embed, always labeled

Every successful response carries a source field naming the tier that answered, so you can label embeds in your UI or debug a surprising result without guessing.

source: native

Native provider

The URL matches a known oEmbed provider such as YouTube, Vimeo, TikTok, or Spotify. The provider response is passed through untouched, including its own iframe HTML.

source: discovery

oEmbed discovery

The page advertises an oEmbed endpoint through a discovery link tag. We fetch that endpoint directly, forwarding your sizing hints, and return what it gives us.

source: og_frame

Hosted embed card

No native embed exists. We build a hosted card from the page Open Graph metadata, so a plain article, product, or documentation URL still returns something embeddable.

API response

What comes back

The response is oEmbed-shaped, so existing consumers keep working, with a few additions that make the fallback tier usable.

Embed-ready HTML

A single html field you can drop into your page, whether it came from a native provider or our hosted card.

oEmbed-shaped response

Standard type, width, height, provider_name, and html fields, so existing oEmbed consumers work unchanged.

Resolution source

A source field of native, discovery, or og_frame on every response so you always know which tier answered.

Size control

maxwidth and maxheight are forwarded to native providers and applied to hosted card dimensions.

Preview imagery

Thumbnails and preview images from the target page, used in hosted cards and available to your own UI.

Title and description

Page metadata alongside the embed so you can render context, alt text, or accessible labels.

Stable frame identity

Hosted cards carry an embed_id you can store, refresh, or invalidate through the frame management API.

Structured errors

Failures return a code, message, and stage instead of an opaque string, so retries can be targeted.

Integration

One call, in whatever you already use

Both URL forms work on v1.1 and v3.0. Full parameter reference, proxy options, and error codes live in the API docs.

curlGET /api/3.0/oembed
# Query form (recommended) curl "https://opengraph.io/api/3.0/oembed?url=https://example.com/article&maxwidth=640&app_id=YOUR_API_KEY" # Path-encoded form curl "https://opengraph.io/api/3.0/oembed/https%3A%2F%2Fexample.com%2Farticle?app_id=YOUR_API_KEY"
Trimmed response
type“rich”
source“og_frame”
provider_name“Example”
title“How We Ship”
width640
height360
html“<iframe src="https://frames.opengraph.io/…" />”
embed_id“a1b2c3d4…”
View full API parameters
Use cases

Where a universal embed matters

The pattern is the same wherever URLs arrive from somewhere you do not control: you cannot know in advance whether a native embed exists.

Website embedsMedia embedsLink previewsUser-generated contentCMS embedsInternal dashboardsPublishing toolsSocial cardsFallback embed cardsEmbed code generation

User-generated content

Render a real embed for whatever URL someone pastes into a comment, post, or message, without maintaining a provider allowlist.

CMS and publishing tools

Give editors one paste-a-URL flow that produces consistent embeds across video, social, articles, and internal pages.

Dashboards and internal tools

Turn linked resources into visual cards so a list of URLs becomes scannable instead of a wall of blue text.

AI agents and chat surfaces

Let an agent cite a source and render it as a card, using one call that never needs per-domain handling.

Branding

What the free tier looks like

Worth knowing before you build: branding only ever applies to hosted fallback cards, never to native provider embeds.

Free

Hosted cards carry OpenGraph.io branding

Native and discovery embeds are always unbranded, because they come from the provider. Hosted fallback cards on the free tier include a small OpenGraph.io attribution.

Paid

Unbranded hosted cards

On paid plans the attribution is removed from hosted fallback cards, so embeds match your own product surface. Nothing else about resolution changes.

API comparison

Embed, oEmbed, or Link Preview

The first two are the same endpoint described for different audiences. The third is for when you want the data, not the HTML.

Embed API

Best for universal embeds

Turn any URL into embeddable HTML, with automatic fallback when no native embed exists.

Use when:

You want one call that always returns something renderable, across providers, articles, products, and pages you have never seen before.

You are here

oEmbed API

Best for oEmbed compatibility

The same engine, documented against the oEmbed 1.0 spec and its provider registry.

Use when:

You are replacing an existing oEmbed integration and need the spec-level details: provider coverage, discovery behavior, and parameter compatibility.

View oEmbed API

Link Preview API

Best for preview cards

Metadata for building your own preview card: title, description, image, and domain.

Use when:

You want to render the card yourself in your own components rather than embedding our HTML.

View Link Preview API
Developer experience

Built for URLs you have never seen

One key, one endpoint

No provider registrations, no per-platform API keys, no OAuth dances. Add your app_id and send a URL.

Native and fallback in one shape

Your rendering code reads the same fields whichever tier answered, so there is no branching to maintain.

Try it before you build

The dashboard playground runs real requests against real URLs, including the fallback tier, with a live preview.

Documented parameters

Sizing, theming, proxying, and rendering options are all in the API reference rather than buried in support threads.

Built for untrusted input

Requests to internal and blocked hosts are rejected before fetch, which matters when your users supply the URLs.

Part of URL Intelligence

Pair embeds with metadata, screenshots, Markdown, and extraction when one call is not enough context.

Embed family

Build complete link and embed workflows

The Embed API is part of OpenGraph.io’s Embed family. Pair embed output with link previews, metadata, screenshots, and optimization tools when your workflow needs more than an embed.

Embed product familyoEmbed APIEmbed API docsIframely alternativeEmbedly alternativeMigration guideLink Preview APIOpen Graph MetadataWebsite Screenshot APIOpen Graph Checker

FAQ

It is a single endpoint that turns any public URL into embeddable HTML. Known providers are passed through natively, pages that advertise an oEmbed endpoint are discovered, and everything else gets a hosted card built from its Open Graph metadata. You render the same html field in all three cases.
They are the same endpoint and the same engine. This page describes it as a product: give us a URL, get embeddable HTML. The oEmbed API page documents the same thing against the oEmbed 1.0 spec, covering provider coverage, discovery behavior, and parameter compatibility for teams migrating an existing oEmbed integration.
You get a hosted embed card instead of an error. We build it from the page Open Graph metadata, including title, description, and preview image, and return it in the same html field with source set to og_frame.
Any public URL returns embeddable output. Whether it is a native provider embed or a hosted card depends on the target: native embeds require provider support, and everything else falls back to a card. Internal addresses and blocked hosts are rejected.
Yes. maxwidth and maxheight are forwarded to native providers, passed to discovered oEmbed endpoints, and applied to hosted card dimensions. camelCase maxWidth and maxHeight are accepted too.
Native and discovery embeds are never branded by us, because they come from the provider. Hosted fallback cards include a small OpenGraph.io attribution on the free tier, which is removed on paid plans.
Either form works on both v1.1 and v3.0: pass ?url=https://example.com as a query parameter, or path-encode it as /oembed/https%3A%2F%2Fexample.com. The query form is usually easier for demos and migrations.
Failures return a structured body with success set to false and an error object containing code, message, and stage. The stage tells you where resolution broke down, so you can distinguish a bad URL from a provider outage.

Turn any URL into an embed

One API call returns embeddable HTML for videos, posts, articles, products, and pages you have never seen before. Free requests included.

Start FreeView API Docs

No credit card required. Free requests included.