Skip to main content

Model Selection (Beta)

Beta Feature

Model selection is currently in beta. Functionality, the list of available models, and behavior may change in future releases.

For each action in a request, the Context API lets you choose which AI model processes your content.

This page does the following:

  • Lists the models you can choose from.
  • Explains what happens when you choose a model and when you don't.
  • Gives guidance on choosing the right model.
  • Shows the error responses for an invalid choice.

This information is for developers who want to balance quality, speed, and cost per action.

caution

Models other than the default can return different results for the same content, and those results are not always correct. An action can report success (isSuccess: true) even when its result is incomplete or wrong. The default model is the recommended choice. Before you use another model in production, test it on your own documents and check the returned content (see Choosing a Model for more information).

How Model Selection Works​

Every text and image action runs on a default model chosen by Knowledge Enrichment. To use a different model for an action, add a model field to that action's options in a POST /content/process request. Model selection is optional and set per action.

SituationBehavior
The action has a model field.The action runs on that model. If processing fails temporarily, it retries use the same model. The action never falls back to a different model.
The action has no model field.The action runs on its default model and falls back automatically to a backup model if needed. This is the same behavior as before model selection existed.
Several actions are included in one request.Each action uses its own model, or its default if it has none. Actions do not affect other actions' models.
The model is unknown or not offered for that action.The whole request is rejected with 400 Bad Request and no action runs (see Errors).

Model selection requires "version": "context.api/v2". The list of accepted models is the same for every customer and every environment. There is no per-account model configuration. However, not every model is deployed in every region (see Regional Availability for more information).

Available Models​

Modelmodel valueText ActionsImage ActionsProduction (US)Production (EU)
Claude Haiku 4.5bedrock-claude-haiku-4-5YesYesYesYes
OpenAI GPT-5.6 Lunaopenai-gpt-5-6-lunaYesYesYesNo
Gemma 4 E2Bgoogle-gemma-4-e2bYesYesYesYes
Gemma 4 26B A4Bgoogle-gemma-4-26b-a4bYesYesYesYes
Gemma 4 31Bgoogle-gemma-4-31bYesYesYesYes
Nemotron Super 3 120Bnvidia-nemotron-super-3-120bYesNoYesYes
Nemotron Nano 3 30Bnvidia-nemotron-nano-3-30bYesNoYesYes
OpenAI GPT OSS 120Bopenai-gpt-oss-120bYesNoYesYes
OpenAI GPT OSS 20Bopenai-gpt-oss-20bYesNoYesYes

Set model to one of the model values listed in this section, exactly as written. Values are case-sensitive.

Action groupActionsModels Accepted
Text actionstextSummarization, textClassification, textMetadataGeneration, namedEntityRecognitionTextAll 9 models
Image actionsimageDescription, imageClassification, imageMetadataGeneration, namedEntityRecognitionImageThe 5 vision-capable models: bedrock-claude-haiku-4-5, openai-gpt-5-6-luna, google-gemma-4-e2b, google-gemma-4-26b-a4b, google-gemma-4-31b
Embedding actionstextEmbeddings, imageEmbeddingsNone. Model selection is not supported.

The model list can change over time. Use GET /content/process/actions to get the current list for each action instead of hard-coding it.

Regional Availability​

OpenAI GPT-5.6 Luna (openai-gpt-5-6-luna) is not hosted in the EU for data residency reasons, so it is not available in the Production (EU) environment. All other models are available in both Production (US) and Production (EU).

important

The Context API does not check regional availability when it validates a request. In Production (EU), a request that selects openai-gpt-5-6-luna is accepted with 200 OK, and GET /content/process/actions still lists the model in availableModels. The actions that name it are expected to fail during processing, typically with errorType: "LambdaError". In Production (EU), choose a different model or omit model.

Choosing a Model​

The default model (used when you omit model) is the recommended choice for every action. Choose a different model when you have tested it on your own content and it gives the quality, speed, or cost you need.

