xAI v1 API
The v1 API from xAI — 30 operation(s) for v1.
xAI v1 API is published by xAI on the APIs.io network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification.
Tagged areas include v1. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an API reference, and an AsyncAPI specification.
This API exposes 33 operations across 30 paths, and defines 153 schemas. It is described by OpenAPI 3.1.0, at version 1.0.0.
Requests are made against the base URL https://api.x.ai/v1.
33 operations
30 paths
153 schemas
2 DELETE17 GET14 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 1
xAI v1 API declares
1 security scheme
for authenticating requests.
It accepts HTTP bearer tokens (bearerAuth).
Paths & Operations 33
Across 30 paths, the API surfaces 33 operations — 2 DELETE, 17 GET, 14 POST. Each is listed below with its method, path, parameters, and response codes.
v1 33
GET
/v1/api-key
Get information about an API key, including name, status, permissions and users who created or modified this key.
POST
/v1/chat/completions
Create a chat response from text/image chat prompts. This is the endpoint for making requests to chat and image understanding models.
GET
/v1/chat/deferred-completion/{request_id}
Tries to fetch a result for a previously-started deferred completion. Returns 200 Success with the response body, if the request has been completed. Returns 202 Accepted when the request is pending p…
POST
/v1/complete
(Legacy - Not supported by reasoning models) Create a text completion response. This endpoint is compatible with the Anthropic API.
POST
/v1/completions
(Legacy - Not supported by reasoning models) Create a text completion response for a given prompt. Replaced by /v1/chat/completions.
POST
/v1/documents/search
Search for content related to the query within the given collections.
GET
/v1/embedding-models
List all embedding models available to the authenticating API key with full information. Additional information compared to /v1/models includes modalities, pricing, fingerprint and alias(es).
GET
/v1/embedding-models/{model_id}
Get full information about an embedding model with its modelid.
POST
/v1/embeddings
Create an embedding vector representation corresponding to the input text. This is the endpoint for making requests to embedding models.
GET
/v1/files
List files owned by the authenticated team, paginated. The response always returns a paginationtoken; pass it back as a query parameter to fetch the next page. The end of the list is reached when the…
POST
/v1/files
Upload a file to xAI's storage. Returns the file's metadata. Files can be referenced by ID anywhere a fileid is accepted (e.g. chat attachments). Maximum file size: 50 MB. Files are kept until you de…
GET
/v1/files/{file_id}
Retrieve metadata for a single file by ID. Errors with 404 if the file doesn't exist, has been deleted, or has passed its expiresat.
DELETE
/v1/files/{file_id}
Delete a file by ID. After this returns, the file no longer appears in GET /v1/files, content download returns 404, and the ID can no longer be referenced in chat attachments.
GET
/v1/files/{file_id}/content
Download the contents of a file as a stream of raw bytes. The response Content-Type is application/octet-stream. Use this for the binary payload; use GET /v1/files/{fileid} for metadata only.
GET
/v1/image-generation-models
List all image generation models available to the authenticating API key with full information. Additional information compared to /v1/models includes modalities, pricing, fingerprint and alias(es).
GET
/v1/image-generation-models/{model_id}
Get full information about an image generation model with its modelid.
POST
/v1/images/edits
Edit an image based on a prompt. This is the endpoint for making edit requests to image generation models.
POST
/v1/images/generations
Generate an image based on a prompt. This is the endpoint for making generation requests to image generation models.
GET
/v1/language-models
List all chat and image understanding models available to the authenticating API key with full information. Additional information compared to /v1/models includes modalities, pricing, fingerprint and…
GET
/v1/language-models/{model_id}
Get full information about a chat or image understanding model with its modelid.
POST
/v1/messages
Create a messages response. This endpoint is compatible with the Anthropic API.
GET
/v1/models
List all models available to the authenticating API key with minimalized information, including model names (ID), creation times, etc.
GET
/v1/models/{model_id}
Get minimalized information about a model with its modelid.
POST
/v1/responses
Generates a response based on text or image prompts. The response ID can be used to retrieve the response later or to continue the conversation without repeating prior context. New responses will be…
GET
/v1/responses/{response_id}
Retrieve a previously generated response.
DELETE
/v1/responses/{response_id}
Delete a previously generated response.
POST
/v1/tokenize-text
Tokenize text with the specified model
GET
/v1/video-generation-models
List all video generation models available to the authenticating API key with full information.
GET
/v1/video-generation-models/{model_id}
Get full information about a video generation model with its modelid.
POST
/v1/videos/edits
Edit a video based on a prompt. This is an asynchronous operation that returns a requestid for polling.
POST
/v1/videos/extensions
Extend a video by generating continuation content. This is an asynchronous operation that returns a requestid for polling.
POST
/v1/videos/generations
Generate a video from a text prompt and optionally an image. This is an asynchronous operation that returns a requestid for polling.
GET
/v1/videos/{request_id}
Get the result of a deferred video generation request.
Schemas 153
The contract defines 153 schemas that model the data the API accepts and returns. The most detailed are ModelResponse (32 properties), ModelRequest (26 properties), ChatRequest (25 properties), SampleRequest (18 properties). Each schema is shown below with its type and property counts.
VideoResolution
string
Resolution for video generation.
Function
object
2 properties
2 required
File
object
An uploaded file.
7 properties
5 required
VideoResponse
object
Video generation response.
6 properties
2 required
ReciprocalRankFusion
object
Configuration for reciprocal rank fusion (RRF) reranking.
3 properties
RankingMetric
string
Deprecated: Metric now comes from collection creation.
ModelOutput
LocalShellSkill
object
A skill available in the local shell environment.
3 properties
3 required
ServerSideToolUsageDetails
object
6 properties
6 required
ContentPart
object
4 properties
1 required
SampleContent
Message
Chat message objects.
ContentFormat
string
Format of the downloaded file content.
EmbeddingContent
Tool
Definition of one tool that the model can call.
GeneratedVideo
object
Generated video.
3 properties
2 required
HybridRetrieval
object
Document search using a combination of keyword and semantic search.
2 properties
EmbeddingUsage
object
2 properties
2 required
ShellCallOutputResult
object
The content of a shell tool call output that was emitted.
3 properties
1 required
MediaUsage
object
Billing and cost information for media generation requests (image and video).
1 property
1 required
MessageBody
object
Anthropic compatible message body
2 properties
2 required
WebSearchUserLocation
object
5 properties
1 required
MessageTools
object
4 properties
3 required
ListLanguageModelsResponse
object
1 property
1 required
GeneratedImageResponse
object
Image generation response for /v1/image/generations endpoint
2 properties
1 required
KeywordRetrieval
object
Document search using keyword matching (sparse embeddings).
1 property
VideoOutput
object
Output destination for generated video.
1 property
1 required
UploadFileMultipartRequest
object
Multipart form fields accepted by POST /v1/files. The expiresafter field MUST appear before file in the multipart body when both are present (the upload handle…
3 properties
1 required
EmbeddingInput
ToolChoice
Parameter to control how model chooses the tools.
EditVideoRequest
object
Request for editing video for /v1/videos/edits endpoint
5 properties
2 required
OutputTokensDetails
object
1 property
1 required
SystemMessageContent
FileSearchResult
object
4 properties
3 required
Content
Content of each chat message.
RerankerModel
object
Configuration for model-based reranking.
2 properties
PromptUsageDetail
object
Details of prompt usage.
4 properties
4 required
HybridReranker
Reranker configuration for hybrid retrieval.
ResponseFormat
Response format parameter for structured outputs.
GenerateVideoRequest
object
Request to generate video for /v1/videos/generations endpoint
9 properties
CompleteRequest
object
(Legacy) Anthropic compatible complete request on /v1/complete endpoint.
9 properties
ShellEnvironment
object
The environment configuration for a shell tool.
2 properties
1 required
MessageContentPart
ReasoningText
object
2 properties
2 required
OutputMessageContent
ModelInputPart
ChatResponse
object
The chat response body for /v1/chat/completions endpoint.
9 properties
5 required
Choice
object
4 properties
2 required
ShellCallOutcome
The outcome of a shell command execution.
VideoAspectRatio
string
Aspect ratio for video generation.
SystemMessagePart
object
3 properties
2 required
ImageAspectRatio
string
Aspect ratio for image generation. Only supported by grok-imagine models.
MessageUsage
object
4 properties
4 required
GeneratedImage
object
Generated images
3 properties
ModelInputContentItem
ShellCallOutput
object
The output of a shell tool call, sent by the client after local execution.
4 properties
3 required
ListVideoGenerationModelsResponse
object
1 property
1 required
TopLogProb
object
3 properties
2 required
MessageToolChoice
Tool choice option.
WebSearchCall
object
The output of a web search tool call.
4 properties
2 required
CodeInterpreterOutput
ImageGenerationModel
object
Details of an image generation model
11 properties
11 required
ModelResponse
object
The response body for /v1/responses endpoint.
32 properties
18 required
FileRef
object
2 properties
WebSearchSource
object
2 properties
1 required
LanguageModel
object
Details of a language model
14 properties
14 required
RagPipeline
string
MessageRequest
object
Request message for /v1/messages
12 properties
ModelRequest
object
The request body for /v1/responses endpoint.
26 properties
1 required
Reasoning
object
The reasoning done by the model.
6 properties
2 required
McpCall
object
The output of a MCP tool call.
8 properties
5 required
Model
object
Same as LanguageModel but fully compliant with the OpenAI API.
4 properties
4 required
SampleResponse
object
(Legacy) Response for /v1/completions endpoint
7 properties
5 required
ModelUsage
object
10 properties
7 required
ApiKey
object
12 properties
12 required
VideoUrl
object
Video input for editing and extension requests. Accepts a public URL, a base64-encoded data URL, or a fileid from the xAI Files API.
2 properties
WebSearchFilters
object
2 properties
RetrievalMode
Retrieval mode configuration for document search.
FunctionChoice
object
Function name.
1 property
1 required
ModelInput
Content of the input passed to a /v1/response request.
ShellCallAction
object
The shell commands and limits that describe how to run the tool call.
4 properties
1 required
ChatRequest
object
The chat request body for /v1/chat/completions endpoint.
25 properties
SummaryText
object
2 properties
2 required
MessageResponse
object
Response message for /v1/messages
8 properties
6 required
ModelTool
Definition of one tool that the model can call.
CompactionOutputItem
object
A compaction item from a previous /v1/responses/compact call. Accepted as input in /v1/responses calls. Clients must treat encryptedcontent as opaque — do not…
3 properties
2 required
EditImageRequest
object
Request for editing image
9 properties
1 required
GenerateImageRequest
object
7 properties
MessageContent
MessageImageContent
OutputFile
object
A file generated during the model's response (e.g., by the code execution tool).
2 properties
2 required
ShellCall
object
A shell command call emitted by the model for local execution.
6 properties
3 required
ModelToolChoice
Parameter to control how model chooses the tools.
CompleteResponse
object
(Legacy) Anthropic compatible complete response on /v1/complete endpoint.
5 properties
4 required
DeleteStoredCompletionResponse
object
Response to delete a stored completion.
3 properties
3 required
ToolCall
object
4 properties
2 required
TokenizeResponseToken
object
3 properties
3 required
VideoErrorCode
string
Machine-readable error codes for video generation failures. These are the codes that can appear in VideoError.code when polling a deferred video generation res…
Annotation
object
5 properties
2 required
EmbeddingModel
object
Details of an embedding model
11 properties
11 required
CompletionUsageDetail
object
Details of completion usage.
4 properties
4 required
DeleteFileResponse
object
3 properties
3 required
ExtendVideoRequest
object
Request for extending a video for /v1/videos/extensions endpoint
5 properties
2 required
ListFilesResponse
object
2 properties
1 required
TokenizeRequest
object
3 properties
LogProbs
object
1 property
EmbeddingResponse
object
4 properties
3 required
StreamOptions
object
Options available when using streaming response.
1 property
1 required
WebSearchAction
ListEmbeddingModelsResponse
object
1 property
1 required
FileSearchCall
object
The output of a web search tool call.
5 properties
3 required
VideoError
object
Structured error returned when video generation fails.
2 properties
2 required
VideoGenerationModel
object
Details of a video generation model
9 properties
9 required
EmbeddingRequest
object
6 properties
ImageResolution
string
Resolution for image generation. Only supported by grok-imagine models.
SearchSource
MessageMetadata
object
1 property
ModelResponseConfiguration
object
1 property
SearchParameters
object
Parameters to control realtime data.
6 properties
FunctionToolCall
object
A tool call to run a function.
6 properties
4 required
OutputMessage
object
An output message from the model.
5 properties
3 required
SearchResponse
object
SearchResponse defines the response to a search request.
1 property
1 required
Usage
object
7 properties
7 required
GroupBy
object
Group search results by metadata key(s) and keep top-k per group.
2 properties
1 required
InputTokensDetails
object
1 property
1 required
WebSearchOptions
object
3 properties
SampleRequest
object
(Legacy) Request for /v1/completions endpoint
18 properties
ListImageGenerationModelsResponse
object
1 property
1 required
IncompleteDetails
Details about why a response is incomplete.
ReasoningConfiguration
object
3 properties
MessageResponseContent
TokenLogProb
object
4 properties
3 required
DocumentsSource
object
DocumentsSource defines the source of documents to search over.
2 properties
1 required
FunctionToolCallOutput
object
The output of a function tool call.
3 properties
3 required
ModelInputContent
TokenizeResponse
object
1 property
1 required
ImageUrl
object
Image input for generation and editing requests. Accepts a public URL, a base64-encoded data URL, or a fileid from the xAI Files API.
2 properties
StartDeferredResponse
object
Response for starting a deferred operation.
1 property
1 required
ToolResultContent
Content of a toolresult block. The Anthropic SDK may send this as either a plain string or an array of typed content blocks (e.g. [{"type": "text", "text": "..…
SemanticRetrieval
object
Document search using semantic similarity (dense embeddings).
1 property
SampleChoice
object
3 properties
3 required
ModelResponseFormat
Response format parameter for structured outputs.
MessageToolInputSchema
object
3 properties
2 required
SearchMatch
object
SearchMatch defines a single match from a search request.
7 properties
6 required
Embedding
object
3 properties
3 required
CustomToolCall
object
The output of a custom tool call.
6 properties
4 required
GroupByAggregate
Aggregation function to apply within each group.
SearchRequest
object
SearchRequest defines the request to search for documents.
8 properties
2 required
ChoiceMessage
object
5 properties
1 required
ListModelsResponse
object
2 properties
2 required
CodeInterpreterCall
object
The output of a code interpreter tool call.
5 properties
2 required
ToolResultContentBlock
A single content block within a toolresult's array content.
FunctionDefinition
object
Definition of the tool call made available to the model.
4 properties
2 required
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
#v1