# Galon AI

> A chat completions API, OpenAI-compatible (Chat Completions), paid per token from your prepaid balance.

## Before you start

- A Galon account, a project with a prepaid balance (requests are reserved on the balance before the model runs), and a key with `ai:inference`.
- Test and live keys both call real models and both spend the balance.

## Quickstart

Every example reads `GALON_API_BASE` (`https://api.galon.ai/v1`) and `GALON_API_KEY` from the environment and prints the HTTP status and the JSON body.

**1. Set your key.** Export the base URL and your key.

**curl**

```bash
export GALON_API_BASE="https://api.galon.ai/v1"
export GALON_API_KEY="gln_..."
```

**2. List the models.** Use one returned `id` as `model`. When prices are published for a model, they are in the entry (`input_usd_micro_per_million`, `output_usd_micro_per_million`).

**curl**

```bash
curl -sS -X GET "$GALON_API_BASE/ai/models" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/ai/models",
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
    method="GET",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/ai/models`, {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` },
});
console.log(res.status, JSON.stringify(await res.json()));
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "list_ai_models", "arguments": {}}}' \
  -w '\n%{http_code}\n'
```

**3. Ask a question.** Any OpenAI-compatible (Chat Completions) client works as is. For safe retries, send your own `Idempotency-Key` (8 to 200 characters) and reuse it: replaying a key never runs the model twice, it answers `409` (see Errors). Without the header, the server sets one and returns it in the `Idempotency-Key` response header. The response headers also carry `X-Request-Id` and the amount charged.

**curl**

```bash
curl -sS -X POST "$GALON_API_BASE/ai/chat/completions" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Idempotency-Key: quickstart-chat-0001" \
  -H "Content-Type: application/json" \
  -d '{"model": "'"$GALON_AI_MODEL"'", "messages": [{"role": "user", "content": "Say hello in French."}], "max_tokens": 50}' \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/ai/chat/completions",
    data=json.dumps({"model": os.environ["GALON_AI_MODEL"], "messages": [{"role": "user", "content": "Say hello in French."}], "max_tokens": 50}).encode(),
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
             "Idempotency-Key": "quickstart-chat-0001",
             "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/ai/chat/completions`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Idempotency-Key": "quickstart-chat-0001", "Content-Type": "application/json" },
  body: JSON.stringify({model: process.env.GALON_AI_MODEL, messages: [{role: "user", content: "Say hello in French."}], max_tokens: 50}),
});
console.log(res.status, JSON.stringify(await res.json()));
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "create_chat_completion", "arguments": {"idempotency_key": "quickstart-chat-0001", "model": "'"$GALON_AI_MODEL"'", "messages": [{"role": "user", "content": "Say hello in French."}], "max_tokens": 50}}}' \
  -w '\n%{http_code}\n'
