Available endpoints
On this page
An overview of the Grok API
The xAI API isn’t limited to text generation. It exposes a set of endpoints covering image and video generation, speech synthesis, file management, and asynchronous processing. This lesson maps out the available endpoints so you know which features to use in your projects.
Text generation
POST /v1/responses (recommended)
The main endpoint for any interaction with the Grok models. It supports text, vision, tools (function calling), web search, and X search.
Key parameters: model, input, instructions, stream, tools, reasoning.
POST /v1/chat/completions (OpenAI-compatible)
The endpoint in OpenAI format, maintained for compatibility with existing tools. It accepts the same parameters as the OpenAI API: model, messages, temperature, stream, tools.
GET /v1/responses/{id}
Retrieves a previously generated response if it was stored (store: true parameter). Responses are kept for 30 days.
DELETE /v1/responses/{id}
Deletes a stored response before it expires automatically after 30 days.
Asynchronous processing
POST /v1/chat/completions (deferred mode)
When you add "deferred": true to the request, the API immediately returns a request_id without waiting for generation to finish. It’s useful for long requests or batch processing.
GET /v1/chat/deferred-completion/{request_id}
Retrieves the result of an asynchronous call:
- HTTP 200: generation is finished, and the body contains the complete response
- HTTP 202: generation is still in progress, so try again later
Image generation
POST /v1/images/generations
Generates images from a text description.
POST /v1/images/edits
Edits an existing image based on text instructions.
Video generation
POST /v1/videos/generations
Starts generating a video from a text prompt.
GET /v1/videos/{id}
Checks the status of a video being generated and retrieves the result URL once it’s finished.
POST /v1/videos/edits
Edits an existing video.
POST /v1/videos/extensions
Extends an existing video.
Speech synthesis
POST /v1/tts
Converts text to audio (text-to-speech). Useful for building voice assistants or automated audio content.
Real-time voice agent
WSS wss://api.x.ai/v1/realtime
A WebSocket endpoint for building interactive voice agents. Communication happens in real time, sending and receiving audio.
File management
POST /v1/files
Uploads a file to the xAI platform. Files can then be used for RAG (retrieval-augmented generation) with collections.
GET /v1/files
Lists all the files uploaded to your space.
GET /v1/files/{id}
Retrieves the metadata of a specific file.
DELETE /v1/files/{id}
Deletes an uploaded file.
Batch processing
POST /v1/batches
Creates a batch of requests to process as a group, often at a reduced price.
GET /v1/batches
Lists batches in progress and completed.
Server-side built-in tools
The /v1/responses endpoint supports tools that the API runs directly, with no client-side logic:
- web_search: real-time web search
- x_search: search in X (Twitter) posts
- code_interpreter: Python code execution
- function: custom function calls (function calling)
You turn these tools on with the request’s tools parameter.
Key takeaways
- The API covers text, images, video, audio, and files
/v1/responsesis the main endpoint, with the most complete supportdeferredmode enables asynchronous processing for long requests- Server-side tools (web_search, x_search, code_interpreter) enrich answers with no extra code