Adding Custom Providers
If you need to use a provider not listed in Lava’s supported providers, you can use the “Other” provider category with unmanaged provider keys.
Custom providers require users to bring their own API keys. Lava can still meter and bill for usage, but cannot manage authentication automatically.
How Custom Providers Work
- Configure Product: Set your product to use unmanaged provider keys
- User API Keys: Your users include their own API keys in requests
- Lava Tracking: Lava tracks usage and bills based on your configured fees
- Any REST API: Works with any REST API endpoint
Configuration Requirements
Product Configuration
In your Lava product settings:
{
"provider": "other",
"managedKeys": false,
"feeStructure": {
"fixedFee": 0.10, // Your fee per request
"percentageFee": 0 // Or percentage markup
},
"billingBasis": "requests" // Or "tokens", "characters", "duration"
}
API Endpoint Requirements
Custom provider endpoints must:
- ✅ Accept HTTP/HTTPS requests
- ✅ Return JSON responses (for automatic usage extraction)
- ✅ Support standard REST verbs (GET, POST, PUT, DELETE)
- ✅ Include usage metadata in responses (optional but recommended)
Usage Pattern
With User-Provided API Keys
const response = await fetch(
'https://api.lavapayments.com/v1/forward?u=' +
encodeURIComponent('https://custom-ai-provider.com/v1/inference'),
{
method: 'POST',
headers: {
'Authorization': `Bearer ${forwardToken}`,
'Content-Type': 'application/json',
'X-Provider-API-Key': userProvidedApiKey // User's own key
},
body: JSON.stringify({
model: "custom-model",
input: "Your prompt here"
})
}
);
Response Handling
Lava automatically tracks:
- Request count (always)
- Tokens (if included in response as
usage.tokens)
- Characters (if included in response as
usage.characters)
- Duration (if included in response as
usage.duration_seconds)
Standard response format for automatic tracking:
{
"result": "...",
"usage": {
"tokens": 1234,
"characters": 5678,
"duration_seconds": 2.5
}
}
Billing Basis Options
Request-Based Billing
Charge per API call regardless of usage:
{
"billingBasis": "requests",
"feeStructure": {
"fixedFee": 0.05 // $0.05 per request
}
}
Token-Based Billing
Charge per token (requires response to include token count):
{
"billingBasis": "tokens",
"feeStructure": {
"fixedFee": 0.00001 // Per token
}
}
{
"usage": {
"tokens": 1250
}
}
Character-Based Billing
Charge per character (requires response to include character count):
{
"billingBasis": "characters",
"feeStructure": {
"fixedFee": 0.000001 // Per character
}
}
Duration-Based Billing
Charge per second/minute (requires response to include duration):
{
"billingBasis": "duration",
"feeStructure": {
"fixedFee": 0.10 // Per second
}
}
Authentication Methods
Bearer Token:
Authorization: Bearer <user_api_key>
X-API-Key: <user_api_key>
X-Custom-Auth: <user_token>
Query Parameter Authentication
https://custom-provider.com/api?key=<user_api_key>
{
"usage": {
"tokens": 1234,
"input_tokens": 500,
"output_tokens": 734,
"characters": 5678,
"duration_seconds": 2.5
}
}
Manual Usage Reporting
If your provider doesn’t include usage in responses, use request-based billing:
{
"billingBasis": "requests",
"feeStructure": {
"fixedFee": 0.10 // Flat fee per request
}
}
Testing Custom Integration
1. Test API Endpoint Directly
Verify the custom provider works with user API keys:
curl -X POST https://custom-provider.com/v1/inference \
-H "Authorization: Bearer USER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "custom-model", "input": "test"}'
2. Test Through Lava Proxy
Verify Lava forwards requests correctly:
curl -X POST "https://api.lavapayments.com/v1/forward?u=https://custom-provider.com/v1/inference" \
-H "Authorization: Bearer FORWARD_TOKEN" \
-H "X-Provider-API-Key: USER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "custom-model", "input": "test"}'
3. Verify Usage Tracking
Check the response for usage tracking:
x-lava-request-id: req_01234567890abcdef (request tracking header)
Limitations
Custom providers do NOT support:
- ❌ Managed API keys (Lava cannot authenticate on behalf of users)
- ❌ Automatic provider-specific parsing (unless response follows standard format)
- ❌ Built-in model pricing (you set all fees)
- ❌ Provider-specific features (streaming, function calling, etc. depend on provider support)
Custom providers DO support:
- ✅ Any REST API endpoint
- ✅ Standard HTTP authentication methods
- ✅ Automatic usage extraction from standard response fields
- ✅ All Lava billing features (prepaid wallets, subscriptions, autopay)
- ✅ Usage tracking and analytics
Troubleshooting
Issue: No Usage Tracked
Problem: Lava shows 0 tokens/characters but request succeeded
Solution:
- Check if response includes
usage field
- If not, switch to request-based billing
- Or manually calculate and include usage in response
Issue: Authentication Failed
Problem: Provider returns 401 Unauthorized
Solution:
- Verify user API key is correct
- Check authentication header format matches provider requirements
- Ensure API key is included in request (not just forward token)
Issue: Provider Not Responding
Problem: Request times out or fails
Solution:
- Test provider endpoint directly (outside Lava)
- Check provider API status
- Verify endpoint URL is correct and accessible
Next Steps
