Pixorial's oEmbed Documentation

oEmbed is an open standard for embedding content into a website. You can use the Pixorial URL of any Video to get the embed code for the Video. To get started you can view an example response for a Pixorial URL or read the rest of the documentation.

URL Scheme

The following URL scheme defines what urls are supported by this endpoint.

http://www.pixtorial.com/*/*

Example Calls

http://pixorial.embed.ly/1/oembed?url=:url&maxwidth=:maxwidth&format=:format

http://pixorial.embed.ly/1/oembed?urls=:url1,:url2,:url3&maxwidth=:maxwidth&format=:format

Response Explorer

To get an idea of how you can use Pixorial's oEmbed API we recommend trying a few urls out in the response explorer. Here are a few example calls to get started

Query Arguments

url

The URL is to retrieve embedding information. This URL must be escaped to insure that Pixorial retrieves the correct link. For example, this Pixorial URL:


http://www.pixorial.com/watch/0c8691f3ec479992985ac2f3b583655e

Should be sent as:


http%3A//www.pixorial.com/watch/0c8691f3ec479992985ac2f3b583655e

In Javascript this is as easy as using the escape function.

urls

A comma separated list of urls for Pixorial to process. Each URL must be escaped, but commas separating URLS must NOT be URL encoded. For example, the request for:


var urls = ['http://www.pixorial.com/watch/0c8691f3ec479992985ac2f3b583655e', 'http://www.pixorial.com/watch/01408022f949711aa97cd62f81b8fe0c', 'http://www.pixorial.com/watch/08b5250e09a1db442edc65487fb837d8']

would be:


http%3A//www.pixorial.com/watch/0c8691f3ec479992985ac2f3b583655e,http%3A//www.pixorial.com/watch/01408022f949711aa97cd62f81b8fe0c,http%3A//www.pixorial.com/watch/08b5250e09a1db442edc65487fb837d8

We can obtain this path in Javascript by using:


urls.map(escape).join(',')

urls accepts a maximum of 20 urls at a time. Pixorial processes these urls in parallel, therefore, it's much quicker to use urls for batched processing.

maxwidth (optional)

This is the maximum width of the embed in pixels. maxwidth is used for scaling down embeds so they fit into a certain width. If the container for an embed is 500px you should pass maxwidth=500 in the query parameters. It is highly recommended that developers pass a maxwidth to Pixorial.

maxheight (optional)

This is the maximum height of the embed in pixels. Functions the same as maxwidth, but for the height of the embed instead. It's noteworthy that maxwidth is preferred over maxheight.

format (optional)

The response format -- Accepted values: (xml, json)

callback (optional)

Returns a (jsonp) response format. The callback is the name of the javascript function to execute.

wmode (optional)

Will append the wmode value to the flash object. Possible values include window, opaque and transparent. For more information view Adobe's documentation.

autoplay (optional)

This will tell the video/rich media to automatically play when the media is loaded. Accepted values: (true, false) Default: false

oEmbed Type

video: This is a playable video.
error: When accessing multiple urls at once, Pixorial will not throw HTTP errors as normal. Instead it will return an 'error' type response that includes the url, error_message and error_code attributes.

Response

type: The resource type. Valid values, along with value-specific parameters are described below.
version: The oEmbed version number. This must be 1.0.
title: A text title describing the resource.
author_name: The name of the author/owner of the resource.
author_url: A URL for the author/owner of the resource.
provider_name: The name of the resource provider.
provider_url: The url of the resource provider.
cache_age: The suggested cache lifetime for this resource, in seconds. Consumers may choose to ignore this value.
thumbnail_url: A URL to a thumbnail image representing the resource. The thumbnail must respect any maxwidth and maxheight parameters. If this parameter is present, thumbnail_width and thumbnail_height must also be present.
thumbnail_width: The width of the optional thumbnail. If this parameter is present, thumbnail_url and thumbnail_height must also be present.
thumbnail_height: The height of the optional thumbnail. If this parameter is present, thumbnail_url and thumbnail_width must also be present.
description: We support and pass back a description for all oEmbed types.

The `video` type

This type is used for representing playable videos. The following parameters are defined:

html (required): The HTML required to embed a video player. The HTML should have no padding or margins. Consumers may wish to load the HTML in an off-domain iframe to avoid XSS vulnerabilities.
width: The width in pixels required to display the HTML. If not supplied the HTML returned will expand horizontally to the size of its parent container.
height: The height in pixels required to display the HTML. If not supplied the HTML returned will expand vertically to the size of its parent container.

Error Codes

400 Bad Request

Required "url" parameter is missing.
Either "url" or "urls" parameter is reqiured.
Invalid URL format.
Invalid "maxheight" parameter.
Invalid "maxwidth" parameter.

401 Unauthorized

The specified URL contains a private (non-public) resource. The consumer should provide a link directly to the resource instead of any embedding any extra information, and rely on the provider to provide access control.

404 Not Found

The provider has no response for the requested url parameter

501 Not Implemented

Not implemented for format: acceptable values are {json or xml}.