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.

Get a key See the models

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_…

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.

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-flash · deepseek-flash0.10 out / 0.05 in per 1,000

glm-5.20.06 out / 0.04 in per 1,000

glm-5.3 · deepseek-pro0.15 out / 0.075 in per 1,000

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.

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.

Field	Type	Description
model	string · required	One of `glm-5.3`, `glm-5.3-flash`, `glm-5.2`, `deepseek-pro`, `deepseek-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.

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

Field	Type	Description
model	string · required	One of `gpt-image-2.5-flare` (70 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.

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.

Alias	Type	Price
glm-5.3	chat · flagship	0.15 out / 0.075 in per 1,000
deepseek-pro	chat · flagship	0.15 out / 0.075 in per 1,000
glm-5.3-flash	chat · fast	0.10 out / 0.05 in per 1,000
deepseek-flash	chat · fast	0.10 out / 0.05 in per 1,000
glm-5.2	chat · balanced	0.06 out / 0.04 in per 1,000
gpt-image-2.5-flare	image · AA #1	70.00 ETB per image
gpt-image-2.5-sunburst	image · AA #2	70.00 ETB per image
gpt-image-2	image · AA #3	65.00 ETB per image
grok-image-2	image · AA #4	25.00 ETB per image
nano-banana-pro	image · AA #11	50.00 ETB per image
nano-banana-2	image · AA #7	25.00 ETB per image
gpt-image-1.5	image · AA #9	60.00 ETB per image
flux-2-flex	image · AA #22	20.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.

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 — fast models 0.10 out / 0.05 in, glm-5.2 0.06 out / 0.04 in, flagship 0.15 out / 0.075 in per 1,000 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.

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:

Model	Best for
glm-5.3	Default — strongest reasoning, 1M context for large codebases
glm-5.3-flash	Fast iterations and quick edits
deepseek-pro	Long-form writing and translation

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.

Get a key See the models