Quickstart#

Get a key from the owner, submit a generation job, poll for the answer. Then try the OpenAI-compatible chat call.

1. Get a key#

The owner issues API keys from the MaxiMind admin area (API keys). Store it in your app's environment as MAXIMIND_API_KEY. New keys start with no abilities; ask the owner to enable generate and at least one engine (claude, codex, agy) for text work, and media for transcription and the media APIs.

Every request carries the key in one of two headers:

x-api-key: $MAXIMIND_API_KEY
Authorization: Bearer $MAXIMIND_API_KEY

Check that the key is accepted:

GET /auth-check

curl -s https://maximind.dev/auth-check -H "x-api-key: $MAXIMIND_API_KEY"

{"ok": true}

A bad key returns 401 {"detail":"Invalid or missing API key"}.

2. First generation in three steps#

Always use job mode ("async": true). The public edge cuts single requests at about 100 seconds, and Pro-class models can take 40 to 95 seconds.

Step 1: submit#

POST /api/ai/generate

curl -s https://maximind.dev/api/ai/generate \
  -H "x-api-key: $MAXIMIND_API_KEY" -H "content-type: application/json" \
  -d '{"prompt":"Explain the past perfect in one sentence.",
       "system":"You are a concise tutor.",
       "json":false,
       "engines":["agy","codex","claude"],
       "models":{"agy":"gemini-4-argon-high","codex":"gpt-5.6-sol","claude":"opus"},
       "subscription_only":true,"async":true,"attachments":[]}'

{"ok": true, "job_id": "…"}

Step 2: poll every 1 to 3 seconds#

GET /api/ai/generate/jobs/{job_id}

curl -s https://maximind.dev/api/ai/generate/jobs/<job_id> -H "x-api-key: $MAXIMIND_API_KEY"

{"status": "queued|running|done|failed", "text": "…", "engine": "agy", "account": "agy-primary", "model": "gemini-4-argon-high", "error": null}

Step 3: read the result#

When status is done, text holds the answer and engine, account and model say what actually served it. When status is failed with subscription_only: true, no engine could answer and your app decides what to do (usually its own paid key, logged). Job IDs are private to the key that created them and expire one hour after completion.

The same flow in Python (standard library only):

import json, os, time, urllib.request

BASE = "https://maximind.dev"
KEY = os.environ["MAXIMIND_API_KEY"]
HEADERS = {"x-api-key": KEY, "content-type": "application/json"}

def call(method, path, body=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(BASE + path, data=data, headers=HEADERS, method=method)
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)

job = call("POST", "/api/ai/generate", {
    "prompt": "Explain the past perfect in one sentence.",
    "system": "You are a concise tutor.",
    "json": False,
    "engines": ["agy", "codex", "claude"],
    "models": {"agy": "gemini-4-argon-high", "codex": "gpt-5.6-sol", "claude": "opus"},
    "subscription_only": True, "async": True, "attachments": [],
})

while True:
    status = call("GET", f"/api/ai/generate/jobs/{job['job_id']}")
    if status["status"] in ("done", "failed"):
        break
    time.sleep(2)

print(status["engine"], status["model"], status["text"] or status["error"])

3. OpenAI-compatible chat#

Point any OpenAI client at base URL https://maximind.dev/v1 with your MaxiMind key. Model IDs are engine/model, for example claude/opus, codex/gpt-5.6-sol, agy/gemini-3.8-flash-high, or auto, auto/pro, auto/fast.

POST /v1/chat/completions

curl -sN https://maximind.dev/v1/chat/completions \
  -H "Authorization: Bearer $MAXIMIND_API_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"claude/opus","stream":true,"messages":[{"role":"user","content":"Hello"}]}'

Use stream: true for Pro or long answers: the server sends SSE keepalive comments while the model works, then the completed answer in short chunks, a stop chunk and [DONE]. This endpoint never falls back to a pay-per-use API.

The same call with the OpenAI Python SDK, using only the base URL and key:

from openai import OpenAI

client = OpenAI(base_url="https://maximind.dev/v1", api_key=os.environ["MAXIMIND_API_KEY"])
stream = client.chat.completions.create(
    model="claude/opus",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

usage token counts come back as zero and temperature / max_tokens are accepted but not applied. See Chat completions.

4. Discover what you may use#

GET /api/ai/catalog

curl -s https://maximind.dev/api/ai/catalog -H "x-api-key: $MAXIMIND_API_KEY"

Returns engines, models (allowed and denied), defaults, tier recipes and endpoints. The catalogue is always current; the docs can lag. See Models.

Next steps#

• Authentication for what a key can and cannot do.
• Text generation for JSON mode and attachments.
• Limits for admission limits (12 active requests per key owner, 24 globally) and body sizes.
• Errors for status codes.