Models differ most on actions that return structured output: textMetadataGeneration, imageMetadataGeneration, namedEntityRecognitionText, namedEntityRecognitionImage, textClassification, and imageClassification. On these actions, a smaller model can return a result that is incomplete or incorrect while the action still reports success. Typical examples include the following:

  • A metadata field comes back partially filled, empty, or with content that does not match what the field asks for.
  • A classification returns one of the provided classes even though none of them fits the content.
  • A value is correct but does not follow the format shown in your kSimilarMetadata example.

Actions that return free text, such as textSummarization and imageDescription, usually vary less between models, but their results can still differ in content and quality.

caution

isSuccess: true means the action completed, not that its content is correct. Before you switch a structured-output action to a non-default model, run it on a representative sample of your documents and validate the returned content, not just the status.

Selecting a Model​

Add model to the options object of the action. It works together with the action's other options, such as maxWordCount, classes, kSimilarMetadata, and instructions. There is no request-level model field. Each action names its own.

FieldTypeRequiredDescription
modelstringNoThe model that runs this action. Must be one of the action's availableModels. When omitted, the action runs on its default model. Not accepted on textEmbeddings or imageEmbeddings.

Example: One Action With a Chosen Model​

{
  "version": "context.api/v2",
  "objectKeys": [{ "path": "testing/fae61283-571c-403a-b33f-c8d982158da9/documents/report.pdf" }],
  "actions": {
    "textSummarization": {
      "model": "google-gemma-4-e2b"
    }
  }
}

Example: Several Actions With Different Models​

{
  "version": "context.api/v2",
  "objectKeys": [{ "path": "testing/fae61283-571c-403a-b33f-c8d982158da9/documents/report.pdf" }],
  "actions": {
    "textSummarization": {
      "model": "google-gemma-4-e2b",
      "maxWordCount": 200
    },
    "textClassification": {
      "model": "nvidia-nemotron-super-3-120b",
      "classes": ["Invoice", "Contract", "Memo"]
    },
    "textMetadataGeneration": {
      "kSimilarMetadata": [
        { "document_type": "Financial Report", "author": "John Smith", "date": "2025-01" }
      ]
    }
  }
}

textSummarization runs on Gemma 4 E2B and textClassification runs on Nemotron Super 3 120B. textMetadataGeneration has no model, so it runs on its default model.

Example: Image Action With a Vision-Capable Model​

{
  "version": "context.api/v2",
  "objectKeys": [{ "path": "testing/fae61283-571c-403a-b33f-c8d982158da9/images/photo.png" }],
  "actions": {
    "imageDescription": {
      "model": "google-gemma-4-31b",
      "maxWordCount": 100
    }
  }
}

Example: No Model (Default Behavior)​

{
  "version": "context.api/v2",
  "objectKeys": [{ "path": "testing/fae61283-571c-403a-b33f-c8d982158da9/documents/report.pdf" }],
  "actions": {
    "textSummarization": {}
  }
}

The response to each request is the usual processingId. The results have the same format whichever model ran the action.

Discovering Available Models​

Making the GET /content/process/actions?version=context.api/v2 call returns every action you can request. Each action that supports model selection has an availableModels array. Actions without availableModels do not accept a model field. The list is the same in every environment and does not reflect regional availability.

GET /latest/api/context-enrichment/content/process/actions?version=context.api/v2 HTTP/1.1
Host: knowledge-enrichment.ai.app.hyland.com
Authorization: Bearer <access_token>

Response: 200 OK

[
  {
    "name": "textSummarization",
    "availableModels": [
      "bedrock-claude-haiku-4-5",
      "openai-gpt-5-6-luna",
      "google-gemma-4-e2b",
      "google-gemma-4-26b-a4b",
      "google-gemma-4-31b",
      "nvidia-nemotron-super-3-120b",
      "nvidia-nemotron-nano-3-30b",
      "openai-gpt-oss-120b",
      "openai-gpt-oss-20b"
    ]
  },
  {
    "name": "imageDescription",
    "availableModels": [
      "bedrock-claude-haiku-4-5",
      "openai-gpt-5-6-luna",
      "google-gemma-4-e2b",
      "google-gemma-4-26b-a4b",
      "google-gemma-4-31b"
    ]
  },
  { "name": "textEmbeddings" },
  { "name": "imageEmbeddings" }
]

