API endpoints

Every endpoint. One key. One base URL.

Base URL: https://api.fikraapi.co.ke. Every route takes Authorization: Bearer fk_live_... and nothing else authenticates unless noted. Every example below is a paste-ready curl. Prices are per model at /models; billing is per 1M input/output tokens for chat and reasoning, per generation for images and video, per minute for speech-to-text, and per 1M characters for text-to-speech. Decision models bill per 1M input tokens, output is free.

POST /v1/chat/completions

Chat completions. text multimodal

OpenAI-compatible chat. Any chat model in the catalog: DeepSeek (chat, reasoning, multimodal), GLM, Kimi, Qwen, MiMo, StepFun, NVIDIA, Gemini. Image inputs work on multimodal models; pass images as base64 data URIs or public URLs.

curl https://api.fikraapi.co.ke/v1/chat/completions \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash-economy-free",
    "messages": [{"role": "user", "content": "Say hi in one word."}]
  }'
// response (abbreviated)
{
  "id": "chatcmpl-...",
  "model": "deepseek-v4-1-flash-economy-free",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hi."}, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 12, "completion_tokens": 3, "total_tokens": 15}
}
POST /v1/responses

Responses API. text

The same engine as chat completions behind the Responses shape: input + instructions instead of messages. Tool calls arrive in output items. Use it if your agent framework targets the Responses API.

curl https://api.fikraapi.co.ke/v1/responses \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "input": "Return the top 3 risks in this brief.",
    "instructions": "Be concise."
  }'
// response (abbreviated)
{
  "id": "resp-...",
  "object": "response",
  "status": "completed",
  "output": [{"type": "message", "content": [{"type": "output_text", "text": "..."}]}]
}
POST /v1/decisions

Decision models. decision

A decision model does not write a reply. It picks or scores one of the fixed answers you pass in. Billing is per 1M input tokens; output is free. The model is fixed server-side as gemini-decision-1. Body: input (what to decide over) and questions (the fixed options).

# Example: triage a support ticket to one of three routes
curl -X POST https://api.fikraapi.co.ke/v1/decisions \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input": "The card swipe failed at checkout and the customer says they were charged twice.", "questions": {"route": ["billing", "fraud", "technical"]}}'
// response (abbreviated)
{
  "candidates": [{"content": {"parts": [{"text": "billing"}]}, "tokenCount": 1}],
  "usage": {"totalInputTokens": 47, "totalOutputTokens": 0}
}

Use a decision model when the answer is one of a known set, latency matters, and a full chat answer is waste. Use chat instead when the task needs reasoning, tool calls, or free-form text. Billed $0.12 / 1M input tokens. See the decision models page for where they fit.

POST /v1/embeddings

Embeddings. embeddings

Vector embeddings via qwen-embedding. Pass a string or array of strings.

curl https://api.fikraapi.co.ke/v1/embeddings \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen-embedding", "input": ["invoice format", "PDF parsing"]}'
// response (abbreviated)
{
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.0123, -0.0483, ...]},
    {"object": "embedding", "index": 1, "embedding": [0.0021, -0.0012, ...]}
  ],
  "model": "qwen-embedding"
}
Audio

Speech to text and text to speech. audio

POST /v1/audio/transcriptions

OpenAI-compatible transcription shape. Multipart upload, model fikra-stt, billed per minute of audio.

curl https://api.fikraapi.co.ke/v1/audio/transcriptions \
  -H "Authorization: Bearer fk_live_..." \
  -F "[email protected]" \
  -F "model=fikra-stt"
// response
{ "text": "the balance is due on the 30th", "model": "fikra-stt" }

POST /v1/audio/speech

Text to speech, model fikra-tts, billed per 1M characters.

curl https://api.fikraapi.co.ke/v1/audio/speech \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "fikra-tts", "input": "Your order ships tomorrow.", "voice": "default"}' \
  --output speech.mp3
// response: binary audio stream (audio/mpeg), 200 OK
POST /v1/images/generations

Image generation. image

OpenAI-style image generation. Paid models: seedream-5.0-pro, seedream-5.0-flash, seedream-5.0-lite, seedream-4.5, seedream-4.0. seedream-5-5 is limited to 3 generations per account per day and is account-only.

curl https://api.fikraapi.co.ke/v1/images/generations \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "seedream-5.0-pro", "prompt": "A studio product shot of a blue ceramic mug."}'
// response (abbreviated)
{
  "created": 1763400000,
  "data": [{"url": "https://.../generated.png"}]
}
POST /v1/videos/generations

Video generation. video

Text-to-video and image-to-video. Today the account serves minimax-h3 (Fikra retail $0.50 per generation). The endpoint also polls async jobs. Seedance models are not enabled for this account yet and will not work.

curl -X POST https://api.fikraapi.co.ke/v1/videos/generations \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "minimax-h3", "prompt": "A slow dolly shot over a Nairobi skyline at dusk.", "duration": 6}'
// response: 202 Accepted, poll for the finished asset
{ "id": "cgt-...", "status": "processing", "model": "minimax-h3", "poll": "/v1/videos/generations/cgt-..." }
# Poll the job until status is completed
curl https://api.fikraapi.co.ke/v1/videos/generations/cgt-... \
  -H "Authorization: Bearer fk_live_..."
Models, usage and balance

Reading state. models

GET /v1/models

curl https://api.fikraapi.co.ke/v1/models \
  -H "Authorization: Bearer fk_live_..."

Returns the live catalog: id, display_name, context_window, status, pricing. Same registry that backs /models.

GET /v1/models/{model_id}

curl https://api.fikraapi.co.ke/v1/models/deepseek-v4.1-flash \
  -H "Authorization: Bearer fk_live_..."

GET /v1/balance

curl https://api.fikraapi.co.ke/v1/balance \
  -H "Authorization: Bearer fk_live_..."

Returns the authenticated key's owner balance in USD (and KES where applicable).

GET /v1/usage

curl "https://api.fikraapi.co.ke/v1/usage?days=30" \
  -H "Authorization: Bearer fk_live_..."

Per-day aggregates for the authenticated key (key_id optional, days 1..90, default 30): requests, tokens, cost.

Every endpoint bills from the same prepaid wallet. No seat fees. Limits per tier at /pricing. Service-quality telemetry at /stats. Create an account at /account/signup, or read the setup guides.