Flutter OpenAI Custom Base URL Integration Guide

Prerequisites

• A Fikra API key (fk_live_...) from the Fikra dashboard.
• A Flutter project with Dart SDK installed.
• The openai_dart package (or equivalent OpenAI-compatible Dart client) added to your pubspec.yaml.
• Network access to https://api.fikraapi.co.ke/v1.

Environment Variable Setup

Store your API key in an environment variable to avoid hardcoding secrets. In your Flutter project, you can use the flutter_dotenv package or pass the key via build arguments.

1. Create a .env file in your project root: env FIKRA_API_KEY=fk_live_your_key_here
2. Add flutter_dotenv to pubspec.yaml: yaml dependencies: flutter_dotenv: ^5.1.0
3. Load the environment in your main.dart: ```dart import 'package:flutter_dotenv/flutter_dotenv.dart';

void main() async { await dotenv.load(fileName: ".env"); runApp(const MyApp()); } ```

Configuration and Example

Fikra API is OpenAI-compatible. You can configure the openai_dart client to use Fikra's base URL and API key.

import 'package:openai_dart/openai_dart.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart';

void main() async {
  await dotenv.load(fileName: ".env");

  final apiKey = dotenv.env['FIKRA_API_KEY']!;
  final baseUrl = 'https://api.fikraapi.co.ke/v1';

  final client = OpenAI(
    apiKey: apiKey,
    baseUrl: baseUrl,
  );

  final response = await client.chat.completions.create(
    model: 'fikra-flash',
    messages: [
      ChatMessage(role: ChatRole.user, content: 'Hello, Fikra!'),
    ],
  );

  print(response.choices.first.message.content);
}

Streaming Guidance

To enable streaming, set stream: true in the request. The response will be a stream of Server-Sent Events (SSE).

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

await for (final chunk in stream) {
  if (chunk.choices.isNotEmpty) {
    final delta = chunk.choices.first.delta;
    if (delta.content != null) {
      print(delta.content);
    }
  }
}

Common Errors

• 400 Bad Request: Invalid request body, missing required fields, or unsupported model alias. Check the model registry for available aliases.
• 401 Unauthorized: Invalid or missing API key. Ensure Authorization: Bearer fk_live_... is correctly set.
• 402 Payment Required: Insufficient token credits in your Fikra wallet. Top up via the Fikra dashboard.
• 429 Too Many Requests: Rate limit exceeded. Unverified accounts are limited to 30 RPM; trusted accounts to 100 RPM. Implement exponential backoff.
• 503 Service Unavailable: Temporary server issue. Retry with backoff.

Production Checklist

• [ ] API key stored in environment variables, not hardcoded.
• [ ] Base URL set to https://api.fikraapi.co.ke/v1.
• [ ] Model alias verified against the Fikra model registry.
• [ ] Error handling implemented for 400, 401, 402, 429, and 503.
• [ ] Streaming responses handled with proper SSE parsing.
• [ ] Rate limiting respected (30 RPM unverified, 100 RPM trusted).
• [ ] Token credit balance monitored to avoid 402 errors.
• [ ] Logging and monitoring configured for API calls.