Integrating Fikra API with Lobster Custom AI Endpoint

Overview

Lobster is not an OpenAI-compatible SDK. It does not natively support the OpenAI chat-completions interface via a simple base_url swap. Therefore, you cannot configure Lobster to call Fikra API using standard OpenAI SDK parameters.

Instead, you must implement a generic HTTP integration where your application (or a middleware layer) sends raw HTTP requests to the Fikra API endpoint. Below is a practical guide to integrating Fikra API using its OpenAI-compatible chat-completions interface via standard HTTP clients.

Prerequisites

1. Fikra API Key: Obtain a live API key (fk_live_...) from the Fikra dashboard.
2. Base URL: https://api.fikraapi.co.ke/v1
3. Model Alias: Use fikra-flash for general-purpose tasks. Check the model registry for other available aliases.
4. HTTP Client: Any standard HTTP client (e.g., requests in Python, fetch in JavaScript).

Environment Variable Setup

Store your API key in an environment variable to avoid hardcoding secrets.

export FIKRA_API_KEY="fk_live_your_key_here"

Python Example (Generic HTTP Integration)

Since Lobster does not provide an OpenAI-compatible client, use Python’s requests library to call the Fikra API directly.

import os
import requests

# Configuration
BASE_URL = "https://api.fikraapi.co.ke/v1"
API_KEY = os.environ.get("FIKRA_API_KEY")
MODEL = "fikra-flash"

if not API_KEY:
    raise EnvironmentError("FIKRA_API_KEY environment variable is not set.")

def chat_completion(messages):
    url = f"{BASE_URL}/chat/completions"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    payload = {
        "model": MODEL,
        "messages": messages,
        "stream": False
    }

    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()
    return response.json()

# Example usage
messages = [
    {"role": "user", "content": "Hello, Fikra!"}
]
result = chat_completion(messages)
print(result["choices"][0]["message"]["content"])

Streaming Guidance

Fikra API supports streaming via Server-Sent Events (SSE) when stream: true is set. Parse the SSE stream to handle incremental responses.

import os
import requests

BASE_URL = "https://api.fikraapi.co.ke/v1"
API_KEY = os.environ.get("FIKRA_API_KEY")
MODEL = "fikra-flash"

def stream_chat_completion(messages):
    url = f"{BASE_URL}/chat/completions"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    payload = {
        "model": MODEL,
        "messages": messages,
        "stream": True
    }

    with requests.post(url, headers=headers, json=payload, stream=True) as response:
        response.raise_for_status()
        for line in response.iter_lines():
            if line:
                decoded_line = line.decode('utf-8')
                if decoded_line.startswith("data: "):
                    data = decoded_line[6:]  # Remove "data: " prefix
                    if data == "[DONE]":
                        break
                    # Parse JSON chunk and process content
                    import json
                    chunk = json.loads(data)
                    delta = chunk["choices"][0]["delta"]
                    if "content" in delta:
                        print(delta["content"], end="", flush=True)

# Example usage
messages = [
    {"role": "user", "content": "Explain quantum computing in simple terms."}
]
stream_chat_completion(messages)

Common Errors

Production Checklist

1. API Key Security: Store FIKRA_API_KEY in a secure environment variable or secrets manager. Never hardcode it.
2. Rate Limiting: Implement client-side rate limiting to stay within 30 RPM (unverified) or 100 RPM (trusted) limits.
3. Error Handling: Handle 400, 401, 402, 429, and 503 errors gracefully. Log errors for debugging.
4. Streaming: Use stream: true for long responses to improve perceived latency. Parse SSE chunks correctly.
5. Model Alias: Use fikra-flash for general tasks. Check the model registry for other aliases if needed.
6. Monitoring: Monitor API responses for latency and error rates. Set up alerts for high error rates or 429 responses.
7. Billing: Regularly check your token-credit wallet balance to avoid 402 errors. Top up via Paystack as needed.
8. Testing: Test your integration in a staging environment before deploying to production.

Note on Lobster

Lobster does not provide an OpenAI-compatible SDK. If you require a framework with native OpenAI compatibility, consider using the OpenAI Python/JavaScript SDK with base_url="https://api.fikraapi.co.ke/v1" and api_key from FIKRA_API_KEY. Otherwise, use the generic HTTP integration outlined above.