Skip to main content
Contact Us Pricing
0

Pond5 API Reference Documentation

Updated on: 2018-01-03

Commands

create_bin
delete_bin
download
get_bin
get_bin_formatted
get_bins
get_cart
get_cart_formatted
get_clip_data
get_clip_data_array
get_downloads_formatted
get_exchange_ratios
get_music_categories
get_sfx_categories
get_versions_formatted
get_video_categories
login
logout
get_active_bin
set_active_bin
modify_active_bin
modify_active_cart
get_cart_total
promo_redeem
purchase_using_cash
purchase_using_credits
purchase_using_subscription
search
userinfo
get_billing_addresses
set_billing_address

Create a media bin

create_bin

Login required: yes

Parameters

array
  • "name" the name of the bin (mandatory)

Returns

array
  • "binid" the id of the bin

Deletes a media bin

delete_bin

Login required: yes

Parameters

array
  • "binid" the id of the bin to delete (mandatory)

Get a direct download link to a purchased item

download

Login required: yes

Parameters

array
  • "bid" the id of the bought item (mandatory)
  • "tr" transaction id (mandatory)
  • "v" the id of the version that actually should be downloaded (mandatory)

Returns

array
  • "url" the direct download link
  • "bid" the id of the bought item (to distinguish item, if several download commands were sent)
  • "tr" transaction id
  • "v" version id

Possible error codes

  • 2 - Arguments are missing
  • 4 - You are not logged in
  • 51 - User is not allowed to download
  • 52 - Problem creating download link

Fetch the content of a media bin, the items as new line / colon separated string

get_bin

Login required: yes

Parameters

array
  • "binid" the id of the bin to fetch, if not provided, the currently selected bin is provided

Returns

array
  • "bin" the bin content, a new line separated string of items. Each item consist of a colon separated string. The entries in the string are (in order):
    • item id
    • unused value
    • price
    • aspect ratio
    • dimension x
    • dimension y
    • video standard
    • aspect quotient
    • sub_offs
    • name
  • "binid" the id of the bin
  • "icon_base" the base url for used for displaying icons

Fetch the content of the current bin, the items as json array

get_bin_formatted

Login required: yes

Parameters

array
  • "binid" the id of the bin to fetch, if not provided, the currently selected bin is provided

Returns

array
  • "items" array containing the items in the bin, of the form:
    • "id" item id
    • "vs" video standard
    • "ox" dimension x
    • "oy" dimension y
    • "ar" aspect ratio
    • "aq" aspect quotient
    • "n" name
    • "pr" price
    • "so" sub_offs
    • "codg" video codec, might differ between versions
    • "coda" audio codec, might differ between versions
  • "binid" the id of the bin
  • "icon_base" base url for icons
  • "flv_base" base url for other data (not icons)
  • "flv_base_encr" base url for other data (not icons), with https if necessary

Get the bins for a user

get_bins

Example how to create an url to a bin icon:

The icon for a specific bin: {icon_base}bin/{id}_icon.jpeg?{gen}

All images that was used for that bin in one image: {icon_base}bin/{id}.png?{gen}

Note that the id must consist of 10 digits, if it has less, prepend leading zeros

Login required: yes

Parameters

none

Returns

array
  • "icon_base" base url for icons
  • "bins" array containing items of the form:
    • "id" the id of the bin
    • "p" integer 0 if private bin, 1 if public bin
    • "tot" number of clips in the bin
    • "gen" counter used to append to the bin icon urls to make sure it is updated
    • "name" name of the bin

Fetch the content of the current cart, the items as new line / colon separated string

get_cart

Login required: yes

Parameters

array
  • "artistinfo" set to 1 to get artist name in result

Returns

array
  • "cart" the cart content, a new line separated string of items. Each item consist of a colon separated string. The entries in the string are (in order):
    • item id
    • unused value
    • price
    • aspect ratio
    • dimension x
    • dimension y
    • video standard
    • aspect quotient
    • sub_offs
    • name
  • "icon_base" the base url for used for displaying icons
  • artistname (optional)

Fetch the content of the current cart, the items as json array

