{"openapi":"3.0.0","info":{"description":"xAI API: Grok models for chat completions, messages, responses, image understanding and generation, video generation, embeddings, files and collections search","version":[{"name":"v1","value":"v1"}]},"servers":[{"description":"xAI API: Grok models for chat completions, messages, responses, image understanding and generation, video generation, embeddings, files and collections search","url":"https://api.apirails.com/xai"}],"paths":{"/v1/chat/completions":{"post":{"tags":["Chat"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/chat-completions","api_endpoint":"https://api.x.ai/v1/chat/completions"},"summary":"Create Chat Completion","description":"Creates a model response for the given chat conversation","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"frequency_penalty":{"type":"number","description":"Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far"},"logit_bias":{"type":"object","description":"Modify the likelihood of specified tokens appearing in the completion","properties":{}},"max_tokens":{"type":"number","description":"The maximum number of tokens that can be generated in the chat completion"},"messages":{"type":"array","description":"A list of messages comprising the conversation so far","required":true,"items":{"type":"string"}},"model":{"type":"string","description":"ID of the model to use","required":true},"n":{"type":"number","description":"How many chat completion choices to generate for each input message"},"presence_penalty":{"type":"number","description":"Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far"},"response_format":{"type":"object","description":"An object specifying the format that the model must output","properties":{}},"stop":{"type":"array","description":"Up to 4 sequences where the API will stop generating further tokens","items":{"type":"string"}},"stream":{"type":"boolean","description":"If set, partial message deltas will be sent","enum":[true,false]},"temperature":{"type":"number","description":"What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic"},"tool_choice":{"type":"object","description":"Controls which (if any) tool is called by the model","properties":{}},"tools":{"type":"array","description":"A list of tools the model may call","items":{"type":"string"}},"top_p":{"type":"number","description":"An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass"},"user":{"type":"string","description":"A unique identifier representing your end-user"}}},"example":{"frequency_penalty":"","logit_bias":{},"max_tokens":"","messages":[{"content":"Hello, world","role":"user"}],"model":"grok-beta|grok-2","n":"","presence_penalty":"","response_format":{},"stop":[],"stream":"","temperature":0.8,"tool_choice":{},"tools":[],"top_p":"","user":""}}}}}},"/v1/models":{"get":{"tags":["Models"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/models","api_endpoint":"https://api.x.ai/v1/models"},"summary":"List Models","description":"Lists the currently available models, and provides basic information about each one such as the owner and availability","security":[{"bearerAuth":[]}]}},"/v1/models/{model_id}":{"get":{"tags":["Models"],"parameters":[{"name":"model_id","in":"path","description":"The ID of the model to use for this request","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/models","api_endpoint":"https://api.x.ai/v1/models/{model_id}"},"summary":"Retrieve Model","description":"Retrieves a model instance, providing basic information about the model such as the owner and permissioning","security":[{"bearerAuth":[]}]}},"/v1/messages":{"post":{"tags":["Message"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/messages","api_endpoint":"https://api.x.ai/v1/messages"},"summary":"Create a Message","description":"Create a message (Anthropic compatible endpoint)","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"max_tokens":{"type":"number","description":"The maximum number of tokens to generate before stopping","required":true},"messages":{"type":"array","description":"Input messages","required":true,"items":{"type":"string"}},"model":{"type":"string","description":"The model that will complete your prompt","required":true},"stop_sequences":{"type":"array","description":"Custom text sequences that will cause the model to stop generating","items":{"type":"string"}},"stream":{"type":"boolean","description":"Whether to incrementally stream the response using server-sent events","enum":[true,false]},"system":{"type":"string","description":"System prompt"},"temperature":{"type":"number","description":"Amount of randomness injected into the response"},"tool_choice":{"type":"object","description":"The model can use a specific tool, any available tool, or decide by itself","properties":{}},"tools":{"type":"array","description":"Definitions of tools that the model may use","items":{"type":"string"}},"top_p":{"type":"number","description":"Use nucleus sampling"}}},"example":{"max_tokens":"","messages":[{"content":"Hello, world","role":"user"}],"model":"grok-beta|grok-2","stop_sequences":[],"stream":"","system":"","temperature":"","tool_choice":{},"tools":[],"top_p":""}}}}}},"/v1/responses":{"post":{"tags":["Responses"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/responses","api_endpoint":"https://api.x.ai/v1/responses"},"summary":"Create New Response","description":"Create a new response","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"max_tokens":{"type":"number","description":"The maximum number of tokens that can be generated"},"messages":{"type":"array","description":"A list of messages comprising the conversation so far","required":true,"items":{"type":"string"}},"model":{"type":"string","description":"ID of the model to use","required":true},"temperature":{"type":"number","description":"What sampling temperature to use"}}},"example":{"max_tokens":"","messages":[],"model":"","temperature":""}}}}}},"/v1/responses/{response_id}":{"get":{"tags":["Responses"],"parameters":[{"name":"response_id","in":"path","description":"The ID of the response to retrieve","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/responses","api_endpoint":"https://api.x.ai/v1/responses/{response_id}"},"summary":"Retrieve Previous Response","description":"Retrieve a previous response by ID","security":[{"bearerAuth":[]}]},"delete":{"tags":["Responses"],"parameters":[{"name":"response_id","in":"path","description":"The ID of the response to delete","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/responses","api_endpoint":"https://api.x.ai/v1/responses/{response_id}"},"summary":"Delete Previous Response","description":"Delete a previous response by ID","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{}},"example":{}}}}}},"/v1/images/generations":{"post":{"tags":["Images"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/images","api_endpoint":"https://api.x.ai/v1/images/generations"},"summary":"Create Image Generation","description":"Creates an image generation request","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"model":{"type":"string","description":"ID of the image generation model to use","required":true},"n":{"type":"number","description":"The number of images to generate"},"prompt":{"type":"string","description":"A text description of the desired image","required":true},"response_format":{"type":"string","description":"The format in which the generated images are returned"},"size":{"type":"string","description":"The size of the generated images"},"user":{"type":"string","description":"A unique identifier representing your end-user"}}},"example":{"model":"","n":"","prompt":"","response_format":"","size":"","user":""}}}}}},"/v1/api-key":{"get":{"tags":["API Key"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/api-key","api_endpoint":"https://api.x.ai/v1/api-key"},"summary":"Get API Key","description":"Get information about the current API key","security":[{"bearerAuth":[]}]}},"/v1/language-models":{"get":{"tags":["Models"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/language-models","api_endpoint":"https://api.x.ai/v1/language-models"},"summary":"List Language Models","description":"Lists the currently available language models","security":[{"bearerAuth":[]}]}},"/v1/language-models/{model_id}":{"get":{"tags":["Models"],"parameters":[{"name":"model_id","in":"path","description":"The ID of the language model","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/language-models","api_endpoint":"https://api.x.ai/v1/language-models/{model_id}"},"summary":"Get Language Model","description":"Retrieves a specific language model by ID","security":[{"bearerAuth":[]}]}},"/v1/image-generation-models":{"get":{"tags":["Models"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/image-generation-models","api_endpoint":"https://api.x.ai/v1/image-generation-models"},"summary":"List Image Generation Models","description":"Lists the currently available image generation models","security":[{"bearerAuth":[]}]}},"/v1/image-generation-models/{model_id}":{"get":{"tags":["Models"],"parameters":[{"name":"model_id","in":"path","description":"The ID of the image generation model","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/image-generation-models","api_endpoint":"https://api.x.ai/v1/image-generation-models/{model_id}"},"summary":"Get Image Generation Model","description":"Retrieves a specific image generation model by ID","security":[{"bearerAuth":[]}]}},"/v1/tokenize-text":{"post":{"tags":["Text"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/tokenize-text","api_endpoint":"https://api.x.ai/v1/tokenize-text"},"summary":"Tokenize Text","description":"Tokenize text using a specified model","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"text":{"type":"string","description":"The text to tokenize","required":true},"model":{"type":"string","description":"ID of the model to use for tokenization","required":true}}},"example":{"text":"","model":""}}}}}},"/v1/chat/deferred-completion/{request_id}":{"get":{"tags":["Chat"],"parameters":[{"name":"request_id","in":"path","description":"The ID of the deferred completion request","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/chat-completions","api_endpoint":"https://api.x.ai/v1/chat/deferred-completion/{request_id}"},"summary":"Get Deferred Chat Completion","description":"Get the result of a deferred chat completion request","security":[{"bearerAuth":[]}]}},"/v1/completions":{"post":{"tags":["Completions"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/completions","api_endpoint":"https://api.x.ai/v1/completions"},"summary":"Create Completion","description":"Creates a completion for the provided prompt and parameters (Legacy endpoint)","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"frequency_penalty":{"type":"number","description":"Number between -2.0 and 2.0"},"max_tokens":{"type":"number","description":"The maximum number of tokens to generate"},"model":{"type":"string","description":"ID of the model to use","required":true},"n":{"type":"number","description":"How many completions to generate for each prompt"},"presence_penalty":{"type":"number","description":"Number between -2.0 and 2.0"},"prompt":{"type":"string","description":"The prompt(s) to generate completions for","required":true},"stop":{"type":"array","description":"Up to 4 sequences where the API will stop generating further tokens","items":{"type":"string"}},"stream":{"type":"boolean","description":"Whether to stream back partial progress","enum":[true,false]},"temperature":{"type":"number","description":"What sampling temperature to use"},"top_p":{"type":"number","description":"An alternative to sampling with temperature"},"user":{"type":"string","description":"A unique identifier representing your end-user"}}},"example":{"frequency_penalty":"","max_tokens":"","model":"","n":"","presence_penalty":"","prompt":"","stop":[],"stream":"","temperature":"","top_p":"","user":""}}}}}},"/v1/complete":{"post":{"tags":["Completions"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/api-reference/complete","api_endpoint":"https://api.x.ai/v1/complete"},"summary":"Create Completion (Anthropic Compatible)","description":"Creates a completion (Anthropic compatible legacy endpoint)","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"max_tokens_to_sample":{"type":"number","description":"The maximum number of tokens to generate","required":true},"model":{"type":"string","description":"ID of the model to use","required":true},"prompt":{"type":"string","description":"The prompt to generate completions for","required":true},"stop_sequences":{"type":"array","description":"Custom text sequences that will cause the model to stop generating","items":{"type":"string"}},"stream":{"type":"boolean","description":"Whether to incrementally stream the response","enum":[true,false]},"temperature":{"type":"number","description":"Amount of randomness injected into the response"},"top_p":{"type":"number","description":"Use nucleus sampling"}}},"example":{"max_tokens_to_sample":"","model":"","prompt":"","stop_sequences":[],"stream":"","temperature":"","top_p":""}}}}}},"/v1/files":{"get":{"tags":["Files"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/files-api","api_endpoint":"https://api.x.ai/v1/files"},"summary":"List Files","description":"Returns a list of files that belong to the user's organization","security":[{"bearerAuth":[]}]},"post":{"tags":["Files"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/files/upload","api_endpoint":"https://api.x.ai/v1/files"},"summary":"Upload file","description":"Upload a file to xAI's storage. Returns the file's metadata. Files can be referenced by ID anywhere a `file_id` is accepted (e.g. chat attachments). Maximum file size: 50 MB. Files are kept until you delete them, or until `expires_after` elapses if set at upload time.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":false,"content":{"multipart/form-data":{"schema":{"type":"object","required":[],"properties":{"expires_after":{"type":"number","description":"Optional TTL in seconds (measured from upload time). Must be between 3600 (1 hour) and 2592000 (30 days). If unset the file does not expire. Accepts either a plain integer or the OpenAI SDK deepObject form (`expires_after[anchor]=created_at` + `expires_after[seconds]=N`) as separate multipart fields. The anchor+seconds form must arrive before the `file` part."},"file":{"type":"string","format":"binary","description":"The file to upload. The filename from the multipart `Content-Disposition: filename=` header is recorded as the file's `filename`.","required":true},"purpose":{"type":"string","description":"Optional purpose label, accepted for OpenAI SDK compatibility. xAI does not enforce or interpret this field. Setting `\"assistants\"` is the conventional choice."}}},"example":{"expires_after":"","file":"(binary)","purpose":""}}}}}},"/v1/files/{file_id}":{"get":{"tags":["Files"],"parameters":[{"name":"file_id","in":"path","description":"The ID of the file to use for this request","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/files-api","api_endpoint":"https://api.x.ai/v1/files/{file_id}"},"summary":"Get File Metadata","description":"Returns information about a specific file","security":[{"bearerAuth":[]}]},"delete":{"tags":["Files"],"parameters":[{"name":"file_id","in":"path","description":"The ID of the file to delete","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/docs/files-api","api_endpoint":"https://api.x.ai/v1/files/{file_id}"},"summary":"Delete File","description":"Delete a file","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{}},"example":{}}}}}},"/v1/files/{file_id}/content":{"get":{"tags":["Files"],"parameters":[{"name":"file_id","in":"path","description":"The file's `id` to download.","required":true,"schema":{"type":"string","example":""}},{"name":"format","in":"query","description":"Format of the downloaded content.","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/files/download","api_endpoint":"https://api.x.ai/v1/files/{file_id}/content"},"summary":"Download file content","description":"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/{file_id}` for metadata only.","security":[{"bearerAuth":[]}]}},"/v1/files/{file_id}/public-url":{"post":{"tags":["Files"],"parameters":[{"name":"file_id","in":"path","description":"The file's `id`.","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/files/manage","api_endpoint":"https://api.x.ai/v1/files/{file_id}/public-url"},"summary":"Create file public URL","description":"Create a permanent, unauthenticated public URL for an existing file. The underlying file is unaffected and can still be fetched through the authenticated content endpoint. Use this when you want to share a stored asset (image, video, PDF) outside your API-keyed environment. Public URLs can be revoked at any time via `POST /v1/files/{file_id}/public-url/revoke`.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"expires_after":{"type":"string","description":"Seconds from now until the public URL expires. Must be between `3600` (1 hour) and `2592000` (30 days). Omit to inherit the file's expiry (if it has one) or to make the URL valid indefinitely."}}},"example":{"expires_after":""}}}}}},"/v1/files/{file_id}/public-url/revoke":{"post":{"tags":["Files"],"parameters":[{"name":"file_id","in":"path","description":"The file's `id`.","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/files/manage","api_endpoint":"https://api.x.ai/v1/files/{file_id}/public-url/revoke"},"summary":"Revoke file public URL","description":"Revoke the active public URL for a file. The underlying file remains available through the authenticated content endpoint. Revoke is idempotent — calling it on a file without an active public URL returns `revoked: false` without an error.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{}},"example":{}}}}}},"/v1/embeddings":{"post":{"tags":["Embeddings"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference","api_endpoint":"https://api.x.ai/v1/embeddings"},"summary":"Create embeddings","description":"Create an embedding vector representation corresponding to the input text. This is the endpoint for making requests to embedding models.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"dimensions":{"type":"number","description":"The number of dimensions the resulting output embeddings should have."},"encoding_format":{"type":"string","description":"The format to return the embeddings in. Can be either `float` or `base64`."},"input":{"type":"string"},"model":{"type":"string","description":"ID of the model to use."},"preview":{"type":"string","description":"Flag to use the new format of the API."},"user":{"type":"string","description":"A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."}}},"example":{"dimensions":"","encoding_format":"","input":"","model":"v1","preview":"","user":""}}}}}},"/v1/embedding-models":{"get":{"tags":["Embeddings"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference","api_endpoint":"https://api.x.ai/v1/embedding-models"},"summary":"List embedding models","description":"List all embedding models available to the authenticating API key with full information. Additional information compared to /v1/models includes modalities, fingerprint and alias(es).","security":[{"bearerAuth":[]}]}},"/v1/embedding-models/{model_id}":{"get":{"tags":["Embeddings"],"parameters":[{"name":"model_id","in":"path","description":"ID of the model to get.","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference","api_endpoint":"https://api.x.ai/v1/embedding-models/{model_id}"},"summary":"Retrieve embedding model","description":"Get full information about an embedding model with its model_id.","security":[{"bearerAuth":[]}]}},"/v1/video-generation-models":{"get":{"tags":["Videos"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference/videos","api_endpoint":"https://api.x.ai/v1/video-generation-models"},"summary":"List video generation models","description":"List all video generation models available to the authenticating API key with full information.","security":[{"bearerAuth":[]}]}},"/v1/video-generation-models/{model_id}":{"get":{"tags":["Videos"],"parameters":[{"name":"model_id","in":"path","description":"ID of the model to get.","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference/videos","api_endpoint":"https://api.x.ai/v1/video-generation-models/{model_id}"},"summary":"Retrieve video generation model","description":"Get full information about a video generation model with its model_id.","security":[{"bearerAuth":[]}]}},"/v1/videos/generations":{"post":{"tags":["Videos"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference/videos","api_endpoint":"https://api.x.ai/v1/videos/generations"},"summary":"Generate video","description":"Generate a video from a text prompt and optionally an image. This is an asynchronous operation that returns a request_id for polling.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"aspect_ratio":{"type":"string"},"duration":{"type":"number","description":"Video duration in seconds. Range: [1, 15]. Default: 8. Also accepts `seconds` for OpenAI API compatibility. Accepts both number (8) and string (\"8\") values."},"image":{"type":"string"},"model":{"type":"string","description":"Model to be used."},"output":{"type":"string"},"prompt":{"type":"string","description":"Prompt for video generation. Required for text-to-video (T2V) and reference-to-video (R2V). Optional for image-to-video (I2V) — when omitted, the model generates a video from the image alone."},"reference_audios":{"type":"array","description":"Optional reference audio clips (voice identity) for reference-to-video generation. Each entry supplies a clip via `url` or selects a voice via `voice_id`; caller-supplied clips must be at most 15 seconds long. Only supported by select video models; at most 3 entries. May be provided without `reference_images` (audio-only reference-to-video) — at least one reference of either kind selects the reference-to-video mode.","items":{"type":"object","properties":{"url":{"type":"string","description":"Base64-encoded audio data URL (e.g. `data:audio/wav;base64,...`) or an http(s) URL to a downloadable audio clip of at most 15 seconds. Mutually exclusive with `voice_id`."},"voice_id":{"type":"string","description":"Identifier of a first-party preset voice (e.g. \"ara\"; same voice identifiers as the TTS API), resolved server-side to a curated reference clip from the model's voice-preset catalog. Models configured for custom voices also accept a custom voice identifier. Mutually exclusive with `url`."}}}},"reference_images":{"type":"array","description":"Optional reference images for reference-to-video (R2V) generation. When provided generates video using these images as style/content references.","items":{"type":"object","properties":{"file_id":{"type":"string","description":"File ID from the xAI Files API. Mutually exclusive with `url`. The file must be an image (JPEG, PNG, or WebP) and fully uploaded."},"url":{"type":"string","description":"Public URL or base64-encoded data URL of the image (JPEG, PNG, or WebP). Also accepts `image_url` for compatibility. Required when `file_id` is not set."}}}},"resolution":{"type":"string"},"storage_options":{"type":"string"},"user":{"type":"string","description":"A unique identifier representing your end-user."}}},"example":{"aspect_ratio":"","duration":"","image":"","model":"grok-imagine-video","output":"","prompt":"","reference_audios":[],"reference_images":[],"resolution":"","storage_options":"","user":""}}}}}},"/v1/videos/edits":{"post":{"tags":["Videos"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference/videos","api_endpoint":"https://api.x.ai/v1/videos/edits"},"summary":"Edit video","description":"Edit a video based on a prompt. This is an asynchronous operation that returns a request_id for polling.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"model":{"type":"string","description":"Model to be used."},"output":{"type":"string"},"prompt":{"type":"string","description":"Prompt for video editing.","required":true},"storage_options":{"type":"string"},"user":{"type":"string","description":"A unique identifier representing your end-user."},"video":{"type":"object","description":"Video input for editing and extension requests. Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API.","required":true,"properties":{"file_id":{"type":"string","description":"File ID from the xAI Files API. Mutually exclusive with `url`. The file must be a video (e.g., MP4) and fully uploaded."},"url":{"type":"string","description":"URL of the video (public URL or base64-encoded data URL). The video must have the `.mp4` file extension and be encoded with `.mp4` supported codecs such as H.265, H.264, AV1, etc. Required when `file_id` is not set."}}}}},"example":{"model":"grok-imagine-video","output":"","prompt":"","storage_options":"","user":"","video":{}}}}}}},"/v1/videos/extensions":{"post":{"tags":["Videos"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference/videos","api_endpoint":"https://api.x.ai/v1/videos/extensions"},"summary":"Extend video","description":"Extend a video by generating continuation content. This is an asynchronous operation that returns a request_id for polling.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"duration":{"type":"number","description":"Duration of the extension segment to generate in seconds (2-10). Defaults to 6 seconds if not specified."},"model":{"type":"string","description":"Model to be used."},"output":{"type":"string"},"prompt":{"type":"string","description":"Prompt describing what should happen next in the video.","required":true},"storage_options":{"type":"string"},"video":{"type":"object","description":"Video input for editing and extension requests. Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API.","required":true,"properties":{"file_id":{"type":"string","description":"File ID from the xAI Files API. Mutually exclusive with `url`. The file must be a video (e.g., MP4) and fully uploaded."},"url":{"type":"string","description":"URL of the video (public URL or base64-encoded data URL). The video must have the `.mp4` file extension and be encoded with `.mp4` supported codecs such as H.265, H.264, AV1, etc. Required when `file_id` is not set."}}}}},"example":{"duration":"","model":"grok-imagine-video","output":"","prompt":"","storage_options":"","video":{}}}}}}},"/v1/videos/{request_id}":{"get":{"tags":["Videos"],"parameters":[{"name":"request_id","in":"path","description":"The deferred request id returned by a previous video generation request.","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference/videos","api_endpoint":"https://api.x.ai/v1/videos/{request_id}"},"summary":"Get video result","description":"Get the result of a deferred video generation request.","security":[{"bearerAuth":[]}]}},"/v1/images/edits":{"post":{"tags":["Images"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference/images","api_endpoint":"https://api.x.ai/v1/images/edits"},"summary":"Edit image","description":"Edit an image based on a prompt. This is the endpoint for making edit requests to image generation models.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"aspect_ratio":{"type":"string"},"image":{"type":"string"},"images":{"type":"array","description":"List of input images for multi-reference editing. Mutually exclusive with `image`. When multiple images are provided, refer to them as \\<IMAGE_0\\>, \\<IMAGE_1\\>, etc. in the prompt.","items":{"type":"object","properties":{"file_id":{"type":"string","description":"File ID from the xAI Files API. Mutually exclusive with `url`. The file must be an image (JPEG, PNG, or WebP) and fully uploaded."},"url":{"type":"string","description":"Public URL or base64-encoded data URL of the image (JPEG, PNG, or WebP). Also accepts `image_url` for compatibility. Required when `file_id` is not set."}}}},"model":{"type":"string","description":"Model to be used."},"n":{"type":"number","description":"Number of image edits to be generated."},"prompt":{"type":"string","description":"Prompt for image editing.","required":true},"resolution":{"type":"string"},"response_format":{"type":"string","description":"Response format to return the image in. Can be `url` or `b64_json`. If `b64_json` is specified, the image will be returned as a base64-encoded string instead of a url to the generated image file."},"storage_options":{"type":"string"},"user":{"type":"string","description":"A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."}}},"example":{"aspect_ratio":"","image":"","images":[],"model":"grok-imagine-image","n":"","prompt":"","resolution":"","response_format":"","storage_options":"","user":""}}}}}},"/v1/me":{"get":{"tags":["Account"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference/other","api_endpoint":"https://api.x.ai/v1/me"},"summary":"Get authenticated caller","description":"Get information about the currently authenticated caller. Works with both API keys and OAuth tokens. Returns identity, team, and ZDR status.","security":[{"bearerAuth":[]}]}},"/v1/responses/compact":{"post":{"tags":["Responses"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference/responses","api_endpoint":"https://api.x.ai/v1/responses/compact"},"summary":"Compact responses input window","description":"Compacts a full Responses API input window into a shorter canonical window.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"input":{"type":"string","description":"Content of the input passed to a `/v1/response` request.","required":true},"model":{"type":"string","description":"Model to use for compaction summarization (required).","required":true}}},"example":{"input":"","model":""}}}}}},"/v1/responses/{response_id}/input_items":{"get":{"tags":["Responses"],"parameters":[{"name":"response_id","in":"path","description":"The response id returned by a previous create response request.","required":true,"schema":{"type":"string","example":""}},{"name":"after","in":"query","description":"Cursor for pagination. Returns items after this item ID.","schema":{"type":"string","example":""}},{"name":"limit","in":"query","description":"Maximum number of items to return (1-100, default 20).","schema":{"type":"number","example":""}},{"name":"order","in":"query","description":"Sort order: asc or desc. Default asc.","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/inference/responses","api_endpoint":"https://api.x.ai/v1/responses/{response_id}/input_items"},"summary":"List response input items","description":"List input items for a previously generated response.","security":[{"bearerAuth":[]}]}},"/v1/documents/search":{"post":{"tags":["Search"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.x.ai/developers/rest-api-reference/collections/search","api_endpoint":"https://api.x.ai/v1/documents/search"},"summary":"Search collections","description":"Search for content related to the query within the given collections.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"filter":{"type":"string","description":"Optional metadata filter string to apply to search results. Uses AIP-160 filter syntax for querying document metadata. Supports comparison operators: `=`, `!=`, `>`, `>=`, `<`, `<=` Supports logical operators: `AND`, `OR` Supports range syntax: `field:10..20` (inclusive) Examples: `author = \"John\"` or `year > 2020 AND category = \"finance\"`"},"group_by":{"type":"string"},"instructions":{"type":"string","description":"User-defined instructions to be included in the search query. Defaults to generic search instructions."},"limit":{"type":"number","description":"The number of chunks to return. Will always return the top matching chunks. Optional, defaults to 10."},"query":{"type":"string","description":"The query to search for which will be embedded using the same embedding model as the one used for the source to query.","required":true},"ranking_metric":{"type":"string"},"retrieval_mode":{"type":"string"},"source":{"type":"object","description":"DocumentsSource defines the source of documents to search over.","required":true,"properties":{"collection_ids":{"type":"array","description":"The collection IDs to search in.","required":true},"rag_pipeline":{"type":"string"}}}}},"example":{"filter":"","group_by":"","instructions":"","limit":"","query":"","ranking_metric":"","retrieval_mode":"","source":{}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"security":[{"bearerAuth":[]}]}