Skip to main content

Photo Recommendations

The API recommends photos for an article, using multiple strategies, and supporting both strict constrains and soft preferences, such as age, format, licence, entities mentioned in the caption, etc.

Basic code common for all the guide pages

Basic code​

To use the API, you need a valid API key with appropriate authorizations. Please get in touch with us if you do not have it here. In the code below, replace <YOUR_API_KEY> with the API key.

Note that we do not provide SDKs for the API yet, but our G3 SDKs can be used to perform NLP analysis.

No special setup necessary

Supported Photo Banks​

First, we need to see which photo banks are available for a given API Key:

curl -X GET -H 'X-API-KEY: <YOUR_API_KEY>' -H 'accept: */*' -H 'content-type: application/json' 'https://media-api.geneea.com/v2/photos'

bash ["ctk", "demo", "shutterstock"]

Recommendation​

We will pick the ctk dataset and recommend photos for the same text as above. The text of the article is submitted in the same way as in semantic tagging: either via title and text fields or using the paraSpecs array (see here.

curl -X POST -H 'X-API-KEY: <YOUR_API_KEY>' -H 'accept: */*' -H 'content-type: application/json' 'https://media-api.geneea.com/v2/photos/ctk/recommend' -d '{
    "id": "1234",
    "title": "Emmanuel Macron in Germany.",
    "text": "Mr. Macron visited a trade show in Munich.",
    "recommendationCount": 2,
    "returnObjects": true,    
    "returnObjectFields": ["name", "description", "url"]
}'

Here is the simplified output:

{
  "id": "1234",
  "referenceKey": "211023-183731-e073c8c0",
  "photosIds": [ "P2021102202885", "P201904290731201" ],
  "photos": [
    {
      "id": "P2021102202885",
      "description": {
        "en": "French President Emmanuel Macron arrives ..."
      },
      "name": { "cs": "Emmanuel Macron" },
      "url": "http://imultimedia.ctk.cz/storage/foto/P2021102202885/515x515.wm/P2021102202885.jpeg"
    },
    {
      "id": "P201904290731201",
      "description": {
        "en": "German Chancellor Angela Merkel welcomes President of France Emmanuel Macron ..."
      },
      "name": { "cs": "Emmanuel Macron, prezident, politik, Angela Merkel ..." },
      "url": "http://imultimedia.ctk.cz/storage/foto/P201904290731201/515x515.wm/P201904290731201.jpeg"
    }
  ],
  "nextCursor":"5bd1c54c12d5070c",
  "tags": [
    {"type": "Geneea", "value": "G3052772", "subType": "person", "description": "Emmanuel Macron (G3052772)", "score": 21.8421387408},
    {"type": "Geneea", "value": "G567", "subType": "person", "description": "Angela Merkel (G567)", "score": 12.1114189616},
    {"type": "Geneea", "value": "G458", "subType": "organization", "description": "European Union (G458)", "score": 14.5874189616},
    {"type": "Geneea", "value": "G64", "subType": "location", "description": "Berlin (G64)", "score": 18.2413894616}
  ]
}

The output is mostly self-explanatory. Tags can be used to further filter the results; see [Constraints](/api_media2/guide/photos.mdx#constraints below.

Paging​

To page through the results, the request must contain an empty cursor ('cursor': '*'):

curl -X POST -H 'X-API-KEY: <YOUR_API_KEY>' -H 'accept: */*' -H 'content-type: application/json' 'https://media-api.geneea.com/v2/photos/ctk/recommend' -d '{
    "id": "1234",
    "title": "Emmanuel Macron in Germany.",
    "text": "Mr. Macron visited a trade show in Munich.",
    "recommendationCount": 2,
    "returnObjects": true,
    "returnObjectFields": ["name", "description", "url"],
    "cursor": "*"
}'

The response then contains a cursor (nextCursor):

{
  "id": "1234",
  "referenceKey": "241013-200942-a453cdba",
  "photosIds": ["P2022100611159", "P201906200639001"],
  "photos": [
    {
      "id": "P2022100611159",
      "description": {"en": "French President Emmanuel Macron attends a news conference at the end of the first day of the European Political Community (EPC), new political grouping at the Prague Castle, Czech Republic, on October 6, 2022. (CTK Photo/Vit Simanek)"},
      "name": {"en": "Emmanuel Macron"},
      "url": "https://fotoarchiv.ctk.cz/geneea/preview/P2022100611159"
    },
    {
      "id": "P201906200639001",
      "description": {"en": "French President Emmanuel Macron comes to an EU summit, on June 20, 2019, in Brussels, Belgium. (CTK Photo/Jakub Dospiva)"},
      "name": {"en": "Emmanuel Macron"},
      "url": "https://fotoarchiv.ctk.cz/geneea/preview/P201906200639001"
    }
  ],
  "tags": [
    { "type": "Geneea", "value": "G3052772", "subType": "person", "description": "Emmanuel Macron", "score": 23.6842774816 },
    { "type": "Geneea", "value": "G193369", "subType": "location", "description": "Prague Castle", "score": 4.9733127066 },
    { "type": "Geneea", "value": "G239", "subType": "location", "description": "Brussels", "score": 4.904134278 },
    { "type": "Geneea", "value": "G458", "subType": "organization", "description": "European Union", "score": 4.0557094808 },
    { "type": "Geneea", "value": "G272281", "subType": "general", "description": "news conference", "score": 3.3702637114 },
    { "type": "Geneea", "value": "G31", "subType": "location", "description": "Belgium", "score": 2.3611396911 },
    { "type": "Geneea", "value": "G82955", "subType": "general", "description": "politician", "score": 1.7318228339 },
    { "type": "Geneea", "value": "G30461", "subType": "general", "description": "president", "score": 1.4457626534 },
    { "type": "Geneea", "value": "G113834800", "subType": "organization", "description": "European Political Community", "score": 1.0 },
    { "type": "Geneea", "value": "G213", "subType": "location", "description": "Czechia", "score": 0.8172601547 }
  ],
  "nextCursor": "5bd1c54ce2dc64f9"
}

Constraints​

The API supports constraining the results in various ways:

  • requiring photos to be shot at certain dates
  • requiring an entity to be mentioned in photo caption or title
  • requiring an entity not to be mentioned in photo caption or title

See the API reference for more detail.

More like this​

An ID of a photo from a recent search can be passed as the parameter of the likePhotoId constraint. A new recommendation is performed searching for similar photos.

curl -X POST -H 'X-API-KEY: <YOUR_API_KEY>' -H 'accept: */*' -H 'content-type: application/json' 'https://media-api.geneea.com/v2/photos/ctk/recommend' -d '{
    "id": "1234",
    "title": "Emmanuel Macron in Germany.",
    "text": "Mr. Macron visited a trade show in Munich.",
    "recommendationCount": 2,
    "returnObjects": true,
    "returnObjectFields": ["name", "description", "url"],
    "constraints": {
        "likePhotoId": "P201904290731201"
    },
}'