get_cart_formatted

Login required: yes

Parameters

array
  • "artistinfo" set to 1 to get artist name in result

Returns

array
  • "items" array containing the items in the cart, of the form:
    • "id" item id
    • "vs" video standard
    • "ox" dimension x
    • "oy" dimension y
    • "ar" aspect ratio
    • "aq" aspect quotient
    • "n" name
    • "pr" price
    • "so" sub_offs
  • "icon_base" base url for icons
  • "flv_base" base url for other data (not icons)
  • "flv_base_encr" base url for other data (not icons), with https if necessary

Fetch information about a specific clip

get_clip_data

To get the icons, you will use the returned "icon_base", followed by "/" and nine digits (prepended with zeros if the id is shorter as ten digits), followed by _icon.jpeg (in three different variants)

E.g. if the returned icon_base is "http://ec.pond5.com/s3" and your requested id is 590216, the icons will be:

  • http://ec.pond5.com/s3/000590216_icon.jpeg - 120x66
  • http://ec.pond5.com/s3/000590216_iconm.jpeg - 240x134
  • http://ec.pond5.com/s3/000590216_iconl.jpeg - 480x268
  • http://ec.pond5.com/s3/000590216_prevstill.jpeg - 1280x720

For other data, the flv_base is used, and the filename is appended:

  • %09d_prev.m4a
  • %09d_prev_l.flv
  • %09d_prev_xl.flv
  • %09d_anaglyph.flv
  • %09d_main_l.mp4 -- new 264
  • %09d_main_xl.mp4 -- new 264
  • %09d_xl.webm -- new VP8

The last three ones are not always available, so you need to have fallback to old format if it does not exist.

Login required: no

Parameters

array
  • "itemid" the id of the clip (mandatory)

Returns

array
  • "icon_base" base url for icons
  • "flv_base" base url for clips
  • "clip_data" object containing clipdata for this item (not all data is documented yet, so even more data is returned):
    • "id" item id
    • "vs" video standard
    • "ox" dimension x
    • "oy" dimension y
    • "ar" aspect ratio
    • "aq" aspect quotient
    • "ed" is editorial
    • "n" the name of the clip
    • "pic_keywords_cb"
    • "pic_keywords_cb_translated"

Fetch information about several specific clips

get_clip_data_array

Login required: no

Parameters

array
  • "itemids" a comma separated string of ids (mandatory)
  • "col" additional columns of data that should be fetched, a bitmask where the following bits can be set
    • price = 1
    • video codec = 64
    • audio codec = 128
    • artistname = 256
    • 360VR = 1024

Returns

array
  • "icon_base" base url for icons
  • "flv_base" base url for clips
  • "items" array containing items of the form below:
    • "id" item id
    • "vs" video standard
    • "ox" dimension x
    • "oy" dimension y
    • "ar" aspect ratio
    • "aq" aspect quotient
    • "ed" is editorial
    • "n" the name of the clip
    • "pr" the price (if additional column bit set)
    • "artistname" name of the artist (if additional column bit set)
    • "codg" video codec (if additional column bit set), might differ between versions
    • "coda" audio codec (if additional column bit set), might differ between versions
    • "vr360" true if clip is a 360VR file (if additional column bit set)

Fetch the items the user can download, the items as json array

get_downloads_formatted

Login required: yes

Parameters

none

Returns

array
  • "items" array containing vesions containers (see below)
  • "icon_base" base url for icons
  • "flv_base" base url for other data (not icons)
  • "flv_base_encr" base url for other data (not icons), with https if necessary
The version container looks like
  • "bid" the id of the version that was actually bought
  • "sub_offs" only relevant for stock photos
  • "versions" an array containing all the versions of that item the user can download, of the form:
    • "vm" the id of the master item
    • "vs" video standard
    • "ox" dimension x, might differ between versions
    • "oy" dimension y, might differ between versions
    • "ar" aspect ratio
    • "aq" aspect quotient
    • "n" name
    • "pr" price
    • "tr" transaction id
    • "v" version id, if several versions exist, this is what will differ between the versions
    • "exp" info when the download expires, formatted the way the user wants it and in the users time zone
    • "codg" video codec, might differ between versions
    • "coda" audio codec, might differ between versions
    • "ext" file extension
    • "artistname" name of owner
