Repository Public
1<!-- source: https://docs.x.ai/developers/model-capabilities/text/comparison (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Model Capabilities34# Comparison with Chat Completions API56The Responses API is the recommended way to interact with xAI models. Here's how it compares to the legacy Chat Completions API:78| Feature | Responses API | Chat Completions API (Deprecated) |9|---------|---------------|-----------------------------------|10| **Stateful Conversations** | Built-in support via `previous_response_id` | Stateless — must resend full history |11| **Server-side Storage** | Responses stored for 30 days | No storage — manage history yourself |12| **Reasoning Models** | Full support with encrypted reasoning content | No reasoning content returned |13| **Agentic Tools** | Native support for tools (search, code execution, MCP) | Function calling only |14| **Billing Optimization** | Automatic caching of conversation history | Full history billed on each request |15| **Future Features** | All new capabilities delivered here first | Legacy endpoint, limited updates |1617## Key API Changes1819### Parameter Mapping2021| Chat Completions | Responses API | Notes |22|-----------------|---------------|-------|23| `messages` | `input` | Array of message objects |24| `max_tokens` | `max_output_tokens` | Maximum tokens to generate |25| — | `previous_response_id` | Continue a stored conversation |26| — | `store` | Control server-side storage (default: `true`) |27| — | `include` | Request additional data like `reasoning.encrypted_content` |2829### Response Structure3031The response format differs between the two APIs:3233**Chat Completions** returns content in `choices[0].message.content`:3435```json36{37 "id": "chatcmpl-123",38 "choices": [{39 "message": {40 "role": "assistant",41 "content": "Hello! How can I help you?"42 }43 }]44}45```4647**Responses API** returns content in an `output` array with typed items:4849```json50{51 "id": "resp_123",52 "output": [{53 "type": "message",54 "role": "assistant",55 "content": [{56 "type": "output_text",57 "text": "Hello! How can I help you?"58 }]59 }]60}61```6263### Multi-turn Conversations6465With Chat Completions, you must resend the entire conversation history with each request. With Responses API, you can use `previous_response_id` to continue a conversation:6667```pythonWithoutSDK68# First request69response = client.responses.create(70 model="grok-4",71 input=[{"role": "user", "content": "What is 2+2?"}],72)7374# Continue the conversation - no need to resend history75second_response = client.responses.create(76 model="grok-4",77 previous_response_id=response.id,78 input=[{"role": "user", "content": "Now multiply that by 10"}],79)80```8182## Migration Path8384Migrating from Chat Completions to Responses API is straightforward. Here's how to update your code for each SDK:8586### Vercel AI SDK8788Switch from `xai()` to `xai.responses()`:8990```javascriptAISDK deletedLines="1" addedLines="2"91 model: xai('grok-4'),92 model: xai.responses('grok-4'),93```9495### OpenAI SDK (JavaScript)9697Switch from `client.chat.completions.create` to `client.responses.create`, and rename `messages` to `input`:9899```javascriptWithoutSDK deletedLines="1,3" addedLines="2,4"100const response = await client.chat.completions.create({101const response = await client.responses.create({102 messages: [103 input: [104 { role: "user", content: "Hello!" }105 ],106});107108```109110### OpenAI SDK (Python)111112Switch from `client.chat.completions.create` to `client.responses.create`, and rename `messages` to `input`:113114```pythonWithoutSDK deletedLines="1,3" addedLines="2,4"115response = client.chat.completions.create(116response = client.responses.create(117 messages=[118 input=[119 {"role": "user", "content": "Hello!"}120 ],121)122```123124### cURL125126Change the endpoint from `/v1/chat/completions` to `/v1/responses`, and rename `messages` to `input`:127128```bash deletedLines="1,5" addedLines="2,6"129curl https://api.x.ai/v1/chat/completions \130curl https://api.x.ai/v1/responses \131 -H "Content-Type: application/json" \132 -H "Authorization: Bearer $XAI_API_KEY" \133 -d '{ "model": "grok-4", "messages": [{"role": "user", "content": "Hello!"}] }'134 -d '{ "model": "grok-4", "input": [{"role": "user", "content": "Hello!"}] }'135```136137This will work for most use cases. If you have a unique integration, refer to the [Responses API documentation](/developers/model-capabilities/text/generate-text) for detailed guidance.138