Galon Cloud
Galon Cloud

Galon AI

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

Markdown · API reference · OpenAPI

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.

MethodPathSummary
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.

StatusCodeWhennext_action
401api_key_missingNo Authorization: Bearer header.use_valid_api_key
403scope_missingThe key lacks ai:inference.add_missing_scope
400idempotency_key_invalidAn Idempotency-Key header that is not 8 to 200 printable characters.fix_request
400ai_field_not_supportedA field the API does not accept (field names it).fix_request
400ai_parameter_invalidA value out of range (field names it).fix_request
404ai_model_not_foundmodel is not a served id: list /v1/ai/models.check_resource_id
413ai_input_too_largeThe messages are over the input limit.fix_request
402ai_wallet_insufficient_fundsThe balance does not cover the reservation.top_up_balance
402ai_budget_exhaustedThe daily or monthly spending cap is reached.raise_limit_or_plan
402ai_key_limit_reachedThis key's own spending cap is reached.raise_limit_or_plan
429ai_quota_exhaustedThe request quota is used (retry after Retry-After).raise_limit_or_plan
429ai_rate_limitedToo 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
409idempotency_conflictSame key, different body.resolve_conflict
409ai_request_already_processedThis key was already used for a finished request.resolve_conflict
409ai_request_in_progressThis key is being processed: wait.resolve_conflict
503model_temporarily_unavailableNo route for this model right now (retry later).retry_later
503ai_provider_unavailableTemporary: retry later.retry_later
502ai_upstream_failedThe model failed to answer.retry_later
next_actionWhat to do
use_valid_api_keySend 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_scopeThis 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_requestThe 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_idNothing 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_balanceThe 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_planA 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_delayToo many requests. Wait the Retry-After delay (seconds), then retry with exponential backoff and the same Idempotency-Key.
resolve_conflictThe 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_laterTemporary 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.

LimitValue
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 request256
Tools per request128
Images per request8
Size of one image5 MiB
Request body2 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.

ItemPriceUnit
Meta-Llama-3_3-70B-Instruct1.197625 USDper million input tokens
Meta-Llama-3_3-70B-Instruct1.197625 USDper million output tokens
gpt-oss-120b0.1485 USDper million input tokens
gpt-oss-120b0.7425 USDper million output tokens
gpt-oss-20b0.07425 USDper million input tokens
gpt-oss-20b0.278438 USDper million output tokens
Qwen2.5-VL-72B-Instruct1.626625 USDper million input tokens
Qwen2.5-VL-72B-Instruct1.626625 USDper million output tokens
Qwen3.5-397B-A17B1.0725 USDper million input tokens
Qwen3.5-397B-A17B6.435 USDper million output tokens
Qwen3.5-9B0.17875 USDper million input tokens
Qwen3.5-9B0.268125 USDper million output tokens
Qwen3.6-27B0.715 USDper million input tokens
Qwen3.6-27B4.82625 USDper million output tokens
Qwen3.8-27B0.7425 USDper million input tokens
Qwen3.8-27B4.82625 USDper million output tokens
bge-m30.018563 USDper million input tokens
Qwen3-Embedding-8B0.185625 USDper 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