Example:
{ "flv_base" : "http://somecdnhost.somewhere/",
"flv_base_encr" : "http://somecdnhost.somewhere/",
"icon_base" : "http://someothercdnhost.somewhere/",
"items" : [ { "bid" : "62",
"sub_offs" : "0",
"versions" : [ { "aq" : 1.7777799999999999,
"ar" : 1,
"coda" : "pcm_s16be",
"codg" : "dvvideo",
"exp" : "31 Dec 2015 19:00",
"ext" : "mov",
"n" : "happy in the snow",
"ox" : 720,
"oy" : 576,
"pr" : "24",
"tr" : "434",
"v" : "62",
"vm" : 62,
"vs" : 3
},
{ "aq" : 1.7777799999999999,
"ar" : 1,
"coda" : "pcm_s16be",
"codg" : "dvvideo",
"exp" : "31 Dec 2015 19:00",
"ext" : "mov",
"n" : "happy in the snow",
"ox" : 724,
"oy" : 576,
"pr" : "24",
"tr" : "434",
"v" : "185",
"vm" : 62,
"vs" : 3
}
]
},
{ "bid" : "125",
"sub_offs" : "0",
"versions" : [ { "aq" : 1.7777799999999999,
"ar" : 6,
"coda" : "no snd",
"codg" : "h264",
"exp" : "31 Dec 2015 19:00",
"ext" : "mov",
"n" : "happy in the snow",
"ox" : 1440,
"oy" : 1080,
"pr" : "24",
"tr" : "434",
"v" : "125",
"vm" : 62,
"vs" : 2
} ]
}
]
}

Get exchange ratios for available currencies

get_exchange_ratios

Login required: yes

Returns

array
Key is currency code, value is an array in following format:
  • "exchange_ratio" Exchange ratio to 1 USD (local price = USD price * exchange ratio)
  • "rounding_style" How should be the converted price rounded, possible values:
    • 0 = No rounding is applied
    • 1 = Standard rounding (12.3456 = 12.35)
    • 2 = Round up to nearest unit (12.3456 = 13),
    • 3 = Round up to nearest five (12.3456 = 15),
    • 4 = Round up to nearest ten (12.3456 = 20)
  • "price_modifier" Should be added to price after rounding (e.g. if price_modifier = -0.01 and price after rounding is 24, the displayed price should be 23.99)
  • "decimal_points" Number of decimal points displayed to customer

Possible error codes

  • 3 - This api key is not allowed to call this command
  • 107 - There are no available currencies

Fetch all music categories

get_music_categories

Login required: no

Parameters

none

Returns

array
  • "categories" array containing items of the form:
    • "n" name of category
    • "i" id of category

Fetch all sound effect categories

get_sfx_categories

Login required: no

Parameters

none

Returns

array
  • "categories" array containing items of the form:
    • "n" name of category
    • "i" id of category

Fetch formats and version information about an item, return the items as json array

get_versions_formatted

Some clips can exist in different formats, this method will return those different formats and prices Each format can also exist in different versions, if the user buys one item that there exist different versions of, he can download the other versions as well.

An example:

"Format1 Some clip in Pal" => "version11 a version in resolution 720x576", "version12 a version in 724x576"
"Format2 Some clip in Ntsc" => "version21 a version"

If the user buys version12, he can also download version11. If he buys version21, he can only download that version. This method will return a list of all those versions (version11, version12, version21).

Login required: no

Parameters

array
  • "vm" the id of the item to fetch versions for (mandatory)

Returns

array
  • "items" array containing the version information, of the form:
    • "id" item id
    • "ti" title, e.g. "PAL"
    • "tb" sub title
    • "i" additional info
    • "pr" price

Fetch all video categories

get_video_categories

Login required: no

Parameters

none

Returns

array
  • "categories" array containing items of the form:
    • "n" name of category
    • "i" id of category

Login a user

login

Login required: no

