Sign in

Generate text

Send a conversation to a text model and get the answer back in the same call. Messages carry text, images, or both — so the same endpoint writes copy from a brief and describes a picture. Unlike images and video, this endpoint is synchronous: there is nothing to poll and no webhook to register.

POST /v1/chat/completions

Generate text from a conversation. Returns the answer directly.

**Synchronous, and deliberately so.** An image takes a minute, which is why those endpoints answer `202` and deliver later. A text answer arrives in seconds, so the call simply waits. Expect **15-25 seconds for a full-length answer** and allow up to **90 seconds** before timing out on your side.

**Billing is per call, not per token.** One call costs the same whatever its length. Every response carries `cost.xTokens` with the amount actually charged; the rate itself is in your dashboard and deliberately not printed here, because a price in a document goes stale without anyone noticing. A call that fails costs nothing: the charge is reversed automatically, and a request refused for being too long, for an unknown model or for a blocked end-user is never charged in the first place.

**Limits.** Up to **64,000 bytes of UTF-8 of text** across all messages, up to **8 images** per call, and up to **2,000 tokens** of answer (`maxTokens`, default 1,024). All three are checked before you are charged. The input limit counts **bytes, not characters**: plain English is one byte per character, accented and non-Latin text is two to four, and emoji four. Bytes are what the API enforces, because a character count is not a bound on anything — the same 80,000 characters are 80,000 bytes of English and 240,000 of Chinese.

**`messages`** is the conversation in order, each with a `role` of `system`, `user` or `assistant`. This endpoint keeps no state between calls: send the turns you want the model to see, every time.

**Images.** A message's `content` is either a string or an array of parts — `{ "type": "text", "text": "…" }` and `{ "type": "image_url", "image_url": { "url": "…" } }`. Parts keep their order, so an image before the instruction reads differently from one after it.

Images are given as **URLs only**. The URL must be `https` and reachable from the public internet without authentication; inline base64 (a `data:` URI) is refused by name, as is a link behind a login, a private host, and a URL carrying credentials (`https://user:pass@…`). A redirect is followed, so a share link or a bucket that points at its CDN works. We fetch each URL to check it **before you are charged**, so a dead link costs nothing — it comes back as a `validation_error` naming the position (`Image at index 0 …`) rather than repeating your URL. Allow a second or two for that check on top of the answer.

The input ceiling counts **text only**: an image URL's length is free, and the number of images is its own limit above. The price does not change either — it is flat per call whether you send one image or the maximum.

**`endUserEmail`** identifies the person inside YOUR product who triggered the call — the same envelope every other endpoint takes. Calls are grouped under it, and blocking an end-user stops their calls here too.

**Tuning the answer.** `maxTokens` caps its length; `temperature` (0–2) makes it more or less varied; `topP` (0–1) is nucleus sampling; `stop` takes up to 4 strings that end the answer when generated. All four are optional — omit them for the model's own defaults, which are on its reference page. The ceilings are per model and published by `GET /v1/models`.

**`finishReason`** tells you how the answer ended, in a fixed set that does not change when a model does:

- `complete` — the model finished by itself. - `truncated` — it reached `maxTokens`. Raise the ceiling or ask for less. - `filtered` — a content filter stopped it.

**Not supported:** streaming, more than one completion per call, tool calling and structured-output modes. Sending `stream`, `n`, `tools` or `response_format` is an error rather than a silent no-op, so a mistake surfaces on the first call instead of in your output. Field names are camelCase — `maxTokens`, not `max_tokens` — and an unrecognised field is named back to you in the error.

bash
# Request
curl -X POST 'https://api.xmode.ai/v1/chat/completions' \
  -H "Authorization: Bearer xm_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "xTL1.0",
    "endUserEmail": "alice@your-product.com",
    "messages": [
      { "role": "system", "content": "You reply with a single paragraph and no preamble." },
      { "role": "user", "content": "Describe a neon-lit alley after rain." }
    ],
    "maxTokens": 400
  }'

# 200 OK
{
  "requestId": "V1StGXR8_Z5jdHi6",
  "model": "xTL1.0",
  "text": "Rain has just stopped and the alley still holds it...",
  "finishReason": "complete",
  "cost": { "xTokens": 1 },
  "createdAt": "2026-09-30T12:04:04.123Z"
}

# Request - an image in, a description out
curl -X POST 'https://api.xmode.ai/v1/chat/completions'   -H "Authorization: Bearer xm_live_<your-key>"   -H "Content-Type: application/json"   -d '{
    "model": "xTL1.0",
    "endUserEmail": "alice@your-product.com",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "image_url", "image_url": { "url": "https://cdn.your-product.com/frames/a1b2c3.jpg" } },
          { "type": "text", "text": "Describe this image in detail." }
        ]
      }
    ],
    "maxTokens": 600
  }'

# 400 Bad Request - an image we could not fetch. Nothing was charged.
{
  "error": {
    "code": "validation_error",
    "message": "Image at index 0 could not be fetched: the host answered HTTP 403. It must be reachable without authentication."
  }
}

# 400 Bad Request - a field we do not accept
{
  "error": {
    "code": "validation_error",
    "message": "Unrecognized keys: \"max_tokens\""
  }
}

# 502 Bad Gateway - generation failed, and the charge was reversed
{
  "error": { "code": "provider_error", "message": "Text generation failed" }
}