> ## Documentation Index
> Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Image metadata enrichment use case
> In the image metadata enrichment use case, the LLM ingests a text containing either a base64-encoded image or a public HTTP/HTTPS or Google Cloud Storage (`gs://`) image link and routes the image to a multimodal model. A JSON response is returned that contains an `imageMetadata` dictionary with a list of keywords, subcategories, and keyword synonyms. The metadata can be generated based on the image, the image title, and the categories.
## OpenAPI
````yaml /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/image-metadata-enrichment/{MODEL_ID}
openapi: 3.0.1
info:
title: Lucidworks AI Prediction API
version: v0
description: >-
The Lucidworks AI Prediction API is used to send synchronous API calls that
run predictions from pre-trained models or custom models.
The Use Case API returns a list of all supported models.
The `prediction` endpoints require an authentication token with scope
`machinelearning.predict`.
contact:
name: Lucidworks
url: https://lucidworks.com/
email: support@lucidworks.com
termsOfService: https://lucidworks.com/legal/developer-license-agreement/
license:
name: Lucidworks
url: https://lucidworks.com/legal/developer-license-agreement/
servers:
- url: https://APPLICATION_ID.applications.lucidworks.com
description: Production
security: []
tags:
- name: Get predictions
description: Submit prediction tasks to Lucidworks AI.
paths:
/ai/prediction/image-metadata-enrichment/{MODEL_ID}:
post:
tags:
- Get predictions
summary: Image metadata enrichment use case
description: >-
In the image metadata enrichment use case, the LLM ingests a text
containing either a base64-encoded image or a public HTTP/HTTPS or
Google Cloud Storage (`gs://`) image link and routes the image to a
multimodal model. A JSON response is returned that contains an
`imageMetadata` dictionary with a list of keywords, subcategories, and
keyword synonyms. The metadata can be generated based on the image, the
image title, and the categories.
operationId: post-ai-prediction-image-metadata-enrichment-modelId
parameters:
- in: path
name: MODEL_ID
required: true
schema:
type: string
description: >-
Unique identifier for the model. Must be a multimodal model capable
of processing images, such as `gemini-2.5-flash-lite`.
example: gemini-2.5-flash-lite
- in: header
name: Authorization
schema:
type: string
required: true
description: >-
Bearer token used for authentication. Format: `Authorization: Bearer
ACCESS_TOKEN`.
example: Bearer abc123def456
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImageMetadataEnrichmentRequest'
example:
batch:
- imageLink: https://i.postimg.cc/T3Gggmrx/blushing-happymushroom.png
useCaseConfig:
title: blushing-happy-mushroom
categories:
- fungi
- cute
- jubilant
- embarrassed
maxKeywords: 3
maxSynonyms: 2
maxSubcategories: 2
locale: en-US
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImageMetadataEnrichmentResponse'
example:
predictions:
- tokensUsed:
promptTokens: 1614
completionTokens: 61
totalTokens: 1675
imageMetadata:
keywords:
- cartoon
- pleased
- toadstool
subcategories:
- happy
- mushroom art
synonyms:
- animation
- cheerful
- delighted
- drawing
- fungus
- sporocarp
locale: en-US
response: |-
```yaml
keywords:
- toadstool
- pleased
- cartoon
subcategories:
- mushroom art
- happy
synonyms:
- fungus
- sporocarp
- delighted
- cheerful
- drawing
- animation
```
components:
schemas:
ImageMetadataEnrichmentRequest:
title: ImageMetadataEnrichmentRequest
type: object
required:
- batch
properties:
batch:
type: array
description: >-
An array of request items. Each item must contain exactly one of
`text`, `image`, or `imageLink`.
items:
type: object
properties:
text:
type: string
description: >-
Freeform content that contains either a base64-encoded image
or an image link. The value is parsed to the correct field
automatically. Use this field when passing image data from
Fusion.
image:
type: string
description: >-
A base64-encoded string of the image. If included, `imageLink`
may not be included.
imageLink:
type: string
description: >-
A public HTTP/HTTPS or Google Cloud Storage (`gs://`) image
URL. If included, `image` may not be included.
example: https://example.com/product-image.png
useCaseConfig:
$ref: '#/components/schemas/UseCaseConfigImageMetadataEnrichment'
modelConfig:
$ref: '#/components/schemas/ModelConfig'
ImageMetadataEnrichmentResponse:
type: object
properties:
predictions:
type: array
items:
$ref: '#/components/schemas/ImageMetadataEnrichmentResponseItem'
UseCaseConfigImageMetadataEnrichment:
title: UseCaseConfigImageMetadataEnrichment
type: object
description: >-
Optional object to control metadata generation. The image must be
provided in the `batch` item as `useCaseConfig` only tunes the output.
properties:
title:
type: string
description: >-
The title of the image or other details to include for the generated
metadata items.
example: blushing-happy-mushroom
categories:
type: array
description: >-
The current categories for the item. Used as the basis for the
subcategories generated.
items:
type: string
example:
- fungi
- cute
- jubilant
maxKeywords:
type: integer
description: The maximum number of keywords the model generates.
default: 15
example: 3
maxSubcategories:
type: integer
description: The maximum number of subcategories the model generates.
default: 5
example: 2
maxSynonyms:
type: integer
description: The maximum number of synonyms the model generates per keyword.
default: 5
example: 2
locale:
type: string
description: The locale used when generating targeted vernacular.
default: en-US
example: en-US
ModelConfig:
title: ModelConfig
type: object
description: >-
Provides fields and values that specify ranges for tokens. Fields used
for specific use cases and models are specified. The default values are
used if other values are not specified.
properties:
temperature:
type: number
format: float
example: 0.8
minimum: 0
maximum: 2
description: >-
A sampling temperature between 0 and 2. A higher sampling
temperature such as 0.8, results in more random (creative) output. A
lower value such as 0.2 results in more focused (conservative)
output. A lower value does not guarantee the model returns the same
response for the same input. We recommend staying at or below a
temperature of 1.0. Values above 1.0 might return nonsense unless
the topP value is lowered to be more deterministic.
topP:
type: number
format: float
example: 1
minimum: 0
maximum: 1
description: >-
A floating-point number between 0 and 1 that controls the cumulative
probability of the top tokens to consider, known as the randomness
of the LLM's response. This parameter is also referred to as top
probability. Set `topP` to 1 to consider all tokens. A higher value
specifies a higher probability threshold and selects tokens whose
cumulative probability is greater than the threshold. The higher the
value, the more diverse the output.
topK:
type: integer
example: -1
description: >-
An integer that controls the number of top tokens to consider. Set
topK to -1 to consider all tokens.
presencePenalty:
type: number
format: float
minimum: -2
maximum: 2
description: >-
A floating-point number between -2.0 and 2.0 that penalizes new
tokens based on whether they have already appeared in the text. This
increases the model's use of diverse tokens. A value greater than
zero (0) encourages the model to use new tokens. A value less than
zero (0) encourages the model to repeat existing tokens. This is
applicable for all OpenAI and Llama models.
example: 2
frequencyPenalty:
type: number
format: float
minimum: -2
maximum: 2
example: 1
description: >-
A floating-point number between -2.0 and 2.0 that penalizes new
tokens based on their frequency in the generated text. A value
greater than zero (0) encourages the model to use new tokens. A
value less than zero (0) encourages the model to repeat existing
tokens. This is applicable for all OpenAI and Llama models.
maxTokens:
type: integer
format: int32
example: 1
description: >-
The maximum number of tokens to generate per output sequence. The
value is different for each model. Review individual model
specifications when the value exceeds 2048.
apiKey:
type: string
description: >-
This optional parameter is only required when using the model for
prediction. You can find this value in your model's settings:
* **OpenAI**: Copy and paste the API key found in your
organization's settings. For more information, see OpenAI
Authentication API keys.
* **Azure OpenAI**: Copy and paste the API key found in your Azure
portal. See Authenticate
with API key.
* **Anthropic**: Copy and paste the API key found in your Anthropic
console or by using the Anthropic
API.
* **Google Vertex AI**: Copy and paste the base64-encoded service
account key JSON found in your Google
Cloud console. This service account key must have the Vertex
AI user role enabled. For more information, see generate
service account key.
example: API key specific to use case and model
azureDeployment:
type: string
example: DEPLOYMENT_NAME
description: >-
This optional parameter is the name of the deployed Azure OpenAI
model and is only required when a deployed Azure OpenAI model is
used for prediction.
azureEndpoint:
type: string
description: "\t\nThis optional parameter is the URL endpoint of the deployed Azure OpenAI model and is only required when a deployed Azure OpenAI model is used for prediction."
example: https://azure.endpoint.com
googleProjectId:
type: string
example: '[GOOGLE_PROJECT_ID]'
description: >-
This parameter is optional, and is only required when a Google
Vertex AI model is used for prediction.
googleRegion:
type: string
description: >-
This parameter is optional, and is only required when a Google
Vertex AI model is used for prediction. A value of `global` routes
the query to any available region. Other possible region values are:
* us-central1
* us-west4
* northamerica-northeast1
* us-east4
* us-west1
* asia-northeast3
* asia-southeast1
* asia-northeast
example: '[GOOGLE_PROJECT_REGION_OF_MODEL_ACCESS]'
ImageMetadataEnrichmentResponseItem:
type: object
properties:
tokensUsed:
$ref: '#/components/schemas/Token'
imageMetadata:
type: object
description: A dictionary containing the generated metadata for the image.
properties:
keywords:
type: array
description: A list of keywords generated for the image.
items:
type: string
example:
- cartoon
- pleased
- toadstool
subcategories:
type: array
description: >-
A list of subcategories generated based on the provided
categories.
items:
type: string
example:
- happy
- mushroom art
synonyms:
type: array
description: A list of synonyms generated for the keywords.
items:
type: string
example:
- animation
- cheerful
- delighted
- drawing
- fungus
- sporocarp
locale:
type: string
description: The locale used when generating the metadata.
example: en-US
response:
type: string
description: >-
The raw model response in YAML format containing keywords,
subcategories, and synonyms.
example: |-
```yaml
keywords:
- toadstool
- pleased
- cartoon
subcategories:
- mushroom art
- happy
synonyms:
- fungus
- sporocarp
- delighted
- cheerful
- drawing
- animation
```
Token:
type: object
properties:
promptTokens:
type: integer
format: int32
description: >-
The number of tokens generated to prompt the model to continue
generating results.
example: 148
completionTokens:
type: integer
format: int32
description: The number of tokens used until the model completes.
example: 27
totalTokens:
type: integer
format: int32
description: The sum of the prompt and completion tokens used in the model.
example: 175
````