Integrating Fikra API with Dify as a Custom LLM Provider

Prerequisites

• A Fikra API key (fk_live_...) generated from the Fikra dashboard.
• Dify installed and accessible (self-hosted or cloud).
• Python 3.9+ or Node.js 18+ for local testing.
• Access to the Fikra API base URL: https://api.fikraapi.co.ke/v1.

Environment Variable Setup

Set the following environment variables in your Dify deployment or local development environment:

export FIKRA_API_KEY="fk_live_your_key_here"
export FIKRA_BASE_URL="https://api.fikraapi.co.ke/v1"

Dify Custom LLM Provider Configuration

Dify supports custom LLM providers via its OpenAI-compatible interface. Since Fikra API uses an OpenAI-style chat-completions endpoint, you can configure it as a custom provider in Dify.

Steps to Add Fikra as a Custom Provider in Dify

1. Navigate to Settings > Model Provider in Dify.
2. Select Custom LLM or OpenAI-compatible provider type.
3. Enter the following details:
4. API Base URL: https://api.fikraapi.co.ke/v1
5. API Key: Your Fikra API key (fk_live_...)
6. Model Name: fikra-flash (or another listed Fikra alias such as fikra-fast-8b, fikra-pro-20b, or fikra-pro-120b)
7. Save the configuration.

Note: Dify’s custom provider support may vary by version. If your Dify instance does not support OpenAI-compatible custom providers, use the generic HTTP integration outline below.

Generic HTTP Integration Outline (If Dify Custom Provider Is Unavailable)

If Dify does not support OpenAI-compatible custom providers in your version, you can integrate Fikra API directly via HTTP requests in your application logic.

Python Example

import os
import requests

FIKRA_API_KEY = os.environ["FIKRA_API_KEY"]
FIKRA_BASE_URL = "https://api.fikraapi.co.ke/v1"

response = requests.post(
    f"{FIKRA_BASE_URL}/chat/completions",
    headers={
        "Authorization": f"Bearer {FIKRA_API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "model": "fikra-flash",
        "messages": [
            {"role": "user", "content": "Hello, Fikra!"}
        ]
    }
)

print(response.json())

JavaScript Example

const FIKRA_API_KEY = process.env.FIKRA_API_KEY;
const FIKRA_BASE_URL = "https://api.fikraapi.co.ke/v1";

async function callFikra() {
  const response = await fetch(`${FIKRA_BASE_URL}/chat/completions`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${FIKRA_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "fikra-flash",
      messages: [{ role: "user", content: "Hello, Fikra!" }]
    })
  });

  const data = await response.json();
  console.log(data);
}

callFikra();

Streaming Guidance

Fikra API supports streaming via Server-Sent Events (SSE) when stream: true is set in the request body.

Python Streaming Example

import os
import requests

FIKRA_API_KEY = os.environ["FIKRA_API_KEY"]
FIKRA_BASE_URL = "https://api.fikraapi.co.ke/v1"

response = requests.post(
    f"{FIKRA_BASE_URL}/chat/completions",
    headers={
        "Authorization": f"Bearer {FIKRA_API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "model": "fikra-flash",
        "messages": [
            {"role": "user", "content": "Hello, Fikra!"}
        ],
        "stream": True
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

JavaScript Streaming Example

const FIKRA_API_KEY = process.env.FIKRA_API_KEY;
const FIKRA_BASE_URL = "https://api.fikraapi.co.ke/v1";

async function streamFikra() {
  const response = await fetch(`${FIKRA_BASE_URL}/chat/completions`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${FIKRA_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "fikra-flash",
      messages: [{ role: "user", content: "Hello, Fikra!" }],
      stream: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    console.log(decoder.decode(value));
  }
}

streamFikra();

Common Errors

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 avoid 402 errors.
• [ ] Test streaming responses in your application to ensure proper SSE handling.
• [ ] Verify that your Dify version supports OpenAI-compatible custom providers; if not, use the generic HTTP integration.
• [ ] Check the Fikra model registry for the latest available model aliases.
• [ ] Ensure your application handles non-200 responses gracefully.
• [ ] Log request IDs (if provided) for debugging and support purposes.