Your Agents, Plugged In. Every Major Model, One Bill.

Quickstart — first call in two minutes

1. Sign in and mint a key on /xdev — new accounts start with $10 free credit, no card.
2. Set a spend cap on the key (you can raise it later).
3. Make the call:

curl -s https://www.modelxd.com/api/v1/chat/completions \
  -H "Authorization: Bearer xd_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "xd/auto",
    "messages": [{"role": "user", "content": "One sentence: why blind votes?"}]
  }'

That's the whole integration: any OpenAI SDK, one base URL. There is no ModelXD SDK, deliberately — needing one would mean the compatibility failed.

Authentication

Authorization: Bearer xd_...

Keys are minted on /xdev, shown once, stored hashed. Each key can carry a lifetime spend cap, enforced atomically before a call spends — ten concurrent requests cannot slip past it together.

Server-side only. The API sends no CORS headers, so a browser cannot call it — a key shipped in a client cannot be stolen from one. Keep the key on your server: game engine → your server → ModelXD.

Chat completions

Synchronous text inference, OpenAI-shaped in and out. Streaming via standard SSE.

Not supported, loudly: tools / functions / tool_choice return an explicit 400 rather than prose that ignores your functions. For agent decisions use response_format — a filled-in form beats a function call.

Models & routing

The resolved model always comes back in response.model — you are never routed blind. An unknown, disabled, or API-blocked model is a 404 naming the model, never a silent substitution.

Agents with memory: resolve once, pin after. Call xd/auto when a character is created, read response.model, pin that slug for the session — switching models mid-conversation throws away the prompt cache on a history that only grows.

Structured output

Ask for a JSON schema and the reply either validates against it or the call fails with 422 — never malformed text arriving at your validator as a surprise. One silent re-ask happens server-side first. The response's xd.structured_mode reports the enforcement tier: native_schema (constrained decoding), native_json (JSON guaranteed, schema checked by us), or coaxed (schema in the prompt, validated by us).

{
  "model": "xd/budget",
  "messages": [
    {"role": "system", "content": "You are Rosa, a cautious farmer agent."},
    {"role": "user", "content": "<world snapshot JSON>"}
  ],
  "response_format": {"type": "json_schema", "json_schema": {
    "name": "decision",
    "schema": {
      "type": "object",
      "properties": {
        "action": {"enum": ["plant","water","harvest","store","move_to",
                            "steal","guard","chase","flee","idle"]},
        "target": {"type": "string"},
        "amount": {"type": "integer", "maximum": 10},
        "reason": {"type": "string"}
      },
      "required": ["action", "reason"],
      "additionalProperties": false
    }
  }},
  "xd": {"effort": "low"}
}

Provider schema dialects differ (one rejects maximum, another requires every property in required) — ModelXD adapts the schema per provider and validates your original on the way back, so one schema means one thing even across a fallback chain. The decision arrives as a JSON string in choices[0].message.content: parse it, don't regex it.

Images

OpenAI-named so client.images.generate() finds it — but async: the answer is a 202 with a job id, not a finished file. Everything you can act on fails on this call — unknown model, empty prompt, exhausted balance, capped key — never as a job that dies later.

POST https://www.modelxd.com/api/v1/images/generations
{ "model": "openai/gpt-image-2", "prompt": "a cheerful farm girl, low-poly",
  "aspect_ratio": "16:9", "quality": "high" }

→ 202 { "id": "3f2b…", "object": "image.generation.job",
        "status": "running", "poll": "/api/v1/jobs/3f2b…" }

Videos

Same shape as images; video runs take minutes, so poll every ~15s.

Jobs

→ { "id": "3f2b…", "object": "image.generation.job",
    "status": "succeeded",            // running | succeeded | failed
    "model": "openai/gpt-image-2",
    "data": [ { "url": "https://…signed…" } ],
    "usage": { "cost_usd": 0.067 } }

Fetch url promptly — generated files sit behind signed URLs that expire in ~24 hours. Everything also lands in your XCreate gallery, which never expires. On failed, the job carries an error message and costs nothing beyond what the provider actually burned.

Your recent generation jobs, newest first (limit ≤ 100). This is the recovery path: lose an id between the create and the first poll, and the job is still here — nothing has to be paid for twice. Files are not inlined; poll the one you want for a URL signed on the spot. Text runs are not listed — chat is synchronous and has no job.

List models

OpenAI-shaped (client.models.list() works unchanged), and the only place a developer can discover ids like openai/gpt-image-2. Every callable model is listed — text, image and video — each row carrying modalities, an endpoint naming where to send it, ModelXD's display_name, pricing_usd_per_1m (null for per-output-priced image/video models — honest, not missing), and capabilities. The routers (xd/auto, xd/budget) appear under text.

{ "object": "list", "data": [
  { "id": "openai/gpt-5.6-sol", "object": "model", "owned_by": "openai",
    "display_name": "GPT-5.6 Sol",
    "pricing_usd_per_1m": { "input": 5, "output": 30 },
    "capabilities": { "web_search": true, "structured_output": true, "vision": true } },
  { "id": "xd/auto", "object": "model", "owned_by": "modelxd", "tags": ["router"] }
] }

Errors

OpenAI's envelope — {"error": {"message", "type", "code"}} — so SDK error handling works unmodified. Retry 429 / 5xx (429 carries Retry-After); never retry other 4xx unchanged.

Billing & limits

Calls debit your ModelXD wallet at the model's listed price — the same number XBoard shows, no API markup, ever. Every response reports its real cost in usage.cost_usd, streams included. Prompt caching on Anthropic-family models is applied automatically — keep your system message byte-stable and the saving shows up in the price, not in extra fields.

Ten agents thinking concurrently on one key is the designed load — nothing serializes, and the spend cap stays exact under parallel calls. There is no per-request rate limit today; the cap and your balance are the wall. New accounts start with $10 free credit; top-ups are 1:1 on Profile. Spend by day, model and key is on this page and at GET /api/v1/usage.

Usage — what your keys spent

Every call made with a key is recorded: endpoint, model, tokens, list-price cost and whether it failed (failures cost $0). Read it from code with the same key:

curl -s "https://www.modelxd.com/api/v1/usage?group_by=model&from=2026-09-01" \
  -H "Authorization: Bearer $MODELXD_KEY"

The response carries totals for the whole window (requests, failed, input and output tokens, cost_usd) plus the grouped rows in data. Prices before you call are in GET /api/v1/models: per 1M tokens for text, pricing_usd_per_output per image or per video second.

MCP — the same operations, for agent clients

Writing a program? Use the REST endpoints above. Connecting an agent that picks its own tools — Claude Code, Cursor, n8n? That's MCP. Same key, same billing:

claude mcp add --transport http modelxd https://www.modelxd.com/api/mcp \
  --header "Authorization: Bearer xd_..."

All outputs are AI-generated content — label them as such wherever they get published.