Photo Recommender API

Overview

The Photo Recommender API provides endpoints for recommending relevant photos for articles from supported photo banks.

Endpoints

Endpoint	Description
	Request	200 Response
GET /v2/photos	Lists supported photo banks.
		List[string]
POST /v2/photos/{dataset}/recommend	Recommends photos for a given article.
	PhotosRequest	PhotosRecommendation
POST /v2/photos/{dataset}/recommend/feedback	Sends feedback on a specific photo recommendation.
	RecommendFeedback

GET /v2/photos

Lists supported photo banks.

• Request: (empty)
• Response: List[string]

Example

List photo banks

Request

cURL

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

cURL (Windows)

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

JavaScript

const photos = async (config) => {
    const response = await axios.get('photos', config);
    return response.data;
};

photos(config).then(report);

Python

def photos():
    return requests.get(f'{BASE_URL}photos', headers=HEADERS).json()

photos()

Response

cURL

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

cURL (Windows)

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

JavaScript

javascript ['ctk', 'demo', 'shutterstock']

Python

python ['ctk', 'demo', 'shutterstock']

POST /v2/photos/{dataset}/recommend

Recommends photos for a given article.

• Request: PhotosRequest
• Response: PhotosRecommendation

Example

Recommend photos

Request

cURL

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

cURL (Windows)

curl -X POST -H "X-API-KEY: <YOUR_API_KEY>"  -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\"]
}"

JavaScript

const recommendPhotos = async (input, dataset, config) => {
    const response = await axios.post(`photos/${dataset}/recommend`, input, config)
    return response.data
};

const dataset = 'ctk';
const input = {
    id: '1234',
    title: 'Emmanuel Macron in Germany.',
    text: 'Mr. Macron visited Berlin.',
    recommendationCount: 2,
    returnObjects: true,    // Return PhotoData objects in addition to the photo IDs.
    returnObjectFields: ['name', 'description', 'url'],
};

recommendPhotos(input, dataset, config).then(report);

Python

def recommendPhotos(dataset: str, input: Mapping[str, Any]):
    return requests.post(f'{BASE_URL}photos/{dataset}/recommend', json=input, headers=HEADERS).json()

dataset = 'ctk'
input = {
    'id': '1234',
    'title': 'Emmanuel Macron in Germany.',
    'text': 'Mr. Macron visited Berlin.',
    'recommendationCount': 5,
    'returnObjects': True,    # Return PhotoData objects in addition to the photo IDs.
    'returnObjectFields': ['name', 'description', 'url'],
};

recommendPhotos(dataset, input)

Response

cURL

{
  "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}
  ]
}

cURL (Windows)

{
  "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}
  ]
}

JavaScript

{
  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}
  ]
}

Python

{
  '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}
  ]
}

POST /v2/photos/{dataset}/recommend/feedback

Sends feedback on a specific photo recommendation.

• Request: RecommendFeedback
• Response: (empty)