easyai-ai-gateway/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-providers-and-base-models.md

Model Providers and Base Models

Read Current State

curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
  "$GATEWAY_BASE_URL/api/admin/catalog/providers"

curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
  "$GATEWAY_BASE_URL/api/admin/catalog/base-models"

Public read-only catalog endpoints also exist at /api/v1/public/catalog/providers and /api/v1/public/catalog/base-models.

Provider Catalog

Create a provider:

curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "providerKey": "example-openai",
    "code": "example-openai",
    "displayName": "Example OpenAI Compatible",
    "providerType": "openai",
    "defaultBaseUrl": "https://api.example.com/v1",
    "defaultAuthType": "APIKey",
    "source": "gateway",
    "capabilitySchema": {},
    "defaultRateLimitPolicy": {},
    "metadata": {"protocol": "openai-compatible"},
    "status": "active"
  }' \
  "$GATEWAY_BASE_URL/api/admin/catalog/providers"

Use PATCH /api/admin/catalog/providers/{providerID} with the complete current provider body to update. providerType selects the runtime client through the platform candidate. Common supported values include openai, gemini, volces, keling, minimax, and universal. Unknown types may fall back to the OpenAI client, so never leave a custom integration type ambiguous.

Delete with DELETE /api/admin/catalog/providers/{providerID} only after checking platform references and obtaining confirmation.

Base Model

Create a base model after its provider exists:

curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "providerKey": "example-openai",
    "canonicalModelKey": "example-openai:example-chat",
    "providerModelName": "example-chat",
    "modelType": ["text_generate"],
    "modelAlias": "example-chat",
    "displayName": "Example Chat",
    "capabilities": {
      "text_generate": {
        "supportedApiProtocols": ["openai_chat_completions"]
      }
    },
    "baseBillingConfig": {
      "textInputPer1k": 0.001,
      "textOutputPer1k": 0.002
    },
    "defaultRateLimitPolicy": {},
    "runtimePolicyOverride": {},
    "metadata": {"description": "Example OpenAI-compatible chat model"},
    "catalogType": "custom",
    "defaultSnapshot": {},
    "pricingVersion": 1,
    "status": "active"
  }' \
  "$GATEWAY_BASE_URL/api/admin/catalog/base-models"

Use PATCH /api/admin/catalog/base-models/{baseModelID} with a complete body to update. Do not omit capabilities, billing, policy bindings, metadata, or status unintentionally.

Reset endpoints are destructive:

• POST /api/admin/catalog/base-models/{baseModelID}/reset
• POST /api/admin/catalog/base-models/reset-all

Only system-seeded models with default snapshots can be reset. Delete with DELETE /api/admin/catalog/base-models/{baseModelID} only after checking platform-model bindings.