SPB Git

Repository Public

comparison.md 4.4 KB 138 lines markdown

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
Files main
Menu

Theme