yakal.etAPI Docs
api reference · v1 ·
API Reference · v1 ·

The Yakal API.

A small, OpenAI-compatible gateway for chat and images — behind curated Yakal aliases. Authenticate with a yk_… key, pay in Birr.

OpenAI-compatible · chat & images
start here

Authentication

yk_ keys, the Bearer header, and key scopes.

post

Chat completions

POST /v1/chat/completions — OpenAI-compatible.

post

Image generation

POST /v1/images/generations — top-ranked models.

get

List models

GET /v1/models — the curated lineup, live.

wallet

Billing & 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.

headerrequired
$Authorization: Bearer yk_…

Base URL

All gateway endpoints live under api.yakal.et/v1. The console API (keys, billing) lives under console.yakal.et/api.

Inference gatewayhttps://api.yakal.et/v1
Console APIhttps://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:

glm-5.3-flash90 out / 27 in per 1M tokens
deepseek-v4.1-flash182.4 out / 57 in per 1M tokens · 1M context · vision
glm-5.2300 out / 200 in per 1M tokens
glm-5.3400 out / 300 in per 1M tokens
Minimum per message0.15 ETB
Images, voice, transcriptionflat per request

There is no negative balance: if you exceed your prepaid wallet, requests return 402; top up via Telebirr in the console.

note

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.

AliasUpstream buildUse it when
deepseek-v4.1-flashdeepseek-v4.1-flash-1017 · 17 OctDefault. 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

Chat completions

OpenAI-compatible. Send a message array, get a completion. Streaming is supported — pass stream:true for server-sent events.

POST/v1/chat/completions

Returns a completion for the given conversation.

