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.
# 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" }
}