Node.js OpenAI SDK Custom Endpoint Integration Guide

Prerequisites

• Node.js installed on your system.
• A Fikra API key generated from the Fikra dashboard.
• The openai npm package installed in your project.

Environment Variable Setup

Store your Fikra API key in an environment variable to avoid hardcoding secrets. For example, in a .env file:

FIKRA_API_KEY=fk_live_your_key_here

Load this variable in your Node.js application using a library like dotenv or your platform's environment configuration.

JavaScript Example

The OpenAI Node.js SDK supports custom base URLs. Configure it to point to the Fikra API base URL and use a listed Fikra model alias.

import OpenAI from 'openai';
import 'dotenv/config';

const client = new OpenAI({
  apiKey: process.env.FIKRA_API_KEY,
  baseURL: 'https://api.fikraapi.co.ke/v1',
});

async function main() {
  const completion = await client.chat.completions.create({
    model: 'fikra-flash',
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'Hello!' },
    ],
  });

  console.log(completion.choices[0].message.content);
}

main();

Streaming Guidance

To enable streaming, set stream: true in the request. The SDK will return an async iterable of chunks using Server-Sent Events.

const stream = await client.chat.completions.create({
  model: 'fikra-flash',
  messages: [
    { role: 'user', content: 'Tell me a short story.' },
  ],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}

Common Errors

• 400 Bad Request: The request body is malformed or contains invalid parameters. Check the model alias and message structure.
• 401 Unauthorized: The API key is missing, invalid, or expired. Verify the Authorization: Bearer fk_live_... header.
• 402 Payment Required: The token-credit wallet is empty. Top up via the Fikra dashboard using Paystack billing.
• 429 Too Many Requests: Rate limit exceeded. Unverified accounts are limited to 30 RPM; trusted accounts to 100 RPM. Implement retry logic with exponential backoff.
• 503 Service Unavailable: The service is temporarily unavailable. Retry the request after a short delay.

Production Checklist

• Use environment variables for API keys; never hardcode them.
• Implement retry logic with exponential backoff for 429 and 503 errors.
• Monitor token usage via the Fikra dashboard to manage wallet balance.
• Validate model aliases against the current Fikra model registry before deployment.
• Test streaming behavior in your target environment to ensure proper SSE handling.