OpenGraph.ioOpenGraph.io
Log inStart Free
Embed

oEmbed API: Compatibility, Coverage, and Discovery

An oEmbed 1.0 compatible endpoint backed by the official provider registry, with oEmbed discovery for pages that publish their own endpoint and a hosted fallback card for everything else. This page covers what resolves natively, how discovery behaves, and which parameters map to the spec. For the product overview, see the Embed API.

Start Free View DocsTry Playground
GETapi.opengraph.io/api/3.0/oembed
url=https://youtube.com/watch?v=dQw4w9WgXcQ
maxwidth=640
Response 200 OK
type“rich”
source“native”
provider_name“YouTube”
width640
height480
html“<iframe src="..." />”
1B+URLs processed
1,000sof developers

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

Provider support

What resolves natively

The native tier matches against the official oEmbed provider registry rather than a hand-maintained allowlist, so provider coverage tracks the spec.

320+ registered providers

The native tier matches URLs against the official oEmbed provider registry, so anything in the registry resolves natively without us adding it by hand.

Scheme-level URL matching

Each provider declares URL schemes and we match against them, so a provider that serves several URL shapes (watch pages, short links, embed paths) resolves on all of them.

Response passed through untouched

When a provider answers, you get its own payload and its own iframe HTML. We do not rewrite the embed, so provider features and players behave exactly as documented.

Sizing hints forwarded

maxwidth and maxheight are appended to the provider request, so the provider itself decides the returned dimensions rather than us scaling its markup.

Broken providers degrade

A deleted video, a rate limit, an HTML error page, or a non-JSON body does not fail your request. Resolution falls through to the hosted card instead.

Commonly asked for

YouTube, Vimeo, TikTok, X/Twitter, Spotify, SoundCloud, Instagram, Reddit, Figma, CodePen, CodeSandbox, Flickr, GIPHY, SlideShare, Dailymotion, Canva, and Kickstarter are all registry providers.

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

Pages that publish their own oEmbed endpoint

The spec lets any page advertise an oEmbed endpoint in its head, which covers providers that never registered. We follow those links when the registry has no match.

What we look for

A link tag in the page head with type="application/json+oembed". This is the mechanism the oEmbed spec defines for providers that are not in the registry.

When it runs

Only after the native tier finds no registry match. A registry provider is never fetched twice, so discovery costs nothing on the common path.

Sizing hints are merged in

maxwidth and maxheight are merged into the discovered endpoint URL, preserving any query string the page already put there.

XML discovery is not used

We request the JSON variant only. A page that advertises just the XML endpoint falls through to the hosted card rather than returning an XML payload.

Labeled in the response

Discovery results come back with source set to discovery, so you can tell a self-hosted provider embed apart from a registry one.

Failures fall through

An unreachable or malformed discovery endpoint behaves like no endpoint at all: you get the hosted card instead of an error.

API response

Native embeds and fallback cards from one URL

Send a URL and receive embeddable output your application can display, store, or transform into a rich link experience.

Native oEmbed response

Return provider-supported oEmbed data when the URL supports native embeds.

Embed HTML

Use embed-ready HTML when available from supported providers like YouTube, Vimeo, and others.

Fallback embed card

Generate a rich fallback card when a URL does not support native oEmbed.

Title and description

Use page metadata to provide context around the embedded URL.

Preview image

Display a visual thumbnail or preview image alongside the embed when available.

Source indicator

Every response includes a source field (native, discovery, or og_frame) so you know which resolver tier produced the embed.

URL metadata

Use normalized URL data to build consistent embed experiences across providers.

Developer-ready response

Receive structured output that your application can render, save, or pass into other workflows.

API comparison

Choose the right Embed workflow

oEmbed, Embed, and Link Preview can sound similar. Here is how to know which fits your use case.

oEmbed API

Best for oEmbed compatibility

Spec-level detail: provider coverage, discovery behavior, and parameter compatibility.

Use when:

You are replacing an existing oEmbed integration, or you need to know exactly how a given URL will resolve before you ship.

You are here

Embed API

Best for universal embeds

The same endpoint, described as a product: send a URL, render the html field.

Use when:

You are starting fresh and want the overview rather than the spec details.

View Embed API

Link Preview API

Best for preview cards

Generate rich link previews with title, description, image, domain, and metadata.

Use when:

You need preview card data to render yourself instead of embeddable HTML.

View Link Preview API
Universal coverage

Native oEmbed when possible. Fallback embeds when not.

Standard oEmbed works well when a provider supports it. The problem is that many URLs do not return usable oEmbed data. OpenGraph.io helps fill that gap by generating rich fallback embed cards from metadata, images, and preview data when native oEmbed is not available.

  • Use native oEmbed responses for supported providers
  • Generate fallback embed cards for unsupported URLs
  • Avoid writing provider-specific embed logic
  • Display useful context even when a URL lacks oEmbed support
  • Support media, articles, webpages, and shared links
  • Keep user-submitted URLs from becoming plain, empty links
  • Pair embeds with metadata, previews, and screenshots when needed
Start Free View Docs
youtube.com/watch?v=…
source: native
Provider embedtype: "rich" · html: <iframe …>
example.com/article/…
source: og_frame
Fallback embed cardtype: "hybridEmbed" · OG metadata
How it works

From URL to embed in seconds

