Additional API parameters

Together with your API settings, optional query-string API parameters help you fine-tune what you receive from APIs.

If not given with an API call, your defaults from settings will be used. If you haven't set up and saved your preferences at least once, the default cloud-wide settings will be used.

Required parameters

api_key

The API key you see in your profile. If your code faces users, you may replace api_key with key parameter, which should be the MD5 hash of your actual API key.

See how to restrict API access with your key in that case.

url
URL-encoded value of the URL. Also, make sure it's HTTP or HTTPs link (we suggest you match against /^https?:\/\//i)

Please URL-encode the URLs you send to Iframely. Seriously.

iFrame helpers & features

iframe=1

Explicitely activates our async iFrames.

Embed will be wrapped into Iframely iFrame and include required display helper. The media inside an iFrame will be kept up-to-date in background on our end.

iframe=amp
Formats HTML code output for Accelerated Mobile Pages framework.
iframe=card

Wraps rich media into a summary card. Works for players, images and some apps.

Use &iframe=card-small to insist on a compact card layout.

iframe=0

Disables any required or configured Iframely HTML helpers powered by our iFrames.

You get embed codes from publisher as-is and need to take care of any technical matters yourself. The autoplaying videos will be omitted in oEmbed API response.

id=1

If your plan supports it, or during initial trial period, the parameter adds short ID to the API response. For all cases, including when Iframely returns native embed code from publisher as-is, without hosted iFrame.

You can use those IDs to re-fetch data in batches of up to 100 URLs when you need to refresh the cache.

omit_script=1

Excludes embed.js from HTML codes, if you load it yourself.

It also forces script-based embeds with variable height (say, Twitter and Facebook) be returned as <iframe> instead of <a> element. (useful e.g. for React)

import=0
In Chrome, when embed code has our embed.js script, it may decide to use Web Components instead of iFrames to bulk-insert some embeds and make it even faster. import=0 disables shadow DOM and imports and our script will use iFrame renders only.
omit_css=1

Formats HTML with CSS classnames instead of inline styles.

Lets you fine-tune embed codes via CSS. Makes Twitter and Facebook not cause less flicks on the page.

align=left
Removes default center aligning of Twitter, Facebook, Instagram and other max-width'ed media embeds.
playerjs=1
Activates Player.js events to control players where possible. Requires and is delivered via Iframely iFrame helper.
lazy=1
Activates lazy-loading when Iframely returns an iFrame helper.

Content filters

language=

Accept-Language - default is en-US. Sets rich media interface language for number of publishers. For all publishers, makes Iframely parsers to request HTTP responses in that locale as top choice in accept-language header (many sites render different meta depending on locale).

The parameter value is an ISO 639-1 fully specified locale of two-letter language code and two-letter region code. For example, fr-CA or fr-FR are both valid values. For some languages, Iframely might accept just the two-letter language code and add the default region code automatically.

Please test your locale choice with Twitter, Facebook, YouTube and TED before pushing it live. Instagram should also use either this language, or the one from user's browser.

ssl=1
Returns only embeds that can be used under HTTPs without our iFrame fallbacks and with no active SSL mixed-content warnings (images and mp4 videos trigger only passive warnings and thus will pass this check).
html5=1
Returns only embeds that can be viewed without our iFrame fallbacks on mobile devices or desktops with no Flash plugin installed.
media=1
"Prefer media-only". For some publishers, Iframely knows status-like app embeds AND simple media, such as photos or video. This option will make Iframely return actual media in the html field instead of branded embeds. It affects, for example, Instagram, Tumblr, Imgur, Pinterest (for videos), etc.
media=0
Disables any rich media from a publisher and forces URL to try and resolve into a summary card instead.
autoplay=1
Gives preference to autoplay media and will try to return it as primary html. Check for autoplay in primary rel to verify. Available only with Iframely API endpoint.
maxwidth=
In pixels, returns only embeds that do not exceed the requested width. It affects the rare cases of fixed-width embeds as in most cases Iframely gives the responsive embed code anyway.

maxwidth doesn't restrict the size of responsive media because many WordPress sites have this setting wrong. Use omit_css instead.

maxheight=
In pixels, applies only to responsive rich media with fixed aspect-ratio. Iframely takes maxheight and media's aspect-ratio and calculates the max width that would match your maxheight. We then set the max-width style in HTML output so that responsive media isn't taller than your maxheight.

maxheight is only a helper function for apps with horizontal layout. It doesn't apply to or restrict the size of media that doesn't resize using a fixed aspect-ratio.

Code helpers

origin=

Optional text value tag that will help you later search links in your dashboard. It represents the hashtag to group your links. E.g. project or chat room name, category, app, if you got several, etc.

You may also use it to indicate your end-customer. In that way you'll be able to make a requests to our support to delete all links by such hashtag from your account. It addresses the "right to be forgotten" act in European GDPR.

callback
Name of a JavaScript function, if you’d like response to be wrapped as JSONP.
format=xml
For oEmbed API only, if you'd like to get your response as XML.

For individual embeds publishers

Number of publishers provide different embedding options. By default, Iframely provides embeds that we believe are the best fit for most common use cases. But you, of course, might want it differently.

Most frequently requested adjustments are available for self-service in your settings. For other cases, Iframely team can configure the exact embeds you like for your favourite publishers. Ask away.

For individual URLs

In addition your default account's settings and parameters, your users may toggle the embedding settings for individual URL to get exact variant they need for their specific post.

It is done by adding Iframely's query-string command direclty to the URL itself. Read about "More/Less" toggle and share with your users.

Previous article: Iframely API
Next article: Result codes