Skip to main content

General

How do I sign up and get access to the API?​

  1. Create an Alamy customer account if you don't already have one.
  2. Request access to the API.

An account manager will then follow up to discuss your integration and agree the plan that works best for you.

Embargoed Content​

Although embargo is referenced in our API documentation as part of the NinJS standard, we don't currently utilise this field as we do not currently accept content that is embargoed.

Retrieve metadata for a single media item

Which Alamy IDs are supported by the API?​

Alamy API V3 currently supports the following IDs on both the Search and Item endpoint:

  • Sequence - 34337802
  • Reference - BYT662

The download endpoint only supports Sequence

An item's associated ids are returned as part of the response on both the /search and /item endpoints.

// One property of the NinJS response, not a whole document.
"altids": [
  {
    "role": "id",
    "value": "47BDD485-87AE-439D-B2F4-DFC480B16980"
  },
  {
    "role": "seq",
    "value": "34337802"
  },
  {
    "role": "ref",
    "value": "BYT662"
  }
]

Does calling the download endpoint cost money?​

Not immediately, but it is not free either. GET /download/{id} generates a signed URL and is logged as a download against your account; the charge follows when you declare usage of the item. POST /download/{id} is the spend action — it decrements your licence pack. There is no preview or dry-run mode for either.

Search and item metadata calls are free. If you are building an automated client, gate the download endpoints behind an explicit decision to download — see Download in the guidance.

How do I test downloads without affecting production?​

Ask your account manager for a pre-production account alongside your production one. It is usually set up at onboarding if you request it, and can be added later. Only the credentials differ — the same https://api.alamy.com/v3 base URL and the same behaviour — and it comes with a download test quota agreed with your account manager, so you can prove your download path end to end and keep your production download and order history clean for auditing.

The quota is finite, so spend it on the few downloads that prove the path rather than on a test suite that runs on every commit. See Testing without spending production budget.

How to identify a Model Released image?​

When an image is model released, we will present this information on requests made to the GET /item/{id} endpoint as a metadata flag within the 'objects' array.

The following JSON Path would return an empty array if the content is not model released.

$..objects[?(@.rel=='usageDefinedBy' && @.literal=='modelReleased')]

Using JSON Path in NodeJS:

const jp = require('jsonpath');

const test = {
  objects: [
    {
      rel: "affectedBy",
      literal: "blackAndWhite",
      name: "Black and white"
    },
    {
      rel: "usageDefinedBy",
      literal: "modelReleased",
      name: "ModelReleased"
    }
  ]
}

console.log(jp.query(test, '$..objects[?(@.rel==\'usageDefinedBy\' && @.literal==\'modelReleased\')]'));

Click here for more information on the available metadata flags.

How to identify a Property Released image?​

When an image is property released, we will present this information on requests made to the GET /item/{id} endpoint as a metadata flag within the 'objects' array.

The following JSON Path would return an empty array if the content is not property released.

$..objects[?(@.rel=='usageDefinedBy' && @.literal=='propertyReleased')]

Using JSON Path in NodeJS:

const jp = require('jsonpath');

const test = {
  objects: [
    {
      rel: "affectedBy",
      literal: "blackAndWhite",
      name: "Black and white"
    },
    {
      rel: "usageDefinedBy",
      literal: "propertyReleased",
      name: "PropertyReleased"
    }
  ]
}

console.log(jp.query(test, '$..objects[?(@.rel==\'usageDefinedBy\' && @.literal==\'propertyReleased\')]'));

Click here for more information on the available metadata flags.