Raw schema
{
"type": "object",
"properties": {
"image_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Public http(s) URL pointing directly to the reference image file, including a URL the user pasted in the conversation. For a photograph Pexafy returned, send its `photo_id` instead."
},
"image_file": {
"type": "object",
"description": "The user's uploaded image, as a host that passes uploads to tools provides it: the upload's `download_url` and `file_id`. A picture that is only visible in the conversation has neither.",
"properties": {
"download_url": {
"type": "string"
},
"file_id": {
"type": "string"
},
"mime_type": {
"type": "string"
},
"file_name": {
"type": "string"
}
},
"required": [
"download_url",
"file_id"
],
"additionalProperties": false
},
"image_base64": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Reference image as base64-encoded bytes, optionally as a data: URL. Use for programmatic clients that already hold the image data."
},
"photo_id": {
"anyOf": [
{
"type": "string",
"examples": [
"019e1ecb-0039-7da6-b1ca-987ee4d337c0"
]
},
{
"type": "null"
}
],
"default": null,
"description": "The photo_id of the Pexafy reference photo, copied from the result the user or assistant is referring to. It is a UUID such as `019e1ecb-0039-7da6-b1ca-987ee4d337c0`. Use it instead of an image when the reference is a Pexafy photo, whether it was returned in an earlier search or liked in the grid, and pass the words of that search in `english_search_sentence` if needed."
},
"english_search_sentence": {
"anyOf": [
{
"type": "string",
"maxLength": 250
},
{
"type": "null"
}
],
"default": null,
"description": "Optional, and usable with any reference. Send the words that say what the user wants from the reference: with a `photo_id`, the words that photograph was found under, so the results stay on the subject they asked for; with an image, what they want changed or kept from it (“like this but at night”). The reference stays the main signal and these words adjust it. With an image, send the change alone (“at night”) rather than the whole scene rewritten, which would outweigh the picture instead of adjusting it; with a `photo_id`, the full sentence that photograph was found under is what to send. In English, like the sentence of a text search. The words a reference photograph was found under are the best ones; where the grid hands you a short description of it instead, that description serves. When it is unclear whether they want the same subject or simply the same look, send the words: staying on the subject is the safer default. Omit them only when they plainly want photographs that look like the picture itself."
},
"explicit_orientation_filter": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"landscape",
"portrait",
"square"
]
}
},
{
"type": "null"
}
],
"default": null,
"description": "Omit this parameter unless the user explicitly asks for a photo shape or orientation in their own words, or names a format whose shape is part of its definition — a vertical Short, a banner, a square post, a phone wallpaper.\n\nThis is a hard filter, not a preference: it removes photos with other shapes before ranking, so using a shape the user did not request can exclude the best matches.\n\nNever infer the shape from the reference image the user gave — its shape is a property of the picture they had, not a constraint on the ones they want — nor from the subject, the composition, or a purpose that fixes no shape (“a photo for my blog post”, “something for my landing page”). If you are choosing a value rather than repeating one explicitly requested by the user, omit it.\n\nAllowed values: `landscape`, `portrait`, `square`. Multiple values are allowed: two shapes return more than one alone, though any filter still returns less than none. For example, “anything but portrait” means `['landscape', 'square']`."
}
},
"required": [],
"additionalProperties": false
}
