Repository Public
1<!-- source: https://docs.x.ai/developers/model-capabilities/legacy/chat-completions (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Model Capabilities34# Chat Completions56> [!WARNING]7>8> Chat Completions is offered as a legacy endpoint. New features will come to the first. To migrate, check out the [Migrating to Responses API](/developers/model-capabilities/text/comparison) guide.910Text in, text out. Chat is the most popular feature on the xAI API, and can be used for anything from summarizing articles, generating creative writing, answering questions, providing customer support, to assisting with coding tasks.1112## Prerequisites1314Create an API key on the [xAI Console API Keys Page](https://console.x.ai/team/default/api-keys?utm_source=docs\&utm_medium=referral\&utm_campaign=developers-model-capabilities-legacy-chat-completions\&utm_content=api-keys). Set your API key in your environment:1516```bash17export XAI_API_KEY="your_api_key"18```1920## A basic chat completions example2122You can also stream the response, which is covered in [Streaming Response](/developers/model-capabilities/text/streaming).2324The user sends a request to the xAI API endpoint. The API processes this and returns a complete response.2526```python customLanguage="pythonXAI"27import os2829from xai_sdk import Client30from xai_sdk.chat import user, system3132client = Client(33 api_key=os.getenv("XAI_API_KEY"),34 timeout=3600, # Override default timeout with longer timeout for reasoning models35)3637chat = client.chat.create(model="grok-4.6")38chat.append(system("You are a PhD-level mathematician."))39chat.append(user("What is 2 + 2?"))4041response = chat.sample()42print(response.content)43```4445```python customLanguage="pythonOpenAISDK"46import os47import httpx48from openai import OpenAI4950client = OpenAI(51 api_key="<YOUR_XAI_API_KEY_HERE>",52 base_url="https://api.x.ai/v1",53 timeout=httpx.Timeout(3600.0), # Override default timeout with longer timeout for reasoning models54)5556completion = client.chat.completions.create(57 model="grok-4.6",58 messages=[59 {"role": "system", "content": "You are a PhD-level mathematician."},60 {"role": "user", "content": "What is 2 + 2?"},61 ],62)6364print(completion.choices[0].message)65```6667```javascript customLanguage="javascriptOpenAISDK"68import OpenAI from "openai";6970const client = new OpenAI({71 apiKey: "<api key>",72 baseURL: "https://api.x.ai/v1",73 timeout: 360000, // Override default timeout with longer timeout for reasoning models74});7576const completion = await client.chat.completions.create({77 model: "grok-4.6",78 messages: [79 {80 role: "system",81 content: "You are Grok, a helpful and useful AI built by xAI."82 },83 {84 role: "user",85 content: "Explain how neural networks learn in two sentences."86 },87 ],88});8990console.log(completion.choices[0].message);91```9293```javascript customLanguage="javascriptAISDK"94import { xai } from '@ai-sdk/xai';95import { generateText } from 'ai';9697const result = await generateText({98 model: xai('grok-4.6'),99 system:100 "You are Grok, a helpful and useful AI built by xAI.",101 prompt: 'Explain how neural networks learn in two sentences.',102});103104console.log(result.text);105```106107```bash108curl https://api.x.ai/v1/chat/completions \109-H "Content-Type: application/json" \110-H "Authorization: Bearer $XAI_API_KEY" \111-m 3600 \112-d '{113 "messages": [114 {115 "role": "system",116 "content": "You are Grok, a helpful and useful AI built by xAI."117 },118 {119 "role": "user",120 "content": "Explain how neural networks learn in two sentences."121 }122 ],123 "model": "grok-4.6",124 "stream": false125}'126```127128Response:129130```python customLanguage="pythonXAI"131'2 + 2 equals 4.'132```133134```python customLanguage="pythonOpenAISDK"135ChatCompletionMessage(136 content='2 + 2 equals 4.',137 refusal=None,138 role='assistant',139 audio=None,140 function_call=None,141 tool_calls=None142)143```144145```javascript customLanguage="javascriptOpenAISDK"146{147 role: 'assistant',148 content: `Neural networks learn by adjusting connection weights to minimize prediction error. Through backpropagation, they propagate gradients backward through layers so each weight updates in the direction that improves accuracy on training data.`149 refusal: null150}151```152153```javascript customLanguage="javascriptAISDK"154// result object structure155{156 text: "Neural networks learn by adjusting connection weights...",157 finishReason: "stop",158 usage: {159 inputTokens: 716,160 outputTokens: 126,161 totalTokens: 1009,162 reasoningTokens: 167163 },164 totalUsage: { /* same as usage */ }165}166```167168```bash169{170 "id": "0daf962f-a275-4a3c-839a-047854645532",171 "object": "chat.completion",172 "created": 1739301120,173 "model": "grok-4.6",174 "choices": [175 {176 "index": 0,177 "message": {178 "role": "assistant",179 "content": "Neural networks learn by adjusting connection weights to minimize prediction error. Through backpropagation, they propagate gradients backward through layers so each weight updates in the direction that improves accuracy on training data.",180 "refusal": null181 },182 "finish_reason": "stop"183 }184 ],185 "usage": {186 "prompt_tokens": 41,187 "completion_tokens": 104,188 "total_tokens": 145,189 "prompt_tokens_details": {190 "text_tokens": 41,191 "audio_tokens": 0,192 "image_tokens": 0,193 "cached_tokens": 0194 }195 },196 "system_fingerprint": "fp_84ff176447"197}198```199200## Conversations201202The xAI API is stateless and does not process a new request with the context of your previous request history.203204However, you can provide previous chat generation prompts and results to a new chat generation request to let the model process your new request with the context in mind.205206An example message:207208```json209{210 "role": "system",211 "content": [{ "type": "text", "text": "You are a helpful and funny assistant."}]212}213{214 "role": "user",215 "content": [{ "type": "text", "text": "Why don't eggs tell jokes?" }]216},217{218 "role": "assistant",219 "content": [{ "type": "text", "text": "They'd crack up!" }]220},221{222 "role": "user",223 "content": [{"type": "text", "text": "Can you explain the joke?"}],224}225```226227By specifying roles, you can change how the model ingests the content.228The `system` role content should define, in an instructive tone, the way the model should respond to user request.229The `user` role content is usually used for user requests or data sent to the model.230The `assistant` role content is usually either in the model's response, or when sent within the prompt, indicates the model's response as part of conversation history.231232## Image understanding233234Some models allow images in the input. The model will consider the image context when generating the response.235236### Constructing the message body - difference from text-only prompt237238The request message to image understanding is similar to a text-only prompt. The main difference is that instead of text input:239240```json241[242{243 "role": "user",244 "content": "What is in this image?"245}246]247```248249We send in `content` as a list of objects:250251```json252[253{254 "role": "user",255 "content": [256{257 "type": "image_url",258 "image_url": {259 "url": "data:image/jpeg;base64,<base64_image_string>",260 "detail": "high"261}262},263{264 "type": "text",265 "text": "What is in this image?"266}267 ]268}269]270```271272The `image_url.url` can also be the image's url on the Internet.273274### Image understanding example275276```pythonXAI277import os278279from xai_sdk import Client280from xai_sdk.chat import user, image281282client = Client(api_key=os.getenv('XAI_API_KEY'))283284image_url = "https://science.nasa.gov/wp-content/uploads/2023/09/web-first-images-release.png"285286chat = client.chat.create(model="grok-4")287chat.append(288 user(289 "What's in this image?",290 image(image_url=image_url, detail="high"),291 )292)293294response = chat.sample()295print(response.content)296```297298```pythonOpenAISDK299import os300from openai import OpenAI301302XAI_API_KEY = os.getenv("XAI_API_KEY")303image_url = (304"https://science.nasa.gov/wp-content/uploads/2023/09/web-first-images-release.png"305)306307client = OpenAI(308 api_key=XAI_API_KEY,309 base_url="https://api.x.ai/v1",310)311312messages = [313 {314 "role": "user",315 "content": [316 {317 "type": "image_url",318 "image_url": {319 "url": image_url,320 "detail": "high",321 },322 },323 {324 "type": "text",325 "text": "What's in this image?",326 },327 ],328 },329]330331completion = client.chat.completions.create(332 model="grok-4",333 messages=messages,334)335336print(completion.choices[0].message.content)337```338339```javascriptOpenAISDK340import OpenAI from "openai";341const openai = new OpenAI({342apiKey: process.env.XAI_API_KEY,343baseURL: "https://api.x.ai/v1",344});345346const image_url =347"https://science.nasa.gov/wp-content/uploads/2023/09/web-first-images-release.png";348349const completion = await openai.chat.completions.create({350 model: "grok-4",351 messages: [352 {353 role: "user",354 content: [355 {356 type: "image_url",357 image_url: {358 url: image_url,359 detail: "high",360 },361 },362 {363 type: "text",364 text: "What's in this image?",365 },366 ],367 },368 ],369});370371console.log(completion.choices[0].message.content);372```373374```javascriptAISDK375import { xai } from '@ai-sdk/xai';376import { generateText } from 'ai';377378const result = await generateText({379model: xai('grok-4'),380messages: [381 {382 role: 'user',383 content: [384 {385 type: 'image',386 image: new URL(387 'https://science.nasa.gov/wp-content/uploads/2023/09/web-first-images-release.png',388 ),389 },390 {391 type: 'text',392 text: "What's in this image?",393 },394 ],395 },396 ],397});398399console.log(result.text);400```401402### Image input general limits403404* Maximum image size: `20MiB`405* Maximum number of images: No limit406* Supported image file types: `jpg/jpeg` or `png`.407* Any image/text input order is accepted (e.g. text prompt can precede image prompt)408409### Image detail levels410411The `"detail"` field controls the level of pre-processing applied to the image that will be provided to the model. It is optional and determines the resolution at which the image is processed. The possible values for `"detail"` are:412413* **`"auto"`**: The system will automatically determine the image resolution to use. This is the default setting, balancing speed and detail based on the model's assessment.414* **`"low"`**: The system will process a low-resolution version of the image. This option is faster and consumes fewer tokens, making it more cost-effective, though it may miss finer details.415* **`"high"`**: The system will process a high-resolution version of the image. This option is slower and more expensive in terms of token usage, but it allows the model to attend to more nuanced details in the image.416