Parameters

array
  • "username" (mandatory)
  • "password" (mandatory)

Returns

array
  • "cx" credentials that shall be passed with each command that shall be performed as this user
  • "cm" credentials that shall be passed with each command that shall be performed as this user

Logout a user and invalidiate the cx/cm values

logout

Login required: yes

Parameters

none

Get active bin id

get_active_bin

Login required: yes

Returns

array
  • "binid" id of the active bin

Possible error codes

  • 4 - You are not logged in
  • 101 - No current bin

Set active bin id

set_active_bin

Login required: yes

Parameters

array
  • "binid" id of the bin to set as active

Returns

array
  • "completed" 1 if active bin was set successfully

Possible error codes

  • 1 - General error code
  • 2 - Invalid bin id
  • 4 - You are not logged in

Add / remove items from a bin

modify_active_bin

Login required: yes

Parameters

array
  • "binid" the bin to modify NOTE! Have to be set
  • "addid" a comma separated string of ids to add
  • "rmid" a comma separated string of ids to remove

Returns

array
  • "addid" number of items added
  • "nbr_removed" number of items removed

Add / remove items from the current cart

modify_active_cart

The id is either just id or an id and a sub offset, if a specific format is chosen

The id is of the form {id} or {id}:{sub_offs}

Login required: yes

Parameters

array
  • "addid" a comma separated string of ids to add, for example "123:0,653,234:1"
  • "rmid" a comma separated string of ids to remove

Returns

array
  • "nbr_added" number of items added
  • "nbr_removed" number of items removed
  • "bought_before" (optional) Note: only filled when clips were successfully added! Array of ids of the clips in the cart that the user has bought before (you should inform the user that he already got these clips)
  • "ownclips" (optional) Note: only filled when clips were successfully added! Array of ids of the clips in the cart that the user has uploaded himself (makes no sense to buy them, you should inform the user)

Fetch information about cart amounts

get_cart_total

Login required: yes

Parameters

array
  • "addressid" id of billing address to use to calculate cart total, if not set fallback to default billing address
  • "use_credits" set to 1 to calculate cart total by using credits

Returns

object
  • "subtotals" object cart total information:
    • "beforeDiscounts" cart amount before discounts
    • "afterDiscounts" cart amount after discounts
    • "beforeVat" cart amount before VAT
    • "afterVat" cart amount after VAT
    • "final" final cart amount
  • "discounts" object containg discount related information:
    • "discountAmount" discount amount
    • "discountPercentage" discount percentage
  • "creditsData" object containing credits related information:
    • "usedCredits" item id
    • "usedSum" video standard
    • "availableSum" video standard
    • "remainingSum" video standard
  • "vatData" object containing VAT related information:
    • "percentage" VAT percentage, might be NULL
    • "display" boolean true if VAT should be displayed
    • "amount" VAT amount, might be NULL

Redeem a promo code

promo_redeem

Login required: yes

Parameters

array
  • "promocode" The promo code to reedem

Returns

array
  • "sum" the sum that was added to the account

Possible error codes

  • 1 - General error code
  • 2 - Arguments are missing
  • 3 - This api key is not allowed to call this command
  • 4 - You are not logged in
  • 104 - No valid promo code

!!! CURRENTLY COMPATIBLE ONLY WITH ADOBE PREMIERE PLUGIN !!!

purchase_using_cash

Purchase the items in the cart using cash.

If clips are found in the cart, that the user bought before, or clips the user owns himself, error code 103 will be returned, as well as two arrays containing ids of the clips that are the culprits. If the user after this still wants to buy the clips, you need to pass the "override" argument with the ids of those clips.

Login required: yes

Parameters

array
  • "override" Array of ids. If the user really wants to buy the bought_before / ownclips, all the ids of those clips must be passed in this array
  • "userdata" End user client info as a string. Might be optional or required, depending on API License agreement.
  • "addressid" id of billing address to use during checkout, or use default billing address if omitted
  • "use_credits" set to 1 to purchase by using available credits

Returns

