Find and score event cover images.
Describe an event, artist, team or venue, and Images searches for a cover image. It returns a link to the image and a link to the website page where it found it, so you can check the source. You can also send links to images you already have and receive quality scores to help you compare them.
curl https://api.cloud.gomry.com/v1/images/search \
-H "Authorization: Bearer $GOMRY_CLOUD_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "Wicked, Gershwin Theatre",
"entityName": "Wicked",
"crop": "square"
}'Search for a cover that fits the listing.
Images ranks candidate covers and, in its default mode, scores their visual quality. The subject’s name helps prioritize relevant sites, while the square-crop preference favors images that remain useful in square cards.
For example, an event app could look for promotional artwork for a theater production by including its name and location in the search. If it already has several image URLs for that listing, it can score them instead of running another search. The scoring example below shows how the app can compare one candidate with the rest.
The quality score runs from 0 to 100. It considers features such as image clarity, readable poster text and watermarks. The score helps compare how images would work as covers; your application still needs to check that the picture shows the intended subject and that it can be used. In search mode with scoring enabled, the service can return no image if no candidate reaches the minimum score you set.
Choose search or score for the images you have.
{
"query": "Wicked, Gershwin Theatre",
"entityName": "Wicked",
"crop": "square"
}{
"images": [
{
"url": "https://example.com/promotional-poster.jpg"
}
]
}- Candidate image
- https://example.com/promotional-poster.jpg
- Illustrative quality score
- 82 / 100
Search discovers candidates; scoring evaluates up to 10 URLs you supply. Relevance mode can return a usable candidate without judging it first, so your application can run its own checks before requesting a score.
Candidate filtering skips sources such as stock agencies, social networks and merchandise sites. In scoring mode, a search with no candidate above the requested minimum can return image: null.
A ranked candidate still needs an editorial decision.
A cover-quality score is not a subject-identity check. Review the subject match and the publisher’s usage rights before putting an image into your application. Source exclusions do not grant a reuse license.
Images finds and evaluates existing pictures; it does not generate or host them. A returned image URL can be a short-lived redirect, so store an approved image in your own system rather than depend on that redirect as permanent hosting.
Search, lookup and scoring costs add up separately.
| Unit | Rate | What it covers |
|---|---|---|
| Image search | $0.04 | One search request |
| Google image lookup | $0.05 | Each lookup the search performs |
| Image scored | $0.02 | Each candidate evaluated by the scoring model |
For illustration, a search that performs three lookups and scores one image costs $0.21: $0.04 + (3 × $0.05) + $0.02. The actual total depends on the work performed.
The response reports the usage counts. A completed search with image: null is still a billable result.
Build with Images.
Enable Images for the project and grant search permission, scoring permission or both to your Cloud key. Send it as a Bearer token. Start with a clear subject query, or supply the image URLs your application already holds.