Welcome to the xMode API

Authentication

Every request must include an API key in the `Authorization` header. Keys look like `xm_live_…` and are issued in your dashboard.

1. 1
   Sign in to your dashboardOpen the dashboard and log in with your account email.
2. 2
   Create an API keyGo to **Settings → API Keys → Create new**. Give it a memorable name (e.g. "production-server"). Copy the key once — we never show it again.
3. 3
   Send it as a Bearer tokenAdd the header `Authorization: Bearer xm_live_<your-key>` to every request.

Example request (async — returns 202 + requestId)

# 1. Submit — returns immediately with a requestId
curl https://api.xmode.ai/v1/generations \
  -H "Authorization: Bearer xm_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"endUserEmail":"alice@your-product.com","prompt":"hello world"}'

# → 202 Accepted
# {
#   "requestId": "req_3xN7kQ1aJpL9wDvE",
#   "status": "queued",
#   "pollUrl": "https://api.xmode.ai/v1/generations/req_3xN7kQ1aJpL9wDvE",
#   ...
# }

# 2. Poll until status="succeeded" (typically 10–60 s)
curl https://api.xmode.ai/v1/generations/req_3xN7kQ1aJpL9wDvE \
  -H "Authorization: Bearer xm_live_<your-key>"

Security tips

• Treat keys like passwords. Keep them on your server. Never embed them in client code, mobile apps, or browser bundles.
• Rotate keys regularly. Compromised keys can be revoked from the dashboard.
• One key per environment is best practice — separate production from staging from CI.

Async lifecycle

Every generation moves through a small state machine. The same shape is returned by GET /v1/generations/:requestId and inside a webhook delivery — only the `status` field changes.

• queuedWe accepted the request, debited xTokens, and pushed it to the worker queue. The worker has not started yet.
• processingA worker has picked up the request and is calling the model. Typical duration: 10–60 seconds.
• succeededGeneration finished. The response now includes `images[]` with signed URLs (valid 23 hours) and `cost.xTokens`.
• failedGeneration failed terminally. The response includes `error.code` and `error.message`. xTokens are refunded automatically.
• expiredMore than 23 hours have passed since success — the signed URLs are no longer fetchable. The metadata record is kept for 90 days for your audit trail.

Poll once every 5 seconds. Most generations finish within 10–60 seconds. Stop polling once `status` is one of `succeeded`, `failed`, or `expired`.

Webhook delivery (optional)

Pass `webhookUrl` in the create request and we will POST the final record to it once the generation reaches a terminal status. The body is identical to what GET /v1/generations/:requestId would return at that moment. Each delivery is HMAC-signed so you can verify it came from us — and replay-protected via a timestamp.

Headers we send

• X-XMode-Signaturev1=<hex>

  Hex-encoded HMAC-SHA256 of `"<timestamp>.<rawBody>"` using your account webhook secret. Use a timing-safe equality check.

• X-XMode-Timestamp<unixSeconds>

  Unix seconds when we built the payload. Reject deliveries older than 5 minutes — that is the replay window.

• X-XMode-Request-Id<requestId>

  Mirror of the requestId in the body. Use it for your own dedup key — we may redeliver on retry.

We retry on network errors and 5xx responses with exponential backoff (up to 5 attempts via our durable queue). 4xx responses are treated as terminal — fix the endpoint and we will stop trying. We never follow redirects (3xx is treated as terminal too).

Your `webhookUrl` MUST be public HTTPS on port 443. We resolve the hostname before connecting and refuse private/loopback/link-local IPs to prevent SSRF — internal hostnames will fail with a terminal `delivery_failed`.

Verify in Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyXModeSignature(req, secret) {
  const ts = req.headers['x-xmode-timestamp'];
  const sig = req.headers['x-xmode-signature']; // "v1=<hex>"
  if (!ts || !sig?.startsWith('v1=')) return false;

  // Replay protection — reject anything older than 5 minutes.
  const ageSec = Math.floor(Date.now() / 1000) - Number(ts);
  if (Number.isNaN(ageSec) || ageSec < 0 || ageSec > 5 * 60) return false;

  const expected = createHmac('sha256', secret)
    .update(`${ts}.${req.rawBody}`)
    .digest('hex');
  const received = sig.slice('v1='.length);

  if (expected.length !== received.length) return false;
  return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(received, 'hex'));
}

Storage & expiry

Every successful generation is uploaded to our CDN and you receive a signed URL in the response. Images are kept for 24 hours by default. After that the URL returns 404 and the bytes are deleted.

If you only need an image short-term (preview, single-use generation), the free 24-hour window is enough. If you ship persistent UX (a user gallery, a brand asset library, etc.) you should either save the bytes yourself the moment you receive them, or wait for the Storage plan.