OpenRouter

The UC AI OpenRouter integration gives you access to hundreds of AI models from different providers (OpenAI, Anthropic, Google, Meta, and many more) through a single API endpoint.

Features

• Access to 300+ models from 60+ providers through a single API
• Full function calling (tools) support
• Structured output support
• Multi-modal support (text, images, PDFs)
• Embedding generation
• Automatic fallback and provider routing
• Pay-per-use pricing with no subscriptions

Prerequisites

1. OpenRouter API key
2. Oracle database with internet access to OpenRouter’s API endpoints (see Network Setup (ACL & Wallet))
3. UC AI package installed
4. Set up API key (guide)

You can get an API key by signing up at OpenRouter.

Creating a Web Credential

To use your OpenRouter key with APEX Web Credentials, create a new web credential in your APEX workspace (Workspace Utilities → Web Credentials) with the following configuration:

• Authentication Type: HTTP Header
• Credential Name: Authorization
• Credential Secret: Bearer <your_api_key>

Also set Valid for URLs to the OpenRouter API (https://openrouter.ai/) to limit the scope of the credential.

To use the web credential in your PL/SQL code, set the package variable uc_ai_openrouter.g_apex_web_credential to the static ID of your web credential before calling any UC AI functions:

uc_ai_openrouter.g_apex_web_credential := 'OPENROUTER';

OpenRouter uses the OpenAI-compatible API format, which UC AI handles through uc_ai_openai. Set the credential on uc_ai_openrouter, where UC AI resolves credentials for this provider.

Models

OpenRouter provides access to models from many providers. You can browse all available models at openrouter.ai/models.

Models are identified by their provider prefix and model name, for example:

• openai/gpt-5.6-terra - OpenAI GPT-5.6 Terra
• anthropic/claude-sonnet-5 - Anthropic Claude Sonnet 5
• google/gemini-pro - Google Gemini Pro
• meta-llama/llama-3-70b-instruct - Meta Llama 3 70B
• mistralai/mixtral-8x7b-instruct - Mistral Mixtral

Some models are available for free (with rate limits), identifiable by the :free suffix:

• meta-llama/llama-3-8b-instruct:free
• google/gemma-7b-it:free

See OpenRouter’s model page for the complete list of available models, pricing, and capabilities.

Usage Examples

Basic Text Generation

declare
  l_result json_object_t;
begin
  l_result := uc_ai.generate_text(
    p_user_prompt => 'What is Oracle APEX?',
    p_provider => uc_ai.c_provider_openrouter,
    p_model => 'openai/gpt-5.6-luna'
  );

  dbms_output.put_line('AI Response: ' || l_result.get_string('final_message'));
end;
/

With System Prompt

declare
  l_result json_object_t;
begin
  l_result := uc_ai.generate_text(
    p_user_prompt => 'I have tomatoes, salad, potatoes, olives, and cheese. What can I cook with that?',
    p_system_prompt => 'You are an assistant helping users to get recipes. Please answer in short sentences.',
    p_provider => uc_ai.c_provider_openrouter,
    p_model => 'anthropic/claude-sonnet-5'
  );

  dbms_output.put_line('Recipe suggestions: ' || l_result.get_string('final_message'));
end;
/

Using Tools/Function Calling

OpenRouter supports tools/function calling for models that have this capability. You can define tools in your application and the model will call them as needed.

declare
  l_result json_object_t;
begin
  uc_ai.g_enable_tools := true; -- enable tools usage

  l_result := uc_ai.generate_text(
    p_user_prompt => 'What is the email address of Jim?',
    p_system_prompt => 'You are an assistant to a time tracking system. Your tools give you access to user, project and timetracking information. Answer concise and short.',
    p_provider => uc_ai.c_provider_openrouter,
    p_model => 'openai/gpt-5.6-terra'
  );

  dbms_output.put_line('AI Response: ' || l_result.get_string('final_message'));
end;
/

See the tools guide for details on how to set up and use tools.

Multi-modal Analysis

Many models available through OpenRouter have vision capabilities for Image and PDF Analysis.

declare
  l_messages json_array_t := json_array_t();
  l_content json_array_t := json_array_t();
  l_result json_object_t;
  l_final_message clob;
begin
  l_messages.append(uc_ai_message_api.create_system_message(
    'You are an image analysis assistant.'));

  l_content.append(uc_ai_message_api.create_file_content(
    p_media_type => 'image/png',
    p_data_blob => your_image_blob,
    p_filename => 'image.png'
  ));

  l_content.append(uc_ai_message_api.create_text_content(
    'What is depicted in the attached image?'
  ));

  l_messages.append(uc_ai_message_api.create_user_message(l_content));

  l_result := uc_ai.generate_text(
    p_messages => l_messages,
    p_provider => uc_ai.c_provider_openrouter,
    p_model => 'openai/gpt-5.6-terra'
  );

  l_final_message := l_result.get_clob('final_message');
  dbms_output.put_line('Analysis: ' || l_final_message);
end;
/

Refer to the file analysis guide for more examples on how to analyze images and PDFs.

Structured Output

OpenRouter supports structured output (JSON schema) for models that have this capability:

declare
  l_result json_object_t;
  l_schema json_object_t;
  l_final_message clob;
  l_structured_output json_object_t;
begin
  -- Define the expected JSON schema
  l_schema := json_object_t('{
    "type": "object",
    "properties": {
      "response": {"type": "string"},
      "confidence": {"type": "number"}
    },
    "required": ["response", "confidence"]
  }');

  l_result := uc_ai.generate_text(
    p_user_prompt => 'What is the capital of France? Please respond with confidence.',
    p_system_prompt => 'You are a helpful assistant that provides accurate information.',
    p_provider => uc_ai.c_provider_openrouter,
    p_model => 'openai/gpt-5.6-terra',
    p_response_json_schema => l_schema
  );

  l_final_message := l_result.get_clob('final_message');
  l_structured_output := json_object_t(l_final_message);

  dbms_output.put_line('Response: ' || l_structured_output.get_string('response'));
  dbms_output.put_line('Confidence: ' || l_structured_output.get_number('confidence'));
end;
/

Reasoning / Thinking

For models that support reasoning (like OpenAI’s o-series models), you can enable extended thinking:

declare
  l_result json_object_t;
begin
  uc_ai.g_enable_reasoning := true;
  uc_ai.g_reasoning_level := 'low'; -- 'low', 'medium', 'high'

  l_result := uc_ai.generate_text(
    p_user_prompt => 'Answer in one sentence. If there is a great filter, are we before or after it and why.',
    p_provider => uc_ai.c_provider_openrouter,
    p_model => 'openai/gpt-5.6-terra'
  );

  dbms_output.put_line('AI Response: ' || l_result.get_string('final_message'));
end;
/

Generating Embeddings

OpenRouter provides access to embedding models for semantic search, clustering, and other vector-based operations:

declare
  l_result json_array_t;
begin
  l_result := uc_ai.generate_embeddings(
    p_input => json_array_t('["Oracle APEX is a low-code development platform.", "UC AI allows you to easily use AI from PL/SQL."]'),
    p_provider => uc_ai.c_provider_openrouter,
    p_model => 'thenlper/gte-base'
  );

  -- l_result.get_size → 2 (one embedding per input string)
  -- l_result.get(0) → JSON array of embedding values for first input
end;
/

Check the OpenRouter models page and filter by “Embeddings” output modality to see available embedding models.

Benefits of Using OpenRouter

Unified API

Access models from OpenAI, Anthropic, Google, Meta, Mistral, and many more through a single API endpoint. Your code keeps the same provider and credential for all of them.

Automatic Fallbacks

During a provider outage, OpenRouter sends the request to an alternative provider.

Cost Optimization

OpenRouter routes each request to a low-cost provider for the model you selected. You pay for each request, and there is no subscription.

Model Discovery

To try a different model, change the p_model parameter. You do not need a separate API key or credential for each provider.