18.9.2.1 Creating Generative AI Service Objects

Learn how to create Generative AI Service objects.

Parent topic: Managing Generative AI Services

18.9.2.1.1 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 - Uses /chat/completions for chat and /embeddings for vector generation. OpenAI expects JSON with messages[] and model parameters, and authenticates using a Bearer token. APEX maps its internal format to the OpenAI schema, injects credentials, and normalizes responses so applications see a consistent structure across models and providers.
  • 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 these core generative AI use cases:
    • Chat for conversational experiences such as question answering and virtual assistants
    • Embeddings for semantic search, recommendation, classification, and clustering

    To learn more, see Oracle Cloud Infrastructure Documentation

  • Google Gemini - Uses generateContent for chat and embedContent for embeddings. Gemini expects structured JSON (with contents[] / parts[]) and an API key passed as a URL query parameter. APEX injects the API key and constructs the Gemini payload automatically. Developers only choose the model.
  • 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) - Runs models locally and exposes /api/chat for chat and /api/embed for embeddings. APEX treats Ollama like any other provider, the service is registered the same way and the same normalization applies which lets organizations run inference entirely inside their infrastructure without changing application code.
  • Generic OpenAI-compatible endpoints - APEX supports a generic OpenAI-compatible path so any provider, proxy or self-hosted model that follows the OpenAI API spec (including fine-tuned or open-weight deployments) can be used with minimal or no custom work. If it speaks the OpenAI format, APEX can plug it into the same runtime surface.

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.

Parent topic: Creating Generative AI Service Objects

18.9.2.1.2 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 Utilties 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, choose the provider type from the list, and enter the provider’s base URL (that is, the endpoint APEX will call). You can also give the service a static identifier that can be referenced programmatically.

  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

    Pick the model to use (for example, claude-sonnet-4-6 or gemini-3.1-pro-preview). APEX uses the selected model name when it builds the provider specific API request.

  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.

Parent topic: Creating Generative AI Service Objects

18.9.2.1.3 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 confirgure 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 will display 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. 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.

  5. 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 - Click Test Connection to validate the information you enter prior to completing the setup.

      If the connection is valid, the following message displays:

      Connection Succeeded!

      If the connection fails, resolve the errors that display.

  6. Advanced:
    1. Advanced, Additional Attributes - Click Additional Attributes to include additional attributes that will be added to the JSON request payload as part of performing a Generative AI Service operation.
    2. 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).
    3. 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.
    4. 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 numbers 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.

    5. 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

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

Parent topic: Creating Generative AI Service Objects