API Reference

The OpenDunes API is OpenAI-compatible: point any OpenAI SDK at https://opendunes.com/api/v1 with your key and your existing code works. Every response is billed in Algerian Dinars (DA) and deducted from your balance in real time.

Requests#

Request format#

Send a POST to /v1/chat/completions with a JSON body. The minimum valid request needs a model slug and a messages array.

curl https://opendunes.com/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-pro",
    "messages": [{ "role": "user", "content": "What is the capital of Algeria?" }]
  }'

Headers#

The Authorization header carries your API key as a Bearer token. Keys begin with sk- and are only shown in full at creation time — only a hash is stored on our end. See Authentication.

Assistant prefill#

To steer the model's response, include a trailing assistant message in your messages array. The model will continue from that text rather than starting fresh.

{
  "model": "anthropic/claude-opus-4.8",
  "messages": [
    { "role": "user", "content": "List three Algerian cities." },
    { "role": "assistant", "content": "1." }
  ]
}

Note. Not all models honor prefill. The behavior is provider-dependent and passed through as-is.

Responses#

Response format#

Successful responses are standard OpenAI-compatible JSON with a choices array and a usage object.

{
  "id": "chatcmpl-01938fae2a7b7000aabbccdd",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "google/gemini-2.5-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of Algeria is Algiers (الجزائر)."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 14,
    "total_tokens": 32
  }
}

Finish reason#

choices[0].finish_reason explains why generation stopped.

Querying cost and usage#

The usage object in every response shows prompt_tokens, completion_tokens, and total_tokens for the request. Multiply by the model's DA per-million-token rate to get the exact cost, or check /dashboard/analytics for itemized history. Non-chat surfaces return their own usage shape — embeddings report prompt_tokens, transcription reports audio seconds, and so on (see each surface's API page).

The X-Balance-Available response header gives your remaining balance in micro-DA (one-millionth of a Dinar) so you can monitor headroom without a separate API call.

X-Balance-Available: 48320000
X-Request-Id: 019383ab-1234-7000-a000-000000000001

See Rate Limits for the full set of response headers.

Usage analytics API#

For aggregate reporting beyond a single response, the dashboard analytics endpoints are available to session-authenticated requests:

per-surface is the one to watch once you use more than chat — it breaks your spend down by surface so you can see how much goes to images vs. transcription vs. embeddings.