Skip to main content

Photo Recommendations

The API recommends photos for an article using multiple strategies. It supports both *strict constrains and soft preferences—such as age, format, license type, and entities mentioned in the photo caption or metadata.

Basic code common to all guide pages

Basic Code​

To use the API, you'll need a valid API key with the appropriate permissions. If you don't have one, please contact us here.

In the code below, replace <YOUR_API_KEY> with your actual API key.

Note: We do not currently provide dedicated SDKs for this API, but our G3 SDKs can be used to perform NLP analysis.

# No special setup necessary

Supported Photo Banks​

Before requesting recommendations, you may want to check which photo banks are available for your 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​

Let's use the ctk dataset to recommend photos based on a given article. The input format is the same as in semantic tagging: either use the title and text fields or the paraSpecs array (see semantic tagging docs).

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's an example of the simplified response:

{
  "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. You can apply additional filters using tags (see Constraints below).

Paging​

To paginate through results, include a cursor in the request. Use 'cursor': '*' to retrieve the first page of results explicitly.

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 includes a field nextCursor, which can be used to request the next page:

{
  "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​

You can apply constraints to filter or influence the recommendation results. Examples include:

  • Require photos taken on specific dates
  • Require that an entity appears in the photo's title or caption
  • Exclude photos that mention certain entities

See the PhotoConstraints API reference for the complete list of supported constraints.

More Like This​

You can request photos similar to a previously returned photo by passing it ID in the likePhotoId constraint.

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"
    },
}'