𝐗𝐀𝐈 𝐗𝐀𝐏𝐈

Keys API

All endpoints require an Authorization: Bearer sk-Xvs... header.

Base URL: https://api.xaixapi.com

—

Overview

  • List/Filter keys: GET /x-keys, GET /x-keys/{id|L{n}|{provider}}
  • Create key: POST /x-keys
  • Update key: PUT /x-keys/{id} (also supports POST /x-keys/{id})
  • Delete key: DELETE /x-keys/{id}
  • Utilities: GET /x-gkey, GET /x-ekey/{plain}, GET /x-dkey/{cipher}
  • Owner overview: GET /x-conf (resources/mappers/limits/sleeping/disabled keys)

—

Query and filter

  • GET /x-keys accepts:

    • id filter by key ID
    • level filter by Level
    • provider filter by upstream provider (full URL or host)
    • page, size for pagination (optional)

  • Path filters:

    • GET /x-keys/{id} fetch by numeric ID
    • GET /x-keys/L{n} filter by Level (e.g. L2)
    • GET /x-keys/{provider} filter by provider (e.g. api.anthropic.com)

Examples

# All keys (brief)
curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/x-keys

# Keys in Level 2
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.xaixapi.com/x-keys?level=2"

# Keys of a provider
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.xaixapi.com/x-keys?provider=https://api.openai.com"

—

Create key

  • Endpoint: POST /x-keys
  • Scope: owner or privileged parent under the current owner (OID)

Request body (common fields):

{
  "SecretKey": "sk-...",         // Upstream provider key (required, min 20 chars)
  "Name": "Production - OpenAI", // Optional display name
  "Level": 1,                    // Load pool level for routing/failover (required)
  "Provider": "https://api.openai.com", // Upstream API host (required, valid URL)
  "Status": true,                // Enable/disable (default true)
  "Config": {                    // Optional, provider_type specific
    "provider_type": "standard"  // Config type: standard/azure/vertex
  }
}

Config Field Reference

The Config field configures special provider types (Azure OpenAI, Google Vertex AI). Different provider_type values require different configuration parameters.

1. Standard Configuration

For standard OpenAI-compatible providers (OpenAI, Anthropic, Mistral, DeepSeek, etc.).

{
  "SecretKey": "sk-...",
  "Name": "OpenAI Production",
  "Level": 1,
  "Provider": "https://api.openai.com",
  "Status": true,
  "Config": {
    "provider_type": "standard"  // Optional, defaults to standard
  }
}

2. Azure OpenAI Configuration

For Azure OpenAI Service.

{
  "SecretKey": "your-azure-api-key",
  "Name": "Azure OpenAI",
  "Level": 2,
  "Provider": "https://your-resource.openai.azure.com",
  "Status": true,
  "Config": {
    "provider_type": "azure",
    "model_mapping": {
      "gpt-4o": "gpt-4-deployment",      // Model name -> Deployment name
      "gpt-4": "my-gpt4-deployment",
      "gpt-3.5*": "gpt35-turbo",         // Supports wildcards
      "*": "default-deployment"          // Default deployment
    },
    "api_versions": {                    // Optional, API versions per endpoint
      "chat": "2025-01-01-preview",
      "embeddings": "2024-02-01",
      "responses": "2025-04-01-preview",
      "audio": "2025-03-01-preview",
      "images": "2025-04-01-preview"
    }
  }
}

Azure configuration notes:

  • Provider should be your Azure endpoint, e.g., https://your-resource.openai.azure.com
  • model_mapping maps standard model names to Azure deployment names
  • api_versions specifies API version per endpoint (optional, uses system env vars if empty)

3. Google Vertex AI Configuration

For Google Cloud Vertex AI.

{
  "SecretKey": "sk-placeholder-51chars-xxxxxxxxxxxxxxxxxxxxxxxx",  // Vertex still needs 51-char placeholder
  "Name": "Vertex AI",
  "Level": 3,
  "Provider": "https://us-central1-aiplatform.googleapis.com",   // Placeholder URL
  "Status": true,
  "Config": {
    "provider_type": "vertex",
    "base_url": "https://us-central1-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}",
    "project_id": "my-gcp-project",
    "client_email": "[email protected]",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----\n"
  }
}

Vertex AI configuration notes:

  • Provider and SecretKey are placeholders but must meet format requirements
  • base_url includes project and location information
  • project_id Google Cloud project ID
  • client_email Service account email
  • private_key Service account private key (PEM format, system auto-cleans and encrypts)

Behavior notes:

  • Sensitive fields in Config (e.g., Vertex private_key) are automatically cleaned and encrypted before storage
  • After creation, the system attempts to auto-augment LEVEL_MAPPER using provider matching (exact and similarity), helping requests route to the correct Level
  • Provider URL cannot self-reference (cannot point to current system)
  • System automatically refreshes Redis cache and memory structures

Standard provider example:

curl -X POST https://api.xaixapi.com/x-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "sk-live-...",
    "Name": "OpenAI main",
    "Level": 1,
    "Provider": "https://api.openai.com",
    "Status": true
  }'

Azure OpenAI example:

curl -X POST https://api.xaixapi.com/x-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "your-azure-key",
    "Name": "Azure GPT-4",
    "Level": 2,
    "Provider": "https://your-resource.openai.azure.com",
    "Status": true,
    "Config": {
      "provider_type": "azure",
      "model_mapping": {
        "gpt-4o": "gpt-4-deployment",
        "gpt-3.5*": "gpt35-turbo"
      }
    }
  }'

Vertex AI example:

curl -X POST https://api.xaixapi.com/x-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "sk-placeholder-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Name": "Vertex Gemini",
    "Level": 3,
    "Provider": "https://us-central1-aiplatform.googleapis.com",
    "Status": true,
    "Config": {
      "provider_type": "vertex",
      "base_url": "https://us-central1-aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1",
      "project_id": "my-gcp-project",
      "client_email": "[email protected]",
      "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n"
    }
  }'

—

Update key

  • Endpoint: PUT /x-keys/{id} (also POST)
  • Editable fields: Name, Level, Status, Provider, Config.
curl -X PUT https://api.xaixapi.com/x-keys/123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Level": 2, "Status": true}'

—

Delete key

  • Endpoint: DELETE /x-keys/{id}
curl -X DELETE https://api.xaixapi.com/x-keys/123 \
  -H "Authorization: Bearer $API_KEY"

—

Utilities

  • Generate random API key: GET /x-gkey
curl -H "Authorization: Bearer $API_KEY" https://api.xaixapi.com/x-gkey
  • Symmetric encryption helpers (platform-wide secret):
    • Encrypt: GET /x-ekey/{plain} → { "EncryptedKey": "..." }
    • Decrypt: GET /x-dkey/{cipher} → { "DecryptedKey": "..." }

—

Owner overview

  • GET /x-conf returns for the current owner:
    • Resources allowlist of API paths
    • LevelMapper, ModelMapper, ModelLimits, SwitchOver
    • SleepingKeys with remaining sleep times; DisabledKeys
    • Thresholds: UserMinBalance, UserApiBalance
curl -H "Authorization: Bearer $API_KEY" https://api.xaixapi.com/x-conf | jq .

—

Best practices

  • Split providers or pricing tiers into different Levels and map models to Levels with LEVEL_MAPPER.
  • Add multiple keys for rate-limited providers; the system will round-robin and auto-sleep failing keys, improving success rate.
  • Use MODEL_LIMITS to cap expensive models (per-model RPM/TPM), preventing cost spikes.
← Access Control (ACL)
Getting Started with Self-Hosted XAI Router →