Fikra API: Token-Credit Wallet and M-Pesa Billing

Overview

Fikra API provides an OpenAI-compatible interface for accessing Fikra models. Unlike some external providers that bill per request directly to a credit card, Fikra uses a token-credit wallet system. This guide explains how the billing model works and how to manage your account balance.

What is a Token-Credit Wallet?

A token-credit wallet is a prepaid balance system. Instead of paying for each API call individually, you top up your account with credits. When you make a request to the Fikra API, the cost of the tokens used (input and output) is deducted from this wallet balance. This model offers predictable costs and immediate access to the API once funds are available.

Account and Top-Up Flow

Access to the Fikra API is managed through the Fikra dashboard. The high-level flow for setting up and funding your account is as follows:

1. Create an Account: Sign up on the Fikra dashboard at fikraapi.co.ke.
2. Generate API Keys: Create API keys (starting with fk_live_...) within the dashboard. These keys are required for authentication.
3. Top Up Balance: Navigate to the billing section of the dashboard. Fikra integrates with Paystack for billing. Publicly, Fikra states that M-Pesa and cards are accepted payment methods.
   • Note: Specific payment availability, exchange rates, and minimum deposit amounts may vary. Always confirm the current payment options and limits directly in the Fikra dashboard or with Fikra support before attempting a transaction.

Monitoring Balance and Handling HTTP 402

Since the API is prepaid, it is critical to monitor your wallet balance to avoid service interruptions.

• Check Balance: Regularly check your remaining credits in the Fikra dashboard. You can also implement logic in your application to check the balance via the dashboard API if available, or simply track usage locally.
• Handle HTTP 402: If your wallet balance is insufficient to cover the cost of a request, the Fikra API will return an HTTP 402 Payment Required status code.
  • Best Practice: Implement error handling in your client code to catch 402 responses. When this occurs, pause API calls and notify the user or administrator that the account needs to be topped up. Do not retry the request immediately, as it will fail until the balance is restored.

Security Advice

• Never Expose API Keys in Browser Code: Fikra API keys (fk_live_...) are sensitive credentials. Never include them in client-side JavaScript, HTML, or any code that runs in the user's browser. This exposes your key to theft and unauthorized usage.
• Use Server-Side Proxies: Always make API calls from your backend server. Your server should hold the API key securely (e.g., in environment variables) and proxy requests to the Fikra API on behalf of your frontend.
• Environment Variables: Store your API key in an environment variable (e.g., FIKRA_API_KEY) on your server. Never hardcode keys in source code or commit them to version control.

Code Example: Secure Server-Side Usage

Below is an example of how to securely use the Fikra API from a Node.js backend. Note that the API key is read from an environment variable.

const OpenAI = require('openai');

// Initialize the client with the Fikra base URL and API key from environment
const client = new OpenAI({
  baseURL: 'https://api.fikraapi.co.ke/v1',
  apiKey: process.env.FIKRA_API_KEY,
});

async function generateResponse() {
  try {
    const completion = await client.chat.completions.create({
      model: 'fikra-flash', // Use a valid Fikra model alias
      messages: [
        { role: 'user', content: 'Hello, Fikra!' }
      ],
    });
    console.log(completion.choices[0].message.content);
  } catch (error) {
    if (error.status === 402) {
      console.error('Payment Required: Insufficient balance. Please top up your Fikra wallet.');
    } else {
      console.error('API Error:', error.message);
    }
  }
}

// Call the function
// generateResponse();

Important Notes

• Model Availability: The model aliases listed (e.g., fikra-flash, fikra-pro-20b) are current public aliases. Always check the Fikra model registry in the dashboard for the latest available models.
• Rate Limits: Unverified accounts are limited to 30 requests per minute (RPM), while trusted accounts are limited to 100 RPM. Ensure your application respects these limits.
• Payment Confirmation: While M-Pesa and cards are publicly stated as accepted methods, specific transaction details (such as exact fees or processing times) should be confirmed within the Fikra dashboard or with Fikra support.

For more information, visit fikraapi.co.ke.