FieldTypeDescription
modelstring · requiredOne of glm-5.3, glm-5.3-flash, glm-5.2, deepseek-v4.1-flash.
messagesarray · requiredOpenAI message array: {role, content}.
temperaturenumber · optional0–2, default per model.
max_tokensinteger · optionalCapped at 64,000.
streamboolean · optionaltrue for SSE streaming deltas.
cURLbash
$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":""}]}'
JavaScriptfetch
const r = await fetch("https://api.yakal.et/v1/chat/completions", {
  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();
Response200
{
  "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 }
}
images

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.

POST/v1/images/generations
FieldTypeDescription
modelstring · requiredOne 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).
promptstring · requiredUp to ~2,000 chars. Amharic and Afaan Oromoo prompts work.
sizestring · optional256x256 | 512x512 | 1024x1024.
cURLbash
$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"}'
Response200
{
  "created": 1789997804,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…" }],
  "model": "gpt-image-2"
}
catalog

List models

Returns the curated catalog with Yakal aliases.

GET/v1/models
cURLbash
$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.

AliasTypePrice
glm-5.3chat · flagship400 out / 300 in per 1M tokens
glm-5.3-flashchat · fast90 out / 27 in per 1M tokens
deepseek-v4.1-flashchat · fast · 1M ctx · vision182.4 out / 57 in per 1M tokens
glm-5.2chat · balanced300 out / 200 in per 1M tokens
gpt-image-2.5-flareimage · selected model55.00 ETB per image
gpt-image-2.5-sunburstimage · selected model55.00 ETB per image
gpt-image-2image · selected model55.00 ETB per image
grok-image-2image · selected model15.00 ETB per image
nano-banana-proimage · selected model35.00 ETB per image
nano-banana-2image · selected model20.00 ETB per image
gpt-image-1.5image · selected model35.00 ETB per image
flux-2-fleximage · selected model15.00 ETB per image
ideogram-4image · text & posters (Higgsfield)15.00 ETB per image
soul-2image · fast stylized portraits (Higgsfield Soul V2)10.00 ETB per image
z-image-turboimage · fast (Z-Image)10.00 ETB per image
flux-2-turboimage · fast (FLUX.2 Turbo)15.00 ETB per image
qwen-image-3image · quality (Qwen)15.00 ETB per image
kling-image-o3image · pro (Kling O3)20.00 ETB per image
flux-2-proimage · flagship (FLUX.2 Pro)25.00 ETB per image
seedream-v5-proimage · artistry (Seedream V5 Pro)25.00 ETB per image
flux-2-maximage · max quality (FLUX.2 Max)30.00 ETB per image
gemini-3-pro-imageimage · flagship (Gemini 3 Pro Image)55.00 ETB per image
minimax-image-01image · Minimax Image 0110.00 ETB per image
flux-2-flashimage · FLUX.2 Flash10.00 ETB per image
recraft-v41-flashimage · Recraft 4.1 Flash10.00 ETB per image
nano-banana-liteimage · Nano Banana Lite10.00 ETB per image
nano-bananaimage · Nano Banana15.00 ETB per image
gemini-25-flash-imageimage · Gemini 2.5 Flash Image15.00 ETB per image
qwen-image-2512image · Qwen Image 251215.00 ETB per image
ideogram-v4-5image · Ideogram 4.515.00 ETB per image
flux-3image · FLUX.320.00 ETB per image
mai-image-2-5image · MAI Image 2.520.00 ETB per image
gemini-3-1-flash-imageimage · Gemini 3.1 Flash Image25.00 ETB per image
keys & billing

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.

EndpointDescription
POST /api/keysConsole-only. Body: {"name": "prod-bot"}. Returns the full key once.
DELETE /api/keys/:idRevokes 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.

EndpointPurpose
GET /api/credit/infoTelebirr number + packages
POST /api/creditSubmit a transaction for verification
GET /api/creditYour credit request history
GET /api/meCurrent user + quota

Errors

Yakal returns standard HTTP status codes with a friendly {"error": "…"} body.

CodeMeaning
400Bad request — missing or invalid field.
401Missing or invalid API key.
402Quota exceeded — top up via Telebirr.
404Model not in the curated catalog.
429Rate limit exceeded.
500Internal error — retry, or contact support with your request ID.
502Model temporarily unavailable — retry.
guides

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:

1 · OpenCode

Add a custom provider in opencode.json (project root or ~/.config/opencode/opencode.json):

opencode.jsonconfig
{ "provider": { "yakal": { "npm": "@ai-sdk/openai-compatible", "name": "Yakal", "options": { "baseURL": "https://api.yakal.et/v1", "apiKey": "{env:YAKAL_API_KEY}" }, "models": { "glm-5.3": { "limit": { "context": 1048576, "output": 16384 } }, "glm-5.3-flash": { "limit": { "context": 1048576, "output": 16384 } }, "deepseek-v4.1-flash": { "limit": { "context": 1048576, "output": 16384 } } } } } }

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:

~/.pi/agent/models.jsonconfig
{ "providers": { "yakal": { "baseUrl": "https://api.yakal.et/v1", "api": "openai-completions", "apiKey": "$YAKAL_API_KEY", "models": [ { "id": "glm-5.3", "contextWindow": 1048576, "maxTokens": 16384, "reasoning": true }, { "id": "glm-5.3-flash", "contextWindow": 1048576, "maxTokens": 16384, "reasoning": true }, { "id": "deepseek-v4.1-flash", "contextWindow": 1048576, "maxTokens": 16384, "reasoning": true } ] } } }

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:

~/.codex/config.tomlconfig
model = "glm-5.3" model_provider = "yakal" model_context_window = 1048576 model_max_output_tokens = 16384 [model_providers.yakal] name = "Yakal" base_url = "https://api.yakal.et/v1" env_key = "YAKAL_API_KEY" wire_api = "chat"

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:

~/.zshrcenv
export OPENAI_BASE_URL="https://api.yakal.et/v1" export OPENAI_API_KEY="yk_your_key_here"

Which model for agent work?

ModelBest for
glm-5.3Default — strongest reasoning, 1M context for large codebases
glm-5.3-flashFast iterations and quick edits
deepseek-v4.1-flashNewest DeepSeek fast tier — 1M context + image input for agent work
glm-5.3-flashFast 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.

guides

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):

~/.zshrcenv
# ~/.bashrc or ~/.zshrc
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:

verifybash
$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

runbash
$hermes

Hermes will now think, write, and run code using Yakal models. Recommended aliases for agent work:

ModelBest for
glm-5.3Default — strongest reasoning, 1M context for large codebases
glm-5.3-flashFast 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.

get a key

Ship in minutes.

Create a key, top up with Telebirr, and point your stack at api.yakal.et — OpenAI-compatible, billed in Birr.