ImagesEndpoints

POST /v1/images

Scope: search
Tier: Starter and up
Price: $0.002 per call
Free credit: Yes, once Starter opens it

Find real photos, diagrams and illustrations for a subject, from Kaer's picture index with live Wikimedia Commons and Pexels results when the index is thin. Every picture is checked and comes with its licence, a ready-made credit line and whether a business website may reuse it.

Request body

Parameter	Type	Default	Description
`query`Required	string	·	What to picture, 1 to 300 characters ("sourdough bread", "water cycle diagram").
`count`	integer	`12`	1 to 30 pictures. Anything else, a numeric string included, is a 400.
`reusable`	boolean	`false`	Only pictures a business website may use with the returned credit.

Other fields come back in kaer.ignored_params. The body is limited to 8 KB; a call times out after 15 seconds.

Price

One call costs $0.002 whatever count is, even when it finds no pictures. A call that fails is not charged.

Response

Field	Type	Description
`object`	string	`images.result`
`query`	string	The query, trimmed.
`subject`	string	The subject the index searched for.
`count`	integer	Pictures returned.
`reusable_only`	boolean	Echoes `reusable`.
`withheld`	object	Present when some pictures were held back.
`results[].id`	string	Stable picture id.
`results[].kind`	string	`photo`, `diagram` or `illustration`.
`results[].title`	string	Picture title.
`results[].image_url`	string	Full-size image (https).
`results[].thumb_url`	string	Thumbnail (https).
`results[].page_url`	string	The page the picture comes from.
`results[].host`	string	That page's host.
`results[].width, height`	integer	Pixel size, when known.
`results[].source`	string	`wikimedia_commons`, `pexels` or `web`.
`results[].license`	object	`name`, `code`, `label` and `url`.
`results[].credit`	string	Author or owner.
`results[].attribution`	string	Attribution text from the source.
`results[].credit_line`	string	A ready-made credit to publish with the picture.
`results[].attribution_required`	boolean	Publish `credit_line` next to the picture when `true`.
`results[].share_alike`	boolean	Derivatives must keep the same licence.
`results[].commercial_ok`	boolean	A business website may use it.

{
  "object": "images.result",
  "query": "sourdough bread",
  "subject": "sourdough bread",
  "count": 12,
  "reusable_only": true,
  "results": [
    {
      "id": "commons:sourdough.jpg",
      "kind": "photo",
      "title": "Sourdough loaf",
      "image_url": "https://upload.wikimedia.org/…",
      "thumb_url": "https://upload.wikimedia.org/…/500px-…",
      "page_url": "https://commons.wikimedia.org/wiki/File:…",
      "host": "commons.wikimedia.org",
      "width": 4000,
      "height": 3000,
      "source": "wikimedia_commons",
      "license": { "name": "…", "code": "cc-by-sa", "label": "CC BY-SA 4.0", "url": "https://creativecommons.org/licenses/by-sa/4.0/" },
      "credit": "Ann K",
      "attribution": "…",
      "credit_line": "…",
      "attribution_required": true,
      "share_alike": true,
      "commercial_ok": true
    }
  ],
  "kaer": { "request_id": "req_…", "cost_usd": 0.002 }
}

Headers: x-request-id and the x-ratelimit-* headers. The cost is kaer.cost_usd in the body; there is no x-kaer-cost-usd header.

Errors

Status	Code	When
400	`invalid_json`	The body is not valid JSON. Images also needs a JSON object.
400	`query_required`	`query` is missing or blank.
400	`query_too_long`	`query` is over 512 characters (search) or 300 (images).
400	`invalid_count`	`count` is not an integer from 1 to 30.
400	`invalid_reusable`	`reusable` is not `true` or `false`.
403	`tier_required`	Your tier does not include this service yet.
413	`body_too_large`	The body is over the endpoint's limit: chat 1 MB, search 16 KB, batch 64 KB, images 8 KB, mail 512 KB.
502	`images_failed`	The picture search failed. Nothing was charged.
503	`images_busy`	Images are at capacity. Nothing was charged.
502 or 503	`images_unavailable`	Images are unreachable, timed out or paused. Nothing was charged.

curl https://api.kaer.ai/v1/images \
  -H "Authorization: Bearer $KAER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "sourdough bread", "count": 20, "reusable": true}'