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
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
curl -sS -X GET "$GALON_API_BASE/ai/models" \
-H "Authorization: Bearer $GALON_API_KEY" \
-w '\n%{http_code}\n'Python 3 (standard library)
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)
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)
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
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)
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)
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)
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.