Creating Generative AI Service Objects

Learn how to create Generative AI Service objects.

About AI Providers

Learn about supported AI providers in APEX.

About Choosing an AI Provider

When choosing an AI provider, consider the following:

• Pick the right model for the right job. Different models excel at different tasks such as reasoning, speed, or quality. APEX lets you choose the model and provider that best fits your applications in terms of reasoning, performance and quality, and cost.

• Future-proof the platform. New AI models appear frequently. The best option today may not be the right choice tomorrow. With APEX, changing to a new AI provider or model is just a configuration change. Your application keeps working. To make a change, just point to better services or models.

• Local and hybrid deployment options. Support for local LLM frameworks, such as Ollama, means models can run inside customer controlled infrastructure for sensitive workloads or offline scenarios, while retaining the same APEX “remote server + credential” model. This is a practical approach in high-security deployments.

• Enterprise ready, security and governance. APEX executes AI calls server-side, stores secrets in the Web Credentials repository (so secrets are never exposed to client code), and works with network ACLs and enterprise governance.

Supported AI Providers

APEX supports the following AI providers:

• OpenAI - Supports the Responses API, which is the default for new services, and the deprecated Chat Completions API. APEX constructs the appropriate request payload and interprets the response based on the selected Provider API.

• Cohere - Uses /chat for chat and /embed for embeddings. Cohere expects JSON payloads with messages or input text and authenticates using a Bearer token. APEX maps its normalized request model to Cohere’s format, supports common parameters, and parses responses into a consistent structure independent of provider-specific fields.

• OCI Generative AI - OCI Generative AI is a fully managed Oracle Cloud Infrastructure service for building, deploying, and operating generative AI applications at enterprise scale. OCI Generative AI supports the Generic API, which is the default, and the Responses API. OCI Generative AI supports models from multiple providers, and not every model supports both APIs.

  To learn more, see Oracle Cloud Infrastructure Documentation

• Google Gemini - Supports the Interactions API, which is the default for new services, and the deprecated Generate Text API. APEX constructs the appropriate request payload and interprets the response based on the selected Provider API.

• Anthropic Claude - Exposes a messages-based API and authenticates using an x-api-key header. APEX maps Claude’s message/role structure into its internal format, calls the messages endpoint, and normalizes the returned content[] so your app receives a consistent response shape regardless of Claude model version.

• Mistral AI - Follows an OpenAI-like API but exposes additional parameters and separate endpoints for chat and embeddings. APEX accepts those options and maps them into the normalized request model so applications behave the same whether they talk to Mistral or another supported provider.

• Ollama (local LLM execution) - Supports the Responses API, which is the default for new services, and the deprecated Chat Completions API.

• Generic (OpenAI API Compatible) - Supports the Responses API, which is the default for new services, and the deprecated Chat Completions API.

APEX models each provider as a metadata driven service, transforms APEX’s internal request format into the provider’s expected payload, injects credentials safely on the server, executes the call, and parses the provider response back into a normalized result for the application. This is implemented by the provider normalization layer and the builder’s declarative pages.

Overview of Creating a Generative AI Service

Learn about key steps in creating Generative AI Service in APEX.

Creating an AI Service in APEX involves the following steps:

1. Navigate to the Generative AI Services page

   In App Builder, select Workspace Utilities and then Generative AI. On the Generative AI Services page, create a new Generative AI Service.

2. Specify an Identity and Define Routing

   Give the service a name, select the provider and Provider API, and enter the Base URL. APEX uses the Provider API to determine the endpoint, request format, and response format. You can also specify a unique Static ID for programmatic use.

3. Specify Credentials

   Select or create a Web Credential to authenticate to the provider. Keys and secrets are stored securely in APEX’s credential repository so they are never exposed to application code or the browser.

4. Select a Model

   Specify the model to use for the Generative AI Service. For OCI Generative AI, also configure the Compartment ID and Serving Mode. Dedicated serving mode requires an Endpoint ID, and the Responses API requires a Project ID.

5. Specify App Builder Integration and Defaults

   Control whether the service is available to App Builder features (such as AI Assistant, Create Page from Natural Language and so on). You can optionally mark it as the default for new applications in the workspace.

6. Configure Runtime Controls

   Configure operational settings such as Maximum AI Tokens and Server Timeout value so long-running calls are handled predictably.

7. Save

   Once saved, every AI-powered component in the application routes through that service automatically. Swapping providers later is a single configuration update. Applications do not need code changes.

What Happens When an App Makes an AI Call

Every AI request in an APEX application follows the same path at runtime.

1. An APEX component or PL/SQL API initiates the request.

