The Yakal API.
A small, OpenAI-compatible gateway for chat and images — behind curated Yakal aliases. Authenticate with a yk_… key, pay in Birr.
start hereAuthentication
yk_ keys, the Bearer header, and key scopes.
postChat completions
POST /v1/chat/completions — OpenAI-compatible.
postImage generation
POST /v1/images/generations — top-ranked models.
getList models
GET /v1/models — the curated lineup, live.
walletBilling & quota
Prepaid wallet, per-request settlement, 402s.
Introduction
Yakal exposes a clean inference API. You send prompts; Yakal runs a curated model and bills your prepaid wallet in ETB. You see only Yakal aliases, honest errors, and request IDs.
Curated, not everything. The production catalog covers reviewed chat, image, voice, and transcription models. We choose what works for Amharic, Afaan Oromoo, and Tigrinya and publish the exact ETB price for each request.
Authentication
All requests require a Yakal API key in the Authorization header as a Bearer token. Create keys in the console.
Authorization: Bearer yk_…- Keep keys secret. Treat them like passwords.
- Keys are shown once at creation; we store only a hash.
- Revoke immediately if leaked.
Base URL
All gateway endpoints live under api.yakal.et/v1. The console API (keys, billing) lives under console.yakal.et/api.
Rate limits & quota
Requests are rate-limited per key (90/minute default). Chat is billed per token, split by direction — you pay for actual usage with a 0.15 ETB minimum per message, the same rates on the console and the API gateway:
There is no negative balance: if you exceed your prepaid wallet, requests return 402; top up via Telebirr in the console.
Two DeepSeek Flash models — which one?
Both sit in the fast tier at the same price. They are different builds, and the gateway never picks for you: the model value you send decides.
| Alias | Upstream build | Use it when |
|---|---|---|
deepseek-v4.1-flash | deepseek-v4.1-flash-1017 · 17 Oct | Default. Newest build, 1M context, and the only DeepSeek that accepts images. |
Raw Workers AI ids such as @cf/deepseek-ai/deepseek-v4.1-flash-1017 are rejected with 400. Only the aliases above are valid model values.
If a model is temporarily unavailable the gateway retries the next model in the fallback chain, so the response may come from a different model than the one you asked for. The model field in every response reports what actually ran — log it when it matters.
Chat completions
OpenAI-compatible. Send a message array, get a completion. Streaming is supported — pass stream:true for server-sent events.
Returns a completion for the given conversation.
| Field | Type | Description |
|---|---|---|
| model | string · required | One of glm-5.3, glm-5.3-flash, glm-5.2, deepseek-v4.1-flash. |
| messages | array · required | OpenAI message array: {role, content}. |
| temperature | number · optional | 0–2, default per model. |
| max_tokens | integer · optional | Capped at 64,000. |
| stream | boolean · optional | true for SSE streaming deltas. |
curl https://api.yakal.et/v1/chat/completions -H "Authorization: Bearer yk_…" -H "Content-Type: application/json" -d '{"model":"glm-5.3","messages":[{"role":"user","content":""}]}'method: "POST",
headers: { Authorization: "Bearer yk_…", "Content-Type": "application/json" },
body: JSON.stringify({ model: "glm-5.3", messages: [{role: "user", content: " }] })
});
const d = await r.json();
"id": "chatcmpl-yakal-…",
"model": "glm-5.3",
"choices": [{ "message": { "role": "assistant", "content": "" }, "finish_reason": "stop" }],
"usage": { "prompt_tokens": 12, "completion_tokens": 14, "total_tokens": 26 }
}
Image generation
Generate images from a prompt. "Editing" is conversational prompt refinement — modify your words and regenerate. The output is a base64-encoded image returned in OpenAI shape.
| Field | Type | Description |
|---|---|---|
| model | string · required | One of gpt-image-2.5-flare (55 ETB), gpt-image-2.5-sunburst (70), gpt-image-2 (65), grok-image-2 (25), nano-banana-pro (50), nano-banana-2 (25), gpt-image-1.5 (60), flux-2-flex (20). |
| prompt | string · required | Up to ~2,000 chars. Amharic and Afaan Oromoo prompts work. |
| size | string · optional | 256x256 | 512x512 | 1024x1024. |
curl https://api.yakal.et/v1/images/generations -H "Authorization: Bearer yk_…" -d '{"model":"gpt-image-2","prompt":"a Lalibela rock church at golden hour"}'"created": 1789997804,
"data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…" }],
"model": "gpt-image-2"
}
List models
Returns the curated catalog with Yakal aliases.
curl https://api.yakal.et/v1/models -H "Authorization: Bearer yk_…"Model table
The full curated set with capabilities and exact prepaid ETB prices, settled from your wallet after each successful request.
| Alias | Type | Price |
|---|---|---|
| glm-5.3 | chat · flagship | 400 out / 300 in per 1M tokens |
| glm-5.3-flash | chat · fast | 90 out / 27 in per 1M tokens |
| deepseek-v4.1-flash | chat · fast · 1M ctx · vision | 182.4 out / 57 in per 1M tokens |
| glm-5.2 | chat · balanced | 300 out / 200 in per 1M tokens |
| gpt-image-2.5-flare | image · selected model | 55.00 ETB per image |
| gpt-image-2.5-sunburst | image · selected model | 55.00 ETB per image |
| gpt-image-2 | image · selected model | 55.00 ETB per image |
| grok-image-2 | image · selected model | 15.00 ETB per image |
| nano-banana-pro | image · selected model | 35.00 ETB per image |
| nano-banana-2 | image · selected model | 20.00 ETB per image |
| gpt-image-1.5 | image · selected model | 35.00 ETB per image |
| flux-2-flex | image · selected model | 15.00 ETB per image |
| ideogram-4 | image · text & posters (Higgsfield) | 15.00 ETB per image |
| soul-2 | image · fast stylized portraits (Higgsfield Soul V2) | 10.00 ETB per image |
| z-image-turbo | image · fast (Z-Image) | 10.00 ETB per image |
| flux-2-turbo | image · fast (FLUX.2 Turbo) | 15.00 ETB per image |
| qwen-image-3 | image · quality (Qwen) | 15.00 ETB per image |
| kling-image-o3 | image · pro (Kling O3) | 20.00 ETB per image |
| flux-2-pro | image · flagship (FLUX.2 Pro) | 25.00 ETB per image |
| seedream-v5-pro | image · artistry (Seedream V5 Pro) | 25.00 ETB per image |
| flux-2-max | image · max quality (FLUX.2 Max) | 30.00 ETB per image |
| gemini-3-pro-image | image · flagship (Gemini 3 Pro Image) | 55.00 ETB per image |
| minimax-image-01 | image · Minimax Image 01 | 10.00 ETB per image |
| flux-2-flash | image · FLUX.2 Flash | 10.00 ETB per image |
| recraft-v41-flash | image · Recraft 4.1 Flash | 10.00 ETB per image |
| nano-banana-lite | image · Nano Banana Lite | 10.00 ETB per image |
| nano-banana | image · Nano Banana | 15.00 ETB per image |
| gemini-25-flash-image | image · Gemini 2.5 Flash Image | 15.00 ETB per image |
| qwen-image-2512 | image · Qwen Image 2512 | 15.00 ETB per image |
| ideogram-v4-5 | image · Ideogram 4.5 | 15.00 ETB per image |
| flux-3 | image · FLUX.3 | 20.00 ETB per image |
| mai-image-2-5 | image · MAI Image 2.5 | 20.00 ETB per image |
| gemini-3-1-flash-image | image · Gemini 3.1 Flash Image | 25.00 ETB per image |
API keys
Keys are managed in the console at console.yakal.et. Each key has a prefix (shown) and a full secret (shown once). Keys are hashed at rest; revoke any time.
| Endpoint | Description |
|---|---|
| POST /api/keys | Console-only. Body: {"name": "prod-bot"}. Returns the full key once. |
| DELETE /api/keys/:id | Revokes a key. Subsequent requests with that key return 401. |
Billing & quota
Funds are prepaid ETB credits. Chat is billed per token, split by direction — glm-5.3-flash 90 out / 27 in, deepseek-v4.1-flash 182.4 out / 57 in (1M context, vision), glm-5.2 300 out / 200 in, glm-5.3 400 out / 300 in per million tokens (minimum 0.15 ETB per message); images, voice, and transcription are flat per request. There is no negative balance — inference is refused once credits are exhausted.
Telebirr top-up from the console wallet — credits are verified automatically and never expire.
| Endpoint | Purpose |
|---|---|
| GET /api/credit/info | Telebirr number + packages |
| POST /api/credit | Submit a transaction for verification |
| GET /api/credit | Your credit request history |
| GET /api/me | Current user + quota |
Errors
Yakal returns standard HTTP status codes with a friendly {"error": "…"} body.
| Code | Meaning |
|---|---|
| 400 | Bad request — missing or invalid field. |
| 401 | Missing or invalid API key. |
| 402 | Quota exceeded — top up via Telebirr. |
| 404 | Model not in the curated catalog. |
| 429 | Rate limit exceeded. |
| 500 | Internal error — retry, or contact support with your request ID. |
| 502 | Model temporarily unavailable — retry. |
Connect your coding agents
Because the Yakal gateway is OpenAI-compatible, you can point OpenCode, Pi, Codex, or Hermes at it and build whatever you want — billed in Birr, with your chat bonus applied to API chat automatically.
First, the same three steps for every tool:
- Create a
yk_…key in the console (API keys tab). - Top up with Telebirr — remember every deposit adds a 50% chat bonus that works right here on API chat.
- Set the base URL
https://api.yakal.et/v1and export the key:export YAKAL_API_KEY="yk_…"
1 · OpenCode
Add a custom provider in opencode.json (project root or ~/.config/opencode/opencode.json):
Then start it with Yakal as the model: opencode --model yakal/glm-5.3. Use yakal/glm-5.3-flash for fast iterations.
2 · Pi
Add the provider in ~/.pi/agent/models.json:
Keep contextWindow in the config. Without it Pi assumes 128,000 tokens, and once a session passes that it compacts again after every answer — each time re-sending the whole conversation. With the real window Pi compacts only when it needs to.
Open Pi and run /model to pick Yakal · glm-5.3 (press Ctrl+S to save it as your default), or launch directly with pi -m yakal/glm-5.3.
3 · Codex
Add a model provider in ~/.codex/config.toml:
Run codex and it will think, plan, and write code on Yakal models.
4 · Hermes
Hermes reads the standard OpenAI environment variables — the full step-by-step (including a connection check) is in the Hermes guide below:
Which model for agent work?
| Model | Best for |
|---|---|
| glm-5.3 | Default — strongest reasoning, 1M context for large codebases |
| glm-5.3-flash | Fast iterations and quick edits |
| deepseek-v4.1-flash | Newest DeepSeek fast tier — 1M context + image input for agent work |
| glm-5.3-flash | Fast iterations and quick edits |
API chat is billed per token from your wallet — and your referral + deposit chat bonus is spent first, so agent work runs on bonus before touching your deposited Birr.
Connect the Hermes agent
Hermes is an OpenAI-compatible coding agent. Because the Yakal gateway speaks the OpenAI protocol, you can point Hermes at Yakal in about two minutes and pay in Birr.
1. Get a Yakal API key
Sign in at console.yakal.et (verify your email first), open the API keys tab, and create a key. It looks like yk_… and is shown once — copy it somewhere safe.
Top up first. The agent bills your prepaid wallet per token. Add ETB via Telebirr in the Wallet tab before your first run — otherwise calls return 402.
2. Point Hermes at Yakal
Hermes reads the standard OpenAI environment variables. Add these to your shell profile (or your .env):
export OPENAI_BASE_URL="https://api.yakal.et/v1"
export OPENAI_API_KEY="yk_your_key_here"
export HERMES_MODEL="glm-5.3"
If your Hermes version uses OPENAI_API_BASE instead of OPENAI_BASE_URL, set that one too — both are common.
3. Verify the connection
Before launching the agent, confirm the key works:
curl https://api.yakal.et/v1/chat/completions -H "Authorization: Bearer yk_…" -H "Content-Type: application/json" -d '{"model":"glm-5.3","messages":[{"role":"user","content":"Say "}]}'You should get a JSON completion and see the debit in your Yakal wallet. If you get 401, re-copy the key; 402 means the wallet needs a top-up.
4. Run Hermes
hermesHermes will now think, write, and run code using Yakal models. Recommended aliases for agent work:
| Model | Best for |
|---|---|
| glm-5.3 | Default — strongest reasoning, 1M context for large codebases |
| glm-5.3-flash | Fast iterations and quick edits |
5. Stay in control
Watch spend in the console wallet, set per-key budget caps, and rotate keys any time — every request shows up with tokens and ETB in the usage analytics.
Ship in minutes.
Create a key, top up with Telebirr, and point your stack at api.yakal.et — OpenAI-compatible, billed in Birr.