GME AI API

Overview

There are two APIs, for two audiences:

Concepts & hierarchy

• Merchant — a reseller tenant with a pooled balance funded by the platform.
• Customer — an end user created by the merchant, with a balance drawn from the pool, and one or more keys.
• Balance — every inference call bills the customer's balance and hard-stops at zero (a 402, never an overage).

Authentication

All requests use a bearer token in the Authorization header:

Authorization: Bearer gme-xxxxxxxxxxxxxxxxxxxxxxxx    # inference
Authorization: Bearer gmadm-xxxxxxxxxxxxxxxxxxxxxx    # merchant management

Keys are shown once at creation and cannot be retrieved again — save them securely. Treat a key like a password; anyone holding it can spend the balance it draws on.

Playground

Try a live request against the gateway. Your key is used only in this browser and sent directly to the API — nothing is stored.

Quickstart

The Inference API is a drop-in OpenAI replacement — change the base URL and key:

Python (openai SDK)

from openai import OpenAI
client = OpenAI(base_url="https://gme-ai.com/v1", api_key="gme-YOUR_KEY")

resp = client.chat.completions.create(
    model="atg-gpt-5.4",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

Node (openai SDK)

import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://gme-ai.com/v1", apiKey: "gme-YOUR_KEY" });

const r = await client.chat.completions.create({
  model: "atg-gpt-5.4",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(r.choices[0].message.content);

curl

curl https://gme-ai.com/v1/chat/completions \
  -H "Authorization: Bearer gme-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"atg-gpt-5.4","messages":[{"role":"user","content":"Hello!"}]}'

Chat completions

OpenAI-compatible. Returns a chat.completion object (or an SSE stream when stream: true).

Request body

Response

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "atg-gpt-5.4",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "…" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 }
}

Streaming

Set "stream": true to receive Server-Sent Events. The first event carries delta.role, each following event a partial delta.content, and the stream ends with a finish_reason chunk then data: [DONE]. This is fully compatible with the OpenAI SDK's streaming helpers.

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"}}]}
data: {"…","choices":[{"index":0,"delta":{"content":"Hel"}}]}
data: {"…","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]

List models

Returns the models available to your key, in OpenAI list format:

{ "object": "list", "data": [{ "id": "atg-gpt-5.4", "object": "model", "owned_by": "atg" }, … ] }

If your key has a model allowlist, requests for models outside it return 403 model_not_allowed (even via an alias).

Available models

Merchant API

Base URL https://gme-ai.com/api/gme-ai/merchant. Authenticate every request with your management key:

Authorization: Bearer gmadm-YOUR_MANAGEMENT_KEY

All responses are JSON of the form { "ok": true, … } or { "ok": false, "error": "code", "detail": "…" }. Everything is scoped to your merchant — you can only read and manage your own customers and keys.

Merchant info

{ "ok": true,
  "merchant": { "id": 7, "name": "Acme AI", "pool_balance_usd": 420.50, "customer_count": 12 },
  "limits": { "maxStartBalance": 5000, "maxRatePerMin": 120, "maxCustomers": 2000 } }

Create customer

Creates (or attaches) a customer, transfers a starting balance from your pool, and mints their first inference key. The raw key is returned once.

curl https://gme-ai.com/api/gme-ai/merchant/customers \
  -H "Authorization: Bearer gmadm-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-8842" \
  -d '{"email":"[email protected]","starting_balance_usd":10,"daily_cap_usd":5}'

{ "ok": true, "customer_id": 341, "funded_usd": 10,
  "api_key": { "id": 88, "token_prefix": "gme-Abc123…", "raw_token_shown_once": "gme-…" },
  "base_url": "https://gme-ai.com/v1" }

List customers

{ "ok": true, "customers": [
  { "id": 341, "email": "[email protected]", "display_name": "Dev", "active_keys": 1, "created_at": "…" } ] }

List keys

Returns every inference key under your merchant, with caps, allowlist, last-used and revoked/expiry status. Raw key values are never returned — only the token_prefix hint.

Mint another key

Issues an additional inference key for an existing customer. Body: customer_id or email, plus optional name, daily_cap_usd, monthly_cap_usd, rate_per_min, model_allowlist, expires_days. Returns the raw key once.

Update a key

Change any of daily_cap_usd, monthly_cap_usd, rate_per_min, model_allowlist, expires_days. Pass null to clear a cap. Only fields present in the body are changed.

Revoke & rotate

Revokes a key immediately.

Mints a replacement key (same caps, allowlist and expiry) and sets the old key to expire after a grace window so you can cut over without downtime. Body: grace_hours (default 24, max 168). Returns the new raw key once.

{ "ok": true, "new_key": { "raw_token_shown_once": "gme-…" }, "old_key_expires_in_hours": 24 }

Top-up a customer

Moves amount_usd from your pool to the customer's balance. Send an Idempotency-Key.

{ "ok": true, "customer_id": 341, "amount_usd": 25, "pool_balance": 395.50, "customer_balance": 35 }

Claw back

Moves balance back from the customer to your pool. Body: amount_usd, or { "all": true } to sweep the whole balance. Send an Idempotency-Key.

Usage report

Aggregated spend for your merchant. days = 7, 28, 90 or 365 (default 28). Add &format=csv for a per-customer CSV download.

{ "ok": true, "days": 28,
  "totals":      { "calls": 1820, "tokens_in": …, "tokens_out": …, "cost_usd": 42.18 },
  "by_customer": [{ "member_id": 341, "email": "…", "calls": …, "cost_usd": … }],
  "by_model":    [{ "model_id": "gpt-5.4", "calls": …, "cost_usd": … }],
  "by_day":      [{ "d": "2026-07-17", "calls": …, "cost_usd": … }] }

MCP (Model Context Protocol)

Expose the GME AI platform to Claude Desktop, Claude Code, Cursor, Cline, and any MCP-compatible client. Same API key as the OpenAI-compatible gateway above; separate transport (JSON-RPC 2.0).

MCP is Anthropic's open protocol for connecting AI models to external tools and data. Instead of your assistant calling POST /v1/chat/completions once to get text back, an MCP client can ask the GME server what tools are available, then call any of them (chat, knowledge search, workflow trigger, document create, calendar, meetings…) as a first-class action. The assistant decides when to use them; you pay per call from your ATG balance.

Endpoint

Canonical MCP endpoint for all applications and all tenant hosts. Aliases:

• POST /api/gme-ai/mcp — same server, gme-ai.com-branded path
• POST /api/mcp/japan, POST /api/gme-ai/mcp/japan — back-compat aliases (Japan market handler, same tool surface)

Auth: Authorization: Bearer <your-mcp-token>. Note: MCP tokens are currently a separate credential from the gateway API keys — they're stored in gmeai_mcp_tokens with a per-token country + tool scope, and are minted by a platform admin. To get one, message support from the Developer page or open a ticket. A unified-key flow (one key spends ATG on both /v1/chat/completions and /api/mcp) is on the roadmap.

Client setup

Claude Desktop / Claude Code

Edit ~/.config/claude/mcp_servers.json (macOS/Linux) or %APPDATA%\Claude\mcp_servers.json (Windows) and add:

{
  "mcpServers": {
    "gme-ai": {
      "url": "https://gme-ai.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Cursor

Settings → MCP Servers → Add new MCP server → HTTP transport, URL https://gme-ai.com/api/mcp, header Authorization: Bearer YOUR_API_KEY.

Cline (VS Code extension)

MCP Servers panel → Configure MCP Servers — paste the same JSON block above.

Any MCP-compatible client

Point it at the URL above with a bearer token. The server implements initialize, tools/list, tools/call, and resources/list per the MCP specification (2024-11-05 protocol version).

tools/list & tools/call

Standard JSON-RPC 2.0. List everything the key can call:

curl https://gme-ai.com/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Response shape:

{ "jsonrpc": "2.0", "id": 1,
  "result": {
    "tools": [
      { "name": "chat",           "description": "Ask any GME AI model",            "inputSchema": { "type": "object", "properties": { "prompt": { "type": "string" }, "model": { "type": "string" } } } },
      { "name": "kb_search",       "description": "Full-text search across your knowledge base", "inputSchema": { "type": "object", "properties": { "q": { "type": "string" } } } },
      { "name": "workflow_run",    "description": "Trigger any of your saved workflows by slug" },
      { "name": "doc_create",      "description": "Create a document in your suite" },
      { "name": "calendar_event", "description": "Schedule an event on your GME Calendar" },
      // … depends on which tools your key has access to
    ]
  }
}

Invoke one:

curl https://gme-ai.com/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"kb_search","arguments":{"q":"MOQ negotiation"}}}'

Billing & per-tool cost

Every successful tools/call debits your ATG balance the same way a /v1/chat/completions call does. Tools that wrap a model (e.g. chat, kb_ask) charge model tokens; tools that trigger a workflow charge the workflow's ATG cost; utility tools (kb_search, doc_create) are flat-fee. The response includes an _gme block with the actual debit:

{ "jsonrpc": "2.0", "id": 2,
  "result": { "content": [ { "type": "text", "text": "…" } ],
              "_gme": { "debit_atg": 0.42, "balance_atg": 124.31 } } }

Insufficient balance returns JSON-RPC error -32001 with a message asking the user to top up. Rate limits and idempotency rules match the OpenAI-compatible endpoint (see below).

Idempotency

Money-moving Merchant endpoints — create customer, top-up and claw back — accept an Idempotency-Key header. A retry with the same key returns the original response instead of moving funds again, so a network timeout or a client retry can never double-charge.

Idempotency-Key: any-unique-string-per-operation

• A retry after a successful call replays the stored result (funds moved once).
• A retry after a clean failure where no funds moved (e.g. bad_amount, insufficient_source_balance) is allowed to try again.
• A retry after a money-uncertain failure (a 502 such as transfer_state_unknown) replays the stored error and is not re-attempted — reconcile the balances before acting.
• While the first request is still in flight, a duplicate returns 409 request_in_progress.
• A show-once key is never re-exposed on a replay.

Note: Idempotency-Key applies only to the fund-moving endpoints above (create customer, top-up, claw back). Key mint / update / revoke / rotate are naturally safe to repeat and do not use it.

Errors

Inference API (OpenAI error shape)

{ "error": { "message": "…", "type": "insufficient_quota", "code": "insufficient_quota" } }

Merchant API

Rate limits & caps

• Rate limit — each inference key has a requests-per-minute limit (default 60). Exceeding it returns 429.
• Spend caps — optional per-key daily and monthly USD caps. They are best-effort budgets checked before each call; the hard ceiling is the customer's balance, which stops at zero.
• Balance — the true limit. When it reaches zero, inference returns 402 with no overage and no fallback.

GME AI API · OpenAI-compatible gateway · base https://gme-ai.com/v1