```

## Concepts

**OpenAI-compatible (Chat Completions).** Point any client of this API standard at `$GALON_API_BASE/ai`: no extra header is needed. Send your own `Idempotency-Key` when you want safe retries. A field that is not supported is refused with `ai_field_not_supported` and `field`, never ignored.

**Prices.** Every model is priced per million tokens, in US dollars, input and output apart (`GET /v1/ai/models`). The price you see is the price you are charged: the amount of each request comes back in the response headers, and your statement sums them to the cent.

**Reserve, then settle.** Each request reserves an amount on the project balance before the model is called (`402` if the balance does not cover it), then is settled at the usage received. An interrupted stream is billed for what was received.

**Streaming.** `stream: true` returns `text/event-stream` when the model serves it; otherwise `ai_streaming_not_supported`.

**Caps.** Default request quotas per project and day / month, and spending caps per request, day and month. A key can carry its own lower spending cap (`ai_key_limit_reached`).

**Rate limits.** Each key has a sliding one-minute window of requests and of tokens (input bound plus the maximum output requested); the values are on the Limits page and in the console overview (`limits`). Every response carries `RateLimit-Policy` and `RateLimit` headers; over the limit, `429 ai_rate_limited` says the limit, the usage and `Retry-After`.

## API reference

Derived from the OpenAPI 3.1 contract at each request: every operation of Galon AI you can reach today, with its full page (parameters, bodies, responses, examples). Base URL: the public API endpoint, `$GALON_API_BASE`.

| Method | Path | Summary |
|---|---|---|
| POST | [`/v1/ai/chat/completions`](/cloud/docs/api/ai-chat-completions) | Generate a response (chat completions compatible) |
| GET | [`/v1/ai/models`](/cloud/docs/api/ai-models) | List served models |
| POST | [`/v1/ai/embeddings`](/cloud/docs/api/ai-embeddings) | Compute embeddings |

## Errors

Every error is JSON: `{"detail": {"code", "message", "next_action"}}`. `next_action.code` is stable, `next_action.hint` says what to do next, and `console_url` is added when a person must act. The codes below are those this service returns.

| Status | Code | When | next_action |
|---|---|---|---|
| 401 | `api_key_missing` | No `Authorization: Bearer` header. | `use_valid_api_key` |
| 403 | `scope_missing` | The key lacks `ai:inference`. | `add_missing_scope` |
| 400 | `idempotency_key_invalid` | An `Idempotency-Key` header that is not 8 to 200 printable characters. | `fix_request` |
| 400 | `ai_field_not_supported` | A field the API does not accept (`field` names it). | `fix_request` |
| 400 | `ai_parameter_invalid` | A value out of range (`field` names it). | `fix_request` |
| 404 | `ai_model_not_found` | `model` is not a served id: list `/v1/ai/models`. | `check_resource_id` |
| 413 | `ai_input_too_large` | The messages are over the input limit. | `fix_request` |
| 402 | `ai_wallet_insufficient_funds` | The balance does not cover the reservation. | `top_up_balance` |
| 402 | `ai_budget_exhausted` | The daily or monthly spending cap is reached. | `raise_limit_or_plan` |
| 402 | `ai_key_limit_reached` | This key's own spending cap is reached. | `raise_limit_or_plan` |
| 429 | `ai_quota_exhausted` | The request quota is used (retry after `Retry-After`). | `raise_limit_or_plan` |
| 429 | `ai_rate_limited` | Too many requests or tokens for this key in the last minute (`limit`, `used`, `window_seconds`; retry after `Retry-After`, or use another key). | `retry_after_delay` |
| 409 | `idempotency_conflict` | Same key, different body. | `resolve_conflict` |
| 409 | `ai_request_already_processed` | This key was already used for a finished request. | `resolve_conflict` |
| 409 | `ai_request_in_progress` | This key is being processed: wait. | `resolve_conflict` |
| 503 | `model_temporarily_unavailable` | No route for this model right now (retry later). | `retry_later` |
| 503 | `ai_provider_unavailable` | Temporary: retry later. | `retry_later` |
| 502 | `ai_upstream_failed` | The model failed to answer. | `retry_later` |

| next_action | What to do |
|---|---|
| `use_valid_api_key` | Send a valid Galon API key as 'Authorization: Bearer <key>'. If the key was revoked or has expired, create a new one in the console and retry with it. |
| `add_missing_scope` | This key does not have the scope this call needs. Create a key with that scope in the console, then retry the same call with the new key. |
| `fix_request` | The request is invalid. Fix it as 'message' and 'field' say, using the OpenAPI contract, then send it again. Do not retry it unchanged. |
| `check_resource_id` | Nothing with this id is visible to this key. List the resources to get a valid id, and check that the key belongs to the right project and environment (test or live). |
| `top_up_balance` | The project balance does not cover this call. Top up the balance in USD in the console, then retry with the same Idempotency-Key. |
| `raise_limit_or_plan` | A plan quota or a spending limit is reached. Raise the limit or change the plan in the console, or wait for the next period, then retry. |
| `retry_after_delay` | Too many requests. Wait the Retry-After delay (seconds), then retry with exponential backoff and the same Idempotency-Key. |
| `resolve_conflict` | The request conflicts with the resource state or with an earlier request under the same Idempotency-Key. Read the resource first; for a new intent, use a new Idempotency-Key. |
| `retry_later` | Temporary error on Galon's side. Retry with exponential backoff and the same Idempotency-Key; if it lasts, contact support with the X-Request-Id header. |

## Limits, free tier and pricing

Read from the platform code each time this page is served.

| Limit | Value |
|---|---|
| Requests per project and day (default quota) | **10,000** |
| Requests per project and month (default quota) | **100,000** |
| Requests per key and minute (sliding window) | **60** |
| Tokens per key and minute (input bound + max output, sliding window) | **200,000** |
| Default spending cap of a key per month (adjustable in the console) | **$5.00** |
| Input per request (messages, default) | **64 KiB** |
| Output tokens per request (Galon aliases) | **8,192** |
| Messages per request | **256** |
| Tools per request | **128** |
| Images per request | **8** |
| Size of one image | **5 MiB** |
| Request body | **2 MiB** |

Usage prices, in US dollars, read from the price grid served by the platform each time this page is served. Paid from the prepaid balance.

| Item | Price | Unit |
|---|---|---|
| `Meta-Llama-3_3-70B-Instruct` | 1.197625 USD | per million input tokens |
| `Meta-Llama-3_3-70B-Instruct` | 1.197625 USD | per million output tokens |
| `gpt-oss-120b` | 0.1485 USD | per million input tokens |
| `gpt-oss-120b` | 0.7425 USD | per million output tokens |
| `gpt-oss-20b` | 0.07425 USD | per million input tokens |
| `gpt-oss-20b` | 0.278438 USD | per million output tokens |
| `Qwen2.5-VL-72B-Instruct` | 1.626625 USD | per million input tokens |
| `Qwen2.5-VL-72B-Instruct` | 1.626625 USD | per million output tokens |
| `Qwen3.5-397B-A17B` | 1.0725 USD | per million input tokens |
| `Qwen3.5-397B-A17B` | 6.435 USD | per million output tokens |
| `Qwen3.5-9B` | 0.17875 USD | per million input tokens |
| `Qwen3.5-9B` | 0.268125 USD | per million output tokens |
| `Qwen3.6-27B` | 0.715 USD | per million input tokens |
| `Qwen3.6-27B` | 4.82625 USD | per million output tokens |
| `Qwen3.8-27B` | 0.7425 USD | per million input tokens |
| `Qwen3.8-27B` | 4.82625 USD | per million output tokens |
| `bge-m3` | 0.018563 USD | per million input tokens |
| `Qwen3-Embedding-8B` | 0.185625 USD | per million input tokens |

There is no free AI usage. Requests are paid per token from the prepaid balance, in US dollars.

## FAQ

**Can I use an existing chat completions client?**

Yes, any OpenAI-compatible (Chat Completions) client: set its base URL to `https://api.galon.ai/v1/ai` and the key as the API key. Nothing else to change; add your own `Idempotency-Key` header when you want safe retries.

**Do test keys spend money?**

Yes. Test and live keys call the same models and spend the prepaid balance.

**What does a request cost?**

The price per token of each model is in `GET /v1/ai/models` when published; the exact amount charged comes back in the response headers.

**Can I retry a request?**

Use a new `Idempotency-Key` for a new request. Reusing a key never runs the model twice: it answers `409`.

## More

- [Authentication](/cloud/docs/platform/authentication)
- [Projects: live and test](/cloud/docs/platform/environments)
- [Prepaid balance](/cloud/docs/platform/balance)
- [Quotas and rate limits](/cloud/docs/platform/quotas)
- [Terms of Service](/legal/terms-of-service)
- [Acceptable Use Policy](/legal/acceptable-use-policy)
- [Privacy Policy](/legal/privacy-policy)
- [Refunds and prepaid balance](/legal/prepaid-balance-and-refund-policy)
- [Legal Notice](/legal/legal-notice)
- [All legal documents](/legal)