\array<br><ul>
  • "url" URL where to redirect customer in order to do a payment

    • Possible error codes

    • 1 - General error code
    • 3 - This api key is not allowed to call this command
    • 4 - You are not logged in
    • 101 - cart is empty, nothing to purchase
    • 103 - the cart contains clips the user bought before or owns, in this case two arrays "bought_before" and "ownClips" will be returned
    • 106 - user has enough credits to pay for this order - no cash payment required (call purchase_using_credits instead)

    Purchase the items in the cart using prepaid credits

    purchase_using_credits

    If clips are found in the cart, that the user bought before, or clips the user owns himself, error code 103 will be returned, as well as two arrays containing ids of the clips that are the culprits. If the user after this still wants to buy the clips, you need to pass the "override" argument with the ids of those clips.

    Login required: yes

    Parameters

    array
    • "override" Array of ids. if the user really wants to buy the bought_before / ownclips, all the ids of those clips must be passed in this array
    • "userdata" End user client info as a string. Might be optional or required, depending on API License agreement.
  • "addressid" id of billing address to use during checkout, or use default billing address if omitted

    • Returns

    array
    • "completed" 1 if the purchase was performed

    Possible error codes

    • 1 - General error code
    • 2 - Missing required parameter
    • 3 - This api key is not allowed to call this command
    • 4 - You are not logged in
    • 101 - cart is empty, nothing to purchase
    • 102 - the user has not enough credits to buy whats in the cart
    • 103 - the cart contains clips the user bought before or owns, in this case two arrays "bought_before" and "ownClips" will be returned

    Purchase the items in the cart using subscription, one at a time

    purchase_using_subscription

    If a clip is found in the cart, that the user bought before, or a clip the user owns himself, error code 103 will be returned, as well as two arrays containing ids of the clips that are the culprits. If the user after this still wants to buy the clip, you need to pass the "override" argument with the id of that clip. NOTE! To execute this method successfully, you need to have exactly one item in the user's cart.

    Login required: yes

    Parameters

    array
    • "override" Array of ids. if the user really wants to buy the bought_before / ownclips, all the ids of those clips must be passed in this array
    • "userdata" End user client info as a string. Might be optional or required, depending on API License agreement.

    Returns

    array
    • "completed" 1 if the purchase was performed

    Possible error codes

    • 1 - General error code
    • 2 - Missing required parameter
    • 3 - This api key is not allowed to call this command
    • 4 - You are not logged in
    • 101 - cart is empty, nothing to purchase
    • 103 - the cart contains clips the user bought before or owns, in this case two arrays "bought_before" and "ownClips" will be returned

    Perform a search for media

    search

    Default result is limited to non editorial content. If you want to search for editorial content, you need to add "editorial:1" to the query parameter, see advanced search documentation.

    Login required: no

    Parameters

    array
    • "query" string the query to search for, e.g. "car". The format is the same as the normal search field on the site.
    • "bm" integer (bitmask) which media types to search for, defaults to 16,515,135 for all video. Following bits can be set:
      • hd = 1
      • pal = 2
      • ntsc = 4
      • multimedia = 8
      • 4k = 262144
      • 8k = 524288
      • HD 1080i = 1048576
      • HD 720 = 2097152
      • HDV 720p = 4194304
      • other HD = 8388608
      • any video = 16515087
      • music = 16
      • sfx = 32
      • any sound = 48
      • any sound and video = 16515135
      • after effects = 64
      • photos = 128
      • model release = 256
      • matte = 512
      • illustration = 1024
      • filter explicit = 2048
    • "no" number of results wanted per "page", defaults to 25, min value can be 25, max value can be 500
    • "p" which "page" to fetch, starting on 0
    • "sb" define which order the result should be returned in. Can have any of folowing values:
      • default = 1
      • username = 2
      • price = 4
      • duration = 5
      • date uploaded = 6
      • number sales = 8
      • sales revenue = 9
      • number views = 10
      • To reverse result, add 100
    • "col" additional columns of data that should be fetched, a bitmask where the following bits can be set
      • name = 1
      • duration = 2
      • keywords = 4
      • description = 8
      • price = 16
      • fps = 32
      • video codec = 64
      • audio codec = 128
      • artist name = 256
      • filesize = 512
      • 360 VR = 1024
      • sound BPM = 2048
    • "cat" category ids to search within specific categories

    Returns

    array
    • "tot_nbr_rows" total number of items found
    • "max_per_page" number of items per page (i.e. "no")
    • "nbr_footage" total number of video footage found
    • "nbr_music" total number of music items found
    • "nbr_sfx" total number of sound effects found
    • "icon_base" base url for icons
    • "flv_base" base url for other data (not icons)
    • "flv_base_encr" base url for other data (not icons), with https if necessary
    • "items" array containing items of the form:
      • "id" item id
      • "vs" video standard
        • 0 - Multimedia / Unknown
        • 1 - NTSC D1
        • 2 - NTSC DV
        • 3 - PAL / PAL DV
        • 4 - HD 1080
        • 5 - HDV 720p
        • 6 - Other Hi-Def
        • 7 - Multimedia
        • 8 - HDV 1080i
        • 9 - HD 720
        • 10 - 4k
        • 11 - 8k
        • 100 - Music
        • 101 - Sound effect
      • "ox" dimension x, is the original horizontal resolution of the clip (16 for sound)
      • "oy" dimension y, is the original vertical resolution of the clip (9 for sound)
      • "ar" aspect ratio:
        • 1 - 4:3
        • 2 - 16:9 anamorphic
        • 3 - 16:9 letterboxed
        • 4 - Unknown
        • 5 - Other
        • 6 - 16:9 native
      • "aq" aspect quotient
      • "n" name (if additional column bit set)
      • "dur" duration in ms (if additional column bit set)
      • "kw" space separated list of keywords (if additional column bit set), e.g. "dog costume funny parade flowers pets contest"
      • "desc" description (if additional column bit set)
      • "pricerange" array containing two items: lower price and upper price (if additional column bit set)
      • "pr" the price for this specific clip (if additional column bit set)
      • "fps" frames per second (if additional column bit set)
      • "codg" video codec (if additional column bit set), might differ between versions
      • "coda" audio codec (if additional column bit set), might differ between versions
      • "artistname" name of artist (if additional column bit set)
      • "filesize" size of original file (if additional column bit set)
      • "vr360" true if clip is a 360VR file (if additional column bit set)

    Fetch information about the loggedin user

    userinfo

    Login required: yes

    Parameters

    none

    Returns

    array
    • "credit" the amount the user has prepaid and can use for purchases
    • "un" username of the user
    • "fn" first name of the user, '-' will be returned if not available
    • "ln" last name of the user, '-' will be returned if not available
    • "av" path to the avatar, if the user has not avatar, a path to the default avatar will be returned
    • "icon_base" the base url for used for displaying the avatar/icons
    • "user_type" type of the user account, either "standard" or "reseller"

    Get an array of available billing addresses

    get_billing_addresses

    Login required: yes

    Parameters

    none

    Returns

    array
    • containg the following elements:
      • "addressid" id of address
      • "first_name" first name
      • "last_name" last name
      • "street1" street address line 1
      • "street2" street address line 2
      • "city" city
      • "state" U.S. state code
      • "province" province
      • "postal_code" postal (zip) code
      • "country" two character ISO country code
      • "vat_id" VAT ID number
      • "company_id" Company Id number
      • "company_name" company name
      • "company_department" department in company
      • "isdefault" true if this is the default billing address

    Add or update a billing address

    set_billing_address

    Login required: yes

    Parameters

    array
    • "addressid" id of address to modify, omit to add billing address
    • "first_name" first name
    • "last_name" last name
    • "street1" street address line 1
    • "street2" street address line 2
    • "city" city
    • "state" U.S. state code
    • "province" province
    • "postal_code" postal (zip) code
    • "country" two character ISO country code
    • "vat_id" VAT ID number
    • "company_id" Company Id number
    • "company_name" company name
    • "company_department" department in company

    Returns

    array
    • "addressid" id of address added or updated
    Deutsch Español Français Italiano Nederlands Português Русский 한국인 日本語 简体中文