2. APEX looks up the configured provider, endpoint, and credential for the Generative AI Service.

3. A provider-specific REST payload is assembled automatically.

4. The request is sent through APEX’s server-side REST infrastructure.

5. The provider’s response is parsed and normalized into a consistent APEX format.

6. That normalized response is returned to the application.

Creating a Generative AI Service

Learn about creating a Generative AI Service.

Note: Before creating a Generative AI Service, you need an API key or credentials from your AI Provider. To learn more, contact your AI Provider.

Each AI Service must have a unique Name and Static ID within the workspace. To create a Generative AI Service, you select an AI Provider and then configure the attributes. Note that the specific steps and available attributes that display may differ depending upon AI Provider you select.

To create a Generative AI Service object:

1. Navigate to the Generative AI Services page:

   1. On the Workspace home page, click the App Builder icon.

   2. On the App Builder home page, click the Workspace Utilities icon.

      The Workspace Utilities page appears.

   3. On the Workspace Utilities page, click Generative AI.

      The Generative AI Services page appears.

2. To create a Generative AI Service object, click Create.

   The Create/Edit page appears.

3. Under Identification:

   1. Identification, AI Provider - Select the AI Provider to use for this Generative AI Service.

   2. Identification, Name - The name of the Generative AI Service. The name displays on the Generative AI Services page in Workspace Utilities.

      Example: HCM Cohere AI Service

   After this step, the UI changes depending upon the AI Provider you select. The steps that follow describe common attributes. To learn more about an attribute, see item Help.

4. Under OCI Generative AI:

   1. Compartment ID - The Oracle Cloud Infrastructure Compartment ID used for OCI Generative AI requests.

   2. Serving Mode - Select On-Demand or Dedicated.

   3. Endpoint ID - Required when Serving Mode is Dedicated.

   4. Region - The Oracle Cloud Infrastructure Region. If the region is altered for an existing OCI Generative AI service configuration, make sure to also change the corresponding Web Credential or create a new Web Credential for the selected region.

   5. Project ID - Required when Provider API is Responses.

5. Settings:

   1. Settings, Used by App Builder - Controls whether built-in Generative AI Service capabilities are available in App Builder, SQL Workshop, and Data Reporter. See About the Used by App Builder Setting.

   2. Settings, Default for New Apps - When enabled, this Generative AI Service is automatically selected as the default AI Service for all newly created applications.

   3. Settings, Base URL - The base URL of the Generative AI Service.

      The base URL is typically the REST API endpoint for the specified Generative AI Provider. Make sure the URL in the selected Web Credential is reflected in the base URL of the Generative AI Service.

   4. Settings, AI Model - The model to use for the Generative AI Service.

6. Credentials:

   1. Credentials, Credential - Select the Web Credential to use for this Generative AI Service. Customers must sign-up for or use existing credentials of their respective AI provider.

   2. Credentials, API Key - Enter the API Key to authenticate against the AI Provider.

   3. Credentials, Test Connection - Select Test Connection to validate the information you enter prior to completing the setup. APEX tests the selected Provider API and validates the applicable OCI fields.

      If the connection is valid, the following message displays:

      Connection Succeeded!

      If the connection fails, resolve the errors that display.

7. Advanced:

   1. Advanced, Additional Attributes - Specify additional provider-specific attributes in JSON format. The supported JSON structure depends on the selected Provider API.

   2. Advanced, Provider API - Select the API format used by the Generative AI Service. Available values depend on the selected AI Provider. Chat Completions and Generate Text are deprecated.

   3. Advanced, Static ID - The Static ID for the Generative AI Service. The static ID is used when using the service with the APEX_AI package (APEX_AI.CHAT).

   4. Advanced, AI Model - An optional model name or ID for the Generative AI Service. If no model information is given, the default model of the respective AI provider will be used.

   5. Advanced, Maximum AI Tokens - Enter the maximum number of AI Tokens per 24 hour period that Oracle APEX can use for the Generative AI Service. Not every Generative AI Service provides token usage information, so Oracle APEX may not be able to enforce this limit.

      The APEX_AI.GET_AVAILABLE_TOKENS function also returns the number of tokens available.

      An administrator can also set the Maximum AI Tokens at the workspace or instance-level. See Viewing Existing Workspace Information and Configuring Instance-Level Workspace Isolation Attributes in Oracle APEX Administration Guide.

   6. Advanced, HTTP Headers - Additional HTTP headers used in the Generative AI Service (REST) request. HTTP headers are specified in the following format:

      name_1=value_1

      name_2=value_2

   7. Advanced, Comments - Enter any developer comments or notes.

8. Select Create.