This example shows four of the returned actions. The full response lists every action. textClassification, textMetadataGeneration, and namedEntityRecognitionText have the same availableModels as textSummarization. imageClassification, imageMetadataGeneration, and namedEntityRecognitionImage have the same availableModels as imageDescription.

important

Without ?version=context.api/v2, making the GET /content/process/actions call returns a plain array of action names with no availableModels. Always pass version=context.api/v2 to discover the available models.

Errors​

The Context API checks every model value before it accepts the request. If any action names an invalid model, the API returns 400 Bad Request and does not process any action in the request, including actions with a valid model or no model. Correct the reported action and send the request again.

Each problem appears in the errors array. propertyName identifies the action as actions.<actionName>.model. When several actions have an invalid model, errors has one entry per action and detail joins the messages with ; .

CauseStatusError message
model is not a known model400Model '{model}' is not a recognized model.
model is not offered for this action (for example, a text-only model on an image action)400Model '{model}' is not available for action '{action}'. Allowed models: {models}
Non-empty model on textEmbeddings or imageEmbeddings400{action} action does not support the following properties: model

Example: Text-Only Model On An Image Action​

Request:

{
  "version": "context.api/v2",
  "objectKeys": [{ "path": "testing/fae61283-571c-403a-b33f-c8d982158da9/images/photo.png" }],
  "actions": {
    "imageDescription": { "model": "nvidia-nemotron-super-3-120b" }
  }
}

Response: 400 Bad Request

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Validation error",
  "status": 400,
  "detail": "Model 'nvidia-nemotron-super-3-120b' is not available for action 'imageDescription'. Allowed models: bedrock-claude-haiku-4-5, openai-gpt-5-6-luna, google-gemma-4-e2b, google-gemma-4-26b-a4b, google-gemma-4-31b",
  "errors": [
    {
      "propertyName": "actions.imageDescription.model",
      "errorMessage": "Model 'nvidia-nemotron-super-3-120b' is not available for action 'imageDescription'. Allowed models: bedrock-claude-haiku-4-5, openai-gpt-5-6-luna, google-gemma-4-e2b, google-gemma-4-26b-a4b, google-gemma-4-31b"
    }
  ]
}

Example: Unknown Model​

Request:

{
  "version": "context.api/v2",
  "objectKeys": [{ "path": "testing/fae61283-571c-403a-b33f-c8d982158da9/documents/report.pdf" }],
  "actions": {
    "textSummarization": { "model": "unknown-model-xyz" },
    "textClassification": { "classes": ["Invoice", "Contract"] }
  }
}

Response: 400 Bad Request. textClassification is not processed, either.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Validation error",
  "status": 400,
  "detail": "Model 'unknown-model-xyz' is not a recognized model.",
  "errors": [
    {
      "propertyName": "actions.textSummarization.model",
      "errorMessage": "Model 'unknown-model-xyz' is not a recognized model."
    }
  ]
}

When a Chosen Model Fails During Processing​

A chosen model can still fail after the request is accepted because, for example, the model is temporarily unavailable or is not offered in your region. Temporary failures are retried on the same model. If the action still fails, only that action fails: its result has isSuccess: false, usually with errorType: "LambdaError". If processing takes too long, errorType is "Timeout" instead. The other actions in the request still return their results, so the overall status is PARTIAL_FAILURE when at least one other action succeeded, and FAILURE when none did.

{
  "id": "156e4a8a-e9c8-41c0-95f0-7039982236f3",
  "timestamp": "2026-10-14T15:45:14.104323+00:00",
  "results": [
    {
      "objectKey": "testing/fae61283-571c-403a-b33f-c8d982158da9/documents/report.pdf",
      "textSummary": {
        "isSuccess": false,
        "result": null,
        "error": {
          "errorType": "LambdaError",
          "message": "An error occured while processing the request"
        }
      },
      "textClassification": {
        "isSuccess": true,
        "result": "Invoice",
        "error": null
      }
    }
  ],
  "status": "PARTIAL_FAILURE",
  "inProgress": false
}

To recover, retry the request. If the action keeps failing, choose a different model for it or omit model to use the default model with its automatic backup.

Next steps​