Creating and Managing Endpoints

This guide covers creating Services (provider configurations) and API Keys (client access tokens).

Understanding the Hierarchy

Service (e.g., "google-gemini-prod")
├── Provider API Key (encrypted Google/OpenAI key)
├── Enabled Models (gemini-2.0-flash, gemini-3-pro)
├── Rate Limits (warn/block thresholds)
└── API Keys (client tokens)
    ├── sk_abc123... (frontend app)
    ├── sk_def456... (backend service)
    └── sk_ghi789... (batch processing)

Creating a Service

Via Admin Dashboard

  1. Login to admin dashboard at http://localhost:5173
  2. Navigate to Services > Create Service
  3. Fill in the configuration form
  4. Save and test the connection

Via Admin API

import requests

ADMIN_URL = "http://localhost:8000/api/admin"

# Login to get JWT token
session = requests.Session()
login_response = session.post(
    f"{ADMIN_URL}/auth/login",
    json={"username": "admin", "password": "your_password"}
)
token = login_response.json()["access_token"]
session.headers.update({"Authorization": f"Bearer {token}"})

# Create a service for Google Gemini
service = session.post(
    f"{ADMIN_URL}/services",
    json={
        "service_name": "google-gemini",
        "description": "Google Gemini API for text and image generation",
        "provider": "google",
        "models_enabled": [
            "gemini-2.0-flash",
            "gemini-2.0-flash-lite",
            "gemini-3-pro-preview",
            "gemini-3-pro-image-preview"
        ],
        "provider_api_key": "AIzaSy...",  # Your Google API key

        # Rate limits (in USD)
        "limit_cost_hour_warn": 5.0,      # Warn at $5/hour
        "limit_cost_hour_block": 10.0,    # Block at $10/hour
        "limit_cost_day_warn": 50.0,      # Warn at $50/day
        "limit_cost_day_block": 100.0,    # Block at $100/day
        "limit_cost_month_warn": 500.0,   # Warn at $500/month
        "limit_cost_month_block": 1000.0  # Block at $1000/month
    }
).json()

print(f"Service created: {service['service_name']}")
print(f"Service ID: {service['id']}")

Service Configuration Options

Field Type Description
service_name string Unique identifier (used in API calls)
description string Human-readable description
provider string Provider type: google, openai, anthropic, deepseek
provider_api_key string Your provider's API key
models_enabled array List of allowed model IDs
limit_cost_hour_warn float Hourly soft limit (USD)
limit_cost_hour_block float Hourly hard limit (USD)
limit_cost_day_warn float Daily soft limit (USD)
limit_cost_day_block float Daily hard limit (USD)
limit_cost_month_warn float Monthly soft limit (USD)
limit_cost_month_block float Monthly hard limit (USD)
limit_cost_total_block float Total lifetime limit (USD)

Generating API Keys

Via Admin Dashboard

  1. Navigate to API Keys > Create Key
  2. Select the service to associate with
  3. Set key-specific limits (optional)
  4. Copy the generated key (shown only once)

Via Admin API

# Create an API key for a service
api_key = session.post(
    f"{ADMIN_URL}/api-keys",
    json={
        "name": "image-workflow-prod",
        "description": "API key for image workflow production",
        "service_id": service["id"],

        # Key-specific limits (optional, defaults to service limits)
        "limit_cost_hour_warn": 2.0,
        "limit_cost_hour_block": 5.0,
        "limit_cost_day_warn": 20.0,
        "limit_cost_day_block": 50.0
    }
).json()

print(f"API Key created: {api_key['name']}")
print(f"Key: {api_key['key']}")  # Save this! Shown only once

API Key Configuration Options

Field Type Description
name string Identifier for the key
description string Purpose of this key
service_id int Associated service
limit_cost_* float Override service limits
expires_at datetime Optional expiration date
is_active bool Enable/disable the key

Listing Available Models

# Get models for a service
response = requests.get(
    f"{API_URL}/services",
    headers={"X-API-Key": "sk_your_api_key"}
)

for service in response.json()["services"]:
    print(f"\nService: {service['name']}")
    for model in service["models"]:
        print(f"  - {model['id']}: {model['description']}")

Model Configuration

Models are defined in YAML files at /backend/model_config/{provider}.yaml:

# Example: google.yaml
models:
  gemini-2.0-flash:
    structure: "gemini_text"
    module: "google.gemini_text"
    description: "Fast text generation model"
    cost_per_million_tokens:
      input: 0.075
      output: 0.3

  gemini-3-pro-image-preview:
    structure: "gemini_image_generation"
    module: "google.gemini_image"
    description: "Image generation model"
    cost_per_million_tokens:
      input: 0.0
      output: 0.039  # Per image

Updating a Service

# Update service configuration
session.patch(
    f"{ADMIN_URL}/services/{service_id}",
    json={
        "models_enabled": [
            "gemini-2.0-flash",
            "gemini-3-pro-preview"  # Remove image model
        ],
        "limit_cost_day_block": 200.0  # Increase daily limit
    }
)

Rotating Provider Keys

# Update provider API key (encrypted automatically)
session.patch(
    f"{ADMIN_URL}/services/{service_id}",
    json={
        "provider_api_key": "AIzaSy_new_key..."
    }
)

Disabling a Service or Key

# Disable an API key
session.patch(
    f"{ADMIN_URL}/api-keys/{key_id}",
    json={"is_active": False}
)

# Re-enable
session.patch(
    f"{ADMIN_URL}/api-keys/{key_id}",
    json={"is_active": True}
)

Next Steps