01

Send a URL

Pass any public URL via path or ?url= query parameter. Optionally set maxwidth and maxheight for layout control.

02

Three-tier resolution

OpenGraph.io checks native oEmbed providers, then oEmbed discovery links, then generates a hosted fallback card. The source field tells you which tier resolved the embed.

03

Receive embed-ready output

Use the html field to render a native embed or fallback card. Structured errors with code and stage when resolution fails.

Resolution tiers

Three paths to an embed, always labeled

Every response includes a source field so you know exactly how the embed was resolved. Broken native providers gracefully degrade to the fallback frame.

source: native

Native provider

The URL matches a known oEmbed provider such as YouTube or Vimeo. The native embed is passed through.

source: discovery

oEmbed discovery

The page advertises an oEmbed endpoint via a discovery link tag. We fetch and return it.

source: og_frame

Hosted fallback frame

No native embed exists. A hosted preview card is generated from the page OpenGraph metadata.

API parameters

oEmbed-compatible options built in

Pass URLs the way that fits your integration. Control sizing. Read structured errors when resolution fails.

url query parameter

Pass the target URL as ?url= instead of a path segment. Easier for demos, migrations, and playground integrations.

maxwidth / maxheight

Standard oEmbed sizing hints forwarded to native providers and applied to fallback frame dimensions.

source field

Responses include source: native | discovery | og_frame so you can label embeds and debug resolution paths.

theme & template

Customize fallback card appearance with theme=light|dark|auto and template=default|compact for card vs banner layouts.

Full API reference
Errors

Failures tell you where they happened

Errors return success: false with a code, message, and stage, so a bad URL is distinguishable from a provider outage without parsing strings. See the error handling guide for status codes and retry strategy across all endpoints.

400 · invalid_request

The URL was missing, undecodable, pointed at an internal address, or was otherwise rejected before any fetch. stage is validation.

422 · oembed_resolution_failed

No native embed, no discovery endpoint, and not enough page metadata to build a card.

502 · frame_generation_failed

The hosted frame service could not produce a card. Retryable.

Developer experience

Built for developers embedding user-submitted URLs

Simple API access

Start with an API key and generate embed-ready output from URLs without provider-specific setup.

Native and fallback behavior

Use native oEmbed when available and fallback cards when it is not. One endpoint covers both.

Docs when you need them

Implementation details live in the docs so this page stays focused on product fit.

Free requests to start

Test real URLs before using embeds in production workflows.

Works with user-generated content

Render useful previews for links submitted by users, editors, customers, or internal teams.

Part of URL Intelligence

Pair embeds with previews, metadata, screenshots, extraction, and audits when your workflow needs more context.

Embed family

Build complete link and embed workflows

The oEmbed 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 a native provider embed.

Embed product familyEmbed APIIframely alternativeEmbedly alternativeMigration guideLink Preview APIOpen Graph MetadataWebsite Screenshot APIMeta Tag GeneratorOpen Graph Checker

FAQ

An oEmbed API lets developers send a URL and receive structured embed data that can be used to display embedded content inside an app or website, without writing provider-specific logic.
OpenGraph.io generates a fallback embed card using Open Graph metadata, preview images, and URL data when native oEmbed is not available. This means every public URL gets useful embed output instead of an error.
They are the same endpoint. This page documents it against the oEmbed 1.0 spec, covering provider coverage, discovery behavior, parameter compatibility, and error codes, which is what you need when migrating an existing oEmbed integration. The Embed API page describes the same endpoint as a product for teams starting fresh.
Matching is done against the official oEmbed provider registry, which is over 320 providers, so coverage tracks the registry rather than a list we maintain by hand. YouTube, Vimeo, TikTok, X/Twitter, Spotify, SoundCloud, Instagram, Reddit, Figma, CodePen, Flickr, GIPHY, SlideShare, and Dailymotion are all included.
Yes. When a URL has no registry match, we look for a link tag in the page head with type="application/json+oembed" and fetch that endpoint, forwarding your maxwidth and maxheight. Only the JSON variant is used; a page advertising only an XML endpoint falls through to the hosted card.
The oEmbed API returns embed-ready output including native iframe HTML for supported providers. The Link Preview API returns rich preview cards with title, description, image, domain, and metadata, useful for showing link context rather than embedding content.
You can generate embed-ready or fallback output from many public URLs. Native embeds depend on provider support, while fallback cards can display useful context from Open Graph data when native oEmbed is not available.
The API can support automated embed-generation workflows inside your application. An embed code generator is usually for one-off manual embed creation, while this API is designed for products, CMS platforms, and applications that need to handle many URLs programmatically.
Yes. In addition to the path-encoded form (/oembed/{encoded_url}), you can pass the target as ?url=https://example.com. Both forms are supported on v1.1 and v3.0.
Every successful response includes a source field indicating which resolver tier produced the embed: native (known provider), discovery (page-advertised oEmbed link), or og_frame (hosted OpenGraph fallback card).
Full documentation, including request parameters, response schema, fallback behavior, and code examples, is available in the API reference.

Start generating universal link embeds

Use OpenGraph.io to generate native oEmbed responses, fallback embed cards, and embed-ready URL output for apps, CMS platforms, dashboards, and user-generated content workflows.

Start FreeView Docs

No credit card required. Free requests included.