Generates conversational completions using Grok foundation models, including multi-turn conversations, function calling, structured outputs, and reasoning. OpenAI-compatible Chat Completions interface.
{"openapi":"3.1.0","info":{"title":"xAI's REST API","description":"REST API for xAI compatible with other providers.","license":{"name":""},"version":"1.0.0"},"paths":{"/v1/api-key":{"get":{"tags":["v1"],"summary":"Get information about an API key, including name, status, permissions and users who created or modified this key.","operationId":"handle_get_api_key_info_request","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"},"example":{"redacted_api_key":"xai-...b14o","user_id":"59fbe5f2-040b-46d5-8325-868bb8f23eb2","name":"My API Key","create_time":"2024-01-01T12:55:18.139305Z","modify_time":"2024-08-28T17:20:12.343321Z","modified_by":"3d38b4dc-4eb7-4785-ae26-c3fa8997ffc7","team_id":"5ea6f6bd-7815-4b8a-9135-28b2d7ba6722","acls":["api-key:model:*","api-key:endpoint:*"],"api_key_id":"ae1e1841-4326-4b36-a8a9-8a1a7237db11","team_blocked":false,"api_key_blocked":false,"api_key_disabled":false}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."}},"security":[{"bearerAuth":[]}]}},"/v1/chat/completions":{"post":{"tags":["v1"],"summary":"Create a chat response from text/image chat prompts. This is the endpoint for making requests to chat and image understanding models.","operationId":"handle_generic_completion_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"},"example":{"messages":[{"role":"system","content":"You are a helpful assistant that can answer questions and help with tasks."},{"role":"user","content":"What is 101*3?"}],"model":"latest"}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"},"example":{"id":"a3d1008e-4544-40d4-d075-11527e794e4a","object":"chat.completion","created":1752854522,"model":"latest","choices":[{"index":0,"message":{"role":"assistant","content":"101 multiplied by 3 is 303.","refusal":null},"finish_reason":"stop"}],"usage":{"prompt_tokens":32,"completion_tokens":9,"total_tokens":135,"prompt_tokens_details":{"text_tokens":32,"audio_tokens":0,"image_tokens":0,"cached_tokens":6},"completion_tokens_details":{"reasoning_tokens":94,"audio_tokens":0,"accepted_prediction_tokens":0,"rejected_prediction_tokens":0},"num_sources_used":0},"system_fingerprint":"fp_3a7881249c"}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"422":{"description":"Unprocessable Entity. There are missing fields in the request body."}},"security":[{"bearerAuth":[]}]}},"/v1/chat/deferred-completion/{request_id}":{"get":{"tags":["v1"],"summary":"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 processing.","operationId":"handle_get_deferred_completion_request","parameters":[{"name":"request_id","in":"path","description":"The deferred request id returned by a previous deferred chat request.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"},"example":{"id":"335b92e4-afa5-48e7-b99c-b9a4eabc1c8e","object":"chat.completion","created":1743770624,"model":"latest","choices":[{"index":0,"message":{"role":"assistant","content":"101 multiplied by 3 is 303.","refusal":null},"finish_reason":"stop"}],"usage":{"prompt_tokens":31,"completion_tokens":11,"total_tokens":42,"prompt_tokens_details":{"text_tokens":31,"audio_tokens":0,"image_tokens":0,"cached_tokens":0},"completion_tokens_details":{"reasoning_tokens":0,"audio_tokens":0,"accepted_prediction_tokens":0,"rejected_prediction_tokens":0}},"system_fingerprint":"fp_156d35dcaa"}}}},"202":{"description":"Accepted. The request is processing, but haven't been completed. You can retry at a later time."},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"404":{"description":"Not found. No deferred completion could be found with the given request_id."}},"security":[{"bearerAuth":[]}]}},"/v1/complete":{"post":{"tags":["v1"],"summary":"(Legacy - Not supported by reasoning models) Create a text completion response. This endpoint is compatible with the Anthropic API.","operationId":"handle_generic_complete_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteRequest"},"example":{"model":"grok-3","max_tokens_to_sample":8,"temperature":0.1,"prompt":"\n\nHuman: Hello, how are you?\n\nAssistant:"}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"},"example":{"type":"completion","id":"982044c5-760c-4c8d-8936-f906b5cedc26","completion":" Hey there! I'm doing great, thanks","stop_reason":"max_tokens","model":"grok-3"}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"422":{"description":"Unprocessable Entity. There are missing fields in the request body."}},"security":[{"bearerAuth":[]}]}},"/v1/completions":{"post":{"tags":["v1"],"summary":"(Legacy - Not supported by reasoning models) Create a text completion response for a given prompt. Replaced by /v1/chat/completions.","operationId":"handle_sample_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleRequest"},"example":{"prompt":"1, 2, 3, 4, ","model":"grok-3","max_tokens":3}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleResponse"},"example":{"id":"873492b3-6144-4279-ac2e-2c45242c5ce6","object":"text_completion","created":1743771779,"model":"grok-3","choices":[{"index":0,"text":"5, ","finish_reason":"length"}],"usage":{"prompt_tokens":12,"completion_tokens":3,"total_tokens":15,"prompt_tokens_details":{"text_tokens":12,"audio_tokens":0,"image_tokens":0,"cached_tokens":0},"completion_tokens_details":{"reasoning_tokens":0,"audio_tokens":0,"accepted_prediction_tokens":0,"rejected_prediction_tokens":0}},"system_fingerprint":"fp_156d35dcaa"}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"422":{"description":"Unprocessable Entity. There are missing fields in the request body."}},"security":[{"bearerAuth":[]}]}},"/v1/documents/search":{"post":{"tags":["v1"],"summary":"Search for content related to the query within the given collections.","operationId":"handle_document_search_request_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"},"example":{"query":"What is the revenue in the last quarter?","source":{"collection_ids":["collection_80100614-300c-4609-959b-a138fa90f542"]},"filter":"document_type = \"financial_report\" AND year > 2020"}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"},"example":{"matches":[{"file_id":"file_ac3c5728-7399-41fc-bd62-0fef0042de9c","chunk_id":"0199717c-511b-7a80-bab3-dfe9a27f82ab","chunk_content":", deferred revenue related to such customer payments amounted to $2.10 billion and $1.77 billion, respectively, mainly due to contractual payment terms. Revenue recognized from the deferred revenue balances as of December 31, 2024 and 2023 was $944 million and $873 million for the six months ended June 30, 2025 and 2024, respectively. We have elected the practical expedient to omit disclosure of the amount of the transaction price allocated to remaining performance obligations for contracts with an original expected contract length of one year or less. As of June 30, 2025, total transaction price allocated to performance obligations that were unsatisfied or partially unsatisfied for contracts with an original expected length of more than one year was $10.38 billion. Of this amount, we expect to recognize $5.47 billion in the next 12 months and the rest over the remaining performance obligation period. Changes in government and economic incentives or tariffs may impact the transaction price or our ability to e","score":1.1447691,"collection_ids":["collection_80100614-300c-4609-959b-a138fa90f542"]}]}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."}},"security":[{"bearerAuth":[]}]}},"/v1/embedding-models":{"get":{"tags":["v1"],"summary":"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).","operationId":"handle_embedding_models_list_request","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEmbeddingModelsResponse"},"example":{"models":[{"id":"v1","fingerprint":"fp_df37966059","created":1725148800,"object":"model","owned_by":"xai","version":"0.1.0","input_modalities":["text"],"prompt_text_token_price":100,"prompt_image_token_price":0,"aliases":[]}]}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."}},"security":[{"bearerAuth":[]}]}},"/v1/embedding-models/{model_id}":{"get":{"tags":["v1"],"summary":"Get full information about an embedding model with its model_id.","operationId":"handle_embedding_model_get_request","parameters":[{"name":"model_id","in":"path","description":"ID of the model to get.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingModel"},"example":{"id":"v1","created":1725148800,"object":"model","owned_by":"xai","version":"0.1.0","input_modalities":["text"],"prompt_text_token_price":10,"prompt_image_token_price":0,"aliases":[]}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"404":{"description":"Model not found"}},"security":[{"bearerAuth":[]}]}},"/v1/embeddings":{"post":{"tags":["v1"],"summary":"Create an embedding vector representation corresponding to the input text. This is the endpoint for making requests to embedding models.","operationId":"handle_embedding_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingRequest"},"example":"{\n \"input\": [\"This is an example content to embed...\"],\n \"model\": \"v1\",\n \"encoding_format\": \"float\"\n }"}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingResponse"},"example":{"object":"list","model":"v1","data":[{"index":0,"embedding":[0.01567895,0.063257694,0.045925662],"object":"embedding"}],"usage":{"prompt_tokens":1,"total_tokens":1}}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"422":{"description":"Unprocessable Entity. There are missing fields in the request body."}},"security":[{"bearerAuth":[]}]}},"/v1/files":{"get":{"tags":["v1"],"summary":"List files owned by the authenticated team, paginated. The response\nalways returns a `pagination_token`; pass it back as a query parameter\nto fetch the next page. The end of the list is reached when the\nreturned `data` array is shorter than `limit`.","operationId":"handle_list_files_request","parameters":[{"name":"limit","in":"query","description":"The maximum number of objects to be returned in a single response.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"order","in":"query","description":"The ordering to sort the returned files. Use `asc` for ascending and `desc` for descending order.","required":false,"schema":{"type":"string"}},{"name":"sort_by","in":"query","description":"The field to sort by. Valid options: `created_at`, `filename`, `size`. Defaults to `created_at`.","required":false,"schema":{"type":"string"}},{"name":"pagination_token","in":"query","description":"The pagination token returned by the previous list files request.","required":false,"schema":{"type":"string"}},{"name":"after","in":"query","description":"Only included for compatibility. Use `pagination_token` instead.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListFilesResponse"},"example":{"data":[{"id":"file_a128090d-f0c9-4873-bd84-e499777e7417","object":"file","bytes":12345,"created_at":1762345678,"expires_at":null,"filename":"document.pdf","purpose":""}],"pagination_token":"file_a128090d-f0c9-4873-bd84-e499777e7417"}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["v1"],"summary":"Upload a file to xAI's storage. Returns the file's metadata. Files can\nbe referenced by ID anywhere a `file_id` is accepted (e.g. chat\nattachments). Maximum file size: 50 MB. Files are kept until you\ndelete them, or until `expires_after` elapses if set at upload time.","operationId":"handle_upload_file_request","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadFileMultipartRequest"}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"},"example":{"id":"file_a128090d-f0c9-4873-bd84-e499777e7417","object":"file","bytes":12345,"created_at":1762345678,"expires_at":1762432078,"filename":"document.pdf","purpose":""}}}},"400":{"description":"Bad request. Common causes: `expires_after` outside [3600, 2592000], `expires_after` field appearing after `file` in the multipart body, missing or unnamed `file` part, invalid filename."},"413":{"description":"Payload too large -- file exceeds 50 MB."}},"security":[{"bearerAuth":[]}]}},"/v1/files/{file_id}":{"get":{"tags":["v1"],"summary":"Retrieve metadata for a single file by ID. Errors with 404 if the file\ndoesn't exist, has been deleted, or has passed its `expires_at`.","operationId":"handle_retrieve_file_request","parameters":[{"name":"file_id","in":"path","description":"The file's `id` returned by upload or list.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"404":{"description":"File not found, deleted, or expired."}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["v1"],"summary":"Delete a file by ID. After this returns, the file no longer appears in\n`GET /v1/files`, content download returns 404, and the ID can no longer\nbe referenced in chat attachments.","operationId":"handle_delete_file_request","parameters":[{"name":"file_id","in":"path","description":"The file's `id` to delete.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteFileResponse"},"example":{"id":"file_a128090d-f0c9-4873-bd84-e499777e7417","deleted":true}}}},"404":{"description":"File not found or already deleted."}},"security":[{"bearerAuth":[]}]}},"/v1/files/{file_id}/content":{"get":{"tags":["v1"],"summary":"Download the contents of a file as a stream of raw bytes. The response\n`Content-Type` is `application/octet-stream`. Use this for the binary\npayload; use `GET /v1/files/{file_id}` for metadata only.","operationId":"handle_download_file_content_request","parameters":[{"name":"file_id","in":"path","description":"The file's `id` to download.","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","description":"Format of the downloaded content.","required":false,"schema":{"$ref":"#/components/schemas/ContentFormat"}}],"responses":{"200":{"description":"Success -- raw file bytes streamed in chunks.","content":{"application/octet-stream":{"schema":{"type":"string"}}}},"404":{"description":"File not found, deleted, or expired."}},"security":[{"bearerAuth":[]}]}},"/v1/image-generation-models":{"get":{"tags":["v1"],"summary":"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).","operationId":"handle_image_generation_models_list_request","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListImageGenerationModelsResponse"},"example":{"models":[{"id":"grok-imagine-image","fingerprint":"fp_ca78641a52","max_prompt_length":1024,"created":1738961600,"object":"model","owned_by":"xai","version":"1.0.0","prompt_text_token_price":100000,"prompt_image_token_price":100000,"generated_image_token_price":100000,"aliases":[]}]}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."}},"security":[{"bearerAuth":[]}]}},"/v1/image-generation-models/{model_id}":{"get":{"tags":["v1"],"summary":"Get full information about an image generation model with its model_id.","operationId":"handle_image_generation_model_get_request","parameters":[{"name":"model_id","in":"path","description":"ID of the model to get.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationModel"},"example":{"id":"grok-imagine-image","fingerprint":"fp_ca78641a52","max_prompt_length":1024,"created":1737961600,"object":"model","owned_by":"xai","version":"1.0.0","prompt_text_token_price":100000,"prompt_image_token_price":100000,"generated_image_token_price":100000,"aliases":[]}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"404":{"description":"Model not found"}},"security":[{"bearerAuth":[]}]}},"/v1/images/edits":{"post":{"tags":["v1"],"summary":"Edit an image based on a prompt. This is the endpoint for making edit requests to image generation models.","operationId":"handle_edit_image_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditImageRequest"},"example":{"prompt":"Add a hat to this cat.","image":{"url":"..."},"model":"grok-imagine-image"}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratedImageResponse"},"example":{"data":[{"url":"..."}]}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"422":{"description":"Unprocessable Entity. There are missing fields in the request body."}},"security":[{"bearerAuth":[]}]}},"/v1/images/generations":{"post":{"tags":["v1"],"summary":"Generate an image based on a prompt. This is the endpoint for making generation requests to image generation models.","operationId":"handle_generate_image_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateImageRequest"},"example":{"prompt":"A cat in a tree","model":"grok-imagine-image","response_format":"url","n":2}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratedImageResponse"},"example":{"data":[{"url":"..."},{"url":"..."}]}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"422":{"description":"Unprocessable Entity. There are missing fields in the request body."}},"security":[{"bearerAuth":[]}]}},"/v1/language-models":{"get":{"tags":["v1"],"summary":"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 alias(es).","operationId":"handle_language_models_list_request","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListLanguageModelsResponse"},"example":{"models":[{"id":"grok-3","fingerprint":"fp_898ae9f31c","created":1743724800,"object":"model","owned_by":"xai","version":"1.0","input_modalities":["text"],"output_modalities":["text"],"prompt_text_token_price":30000,"cached_prompt_text_token_price":7500,"prompt_image_token_price":0,"completion_text_token_price":150000,"search_price":250000000,"aliases":["grok-3-latest","grok-3-beta"]},{"id":"grok-3-mini","fingerprint":"fp_6a09108ff5","created":1743724800,"object":"model","owned_by":"xai","version":"1.0","input_modalities":["text"],"output_modalities":["text"],"prompt_text_token_price":3000,"cached_prompt_text_token_price":750,"prompt_image_token_price":0,"completion_text_token_price":5000,"search_price":250000000,"aliases":["grok-3-mini-latest","grok-3-mini-beta"]},{"id":"grok-2-vision-1212","fingerprint":"fp_daba7546e5","created":1733961600,"object":"model","owned_by":"xai","version":"0.1.0","input_modalities":["text","image"],"output_modalities":["text"],"prompt_text_token_price":20000,"prompt_image_token_price":20000,"completion_text_token_price":100000,"aliases":[]}]}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."}},"security":[{"bearerAuth":[]}]}},"/v1/language-models/{model_id}":{"get":{"tags":["v1"],"summary":"Get full information about a chat or image understanding model with its model_id.","operationId":"handle_language_model_get_request","parameters":[{"name":"model_id","in":"path","description":"ID of the model to get.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LanguageModel"},"example":{"id":"latest","fingerprint":"fp_156d35dcaa","created":1743724800,"object":"model","owned_by":"xai","version":"1.0.0","input_modalities":["text"],"output_modalities":["text"],"prompt_text_token_price":20000,"cached_prompt_text_token_price":0,"prompt_image_token_price":0,"completion_text_token_price":100000,"aliases":["grok-4","grok-4-latest"]}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"404":{"description":"Model not found"}},"security":[{"bearerAuth":[]}]}},"/v1/messages":{"post":{"tags":["v1"],"summary":"Create a messages response. This endpoint is compatible with the Anthropic API.","operationId":"handle_generic_messages_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageRequest"},"example":{"model":"latest","max_tokens":32,"messages":[{"role":"user","content":"Hello, world"}]}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"},"example":{"id":"4f224bfb-9d53-4c82-b40a-b7cd80831ec2","type":"message","role":"assistant","content":[{"type":"text","text":"Hello there! \"Hello, world\" is a classic, isn't it? Whether you're just saying hi or channeling your inner coder, I'm happy to greet you back"}],"model":"latest","stop_reason":"max_tokens","stop_sequence":null,"usage":{"input_tokens":9,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":32}}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"422":{"description":"Unprocessable Entity. There are missing fields in the request body."}},"security":[{"bearerAuth":[]}]}},"/v1/models":{"get":{"tags":["v1"],"summary":"List all models available to the authenticating API key with minimalized information, including model names (ID), creation times, etc.","operationId":"handle_models_list_request","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListModelsResponse"},"example":{"data":[{"id":"grok-4-0709","created":1752019200,"object":"model","owned_by":"xai"},{"id":"grok-code-fast-1","created":1755993600,"object":"model","owned_by":"xai"},{"id":"grok-3","created":1743724800,"object":"model","owned_by":"xai"},{"id":"grok-3-mini","created":1743724800,"object":"model","owned_by":"xai"},{"id":"grok-2-image-1212","created":1736726400,"object":"model","owned_by":"xai"},{"id":"grok-2-vision-1212","created":1733961600,"object":"model","owned_by":"xai"}],"object":"list"}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."}},"security":[{"bearerAuth":[]}]}},"/v1/models/{model_id}":{"get":{"tags":["v1"],"summary":"Get minimalized information about a model with its model_id.","operationId":"handle_model_get_request","parameters":[{"name":"model_id","in":"path","description":"ID of the model to get.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"},"example":{"id":"latest","created":1743724800,"object":"model","owned_by":"xai"}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"404":{"description":"Model not found"}},"security":[{"bearerAuth":[]}]}},"/v1/responses":{"post":{"tags":["v1"],"summary":"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 stored for 30 days and then permanently deleted.","operationId":"handle_generic_model_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelRequest"},"example":{"input":[{"role":"system","content":"You are a helpful assistant that can answer questions and help with tasks."},{"role":"user","content":"What is 101*3?"}],"model":"latest"}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelResponse"},"example":{"created_at":1754475266,"id":"ad5663da-63e6-86c6-e0be-ff15effa8357","max_output_tokens":null,"model":"latest","object":"response","output":[{"content":[{"type":"output_text","text":"101 multiplied by 3 is 303.","logprobs":null,"annotations":[]}],"id":"msg_ad5663da-63e6-86c6-e0be-ff15effa8357","role":"assistant","type":"message","status":"completed"}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":null,"temperature":null,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":null,"usage":{"input_tokens":32,"input_tokens_details":{"cached_tokens":8},"output_tokens":9,"output_tokens_details":{"reasoning_tokens":110},"total_tokens":151,"num_sources_used":0,"num_server_side_tools_used":0},"user":null,"incomplete_details":null,"status":"completed","store":true}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"422":{"description":"Unprocessable Entity. There are missing fields in the request body."}},"security":[{"bearerAuth":[]}]}},"/v1/responses/{response_id}":{"get":{"tags":["v1"],"summary":"Retrieve a previously generated response.","operationId":"handle_get_stored_completion_request","parameters":[{"name":"response_id","in":"path","description":"The response id returned by a previous create response request.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelResponse"},"example":{"created_at":1754475266,"id":"ad5663da-63e6-86c6-e0be-ff15effa8357","max_output_tokens":null,"model":"latest","object":"response","output":[{"content":[{"type":"output_text","text":"101 multiplied by 3 is 303.","logprobs":null,"annotations":[]}],"id":"msg_ad5663da-63e6-86c6-e0be-ff15effa8357","role":"assistant","type":"message","status":"completed"},{"id":"","summary":[{"text":"First, the user asked: \"What is 101*3?\"\n\nThis is a simple multiplication: 101 multiplied by 3.\n\nCalculating: 100 * 3 = 300, and 1 * 3 = 3, so 300 + 3 = 303.\n\nI should respond helpfully and directly, as per my system prompt: \"You are a helpful assistant that can answer questions and help with tasks.\"\n\nKeep the response concise and accurate. No need for extra fluff unless it adds value.\n\nFinal answer: 303.","type":"summary_text"}],"type":"reasoning","status":"completed"}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":null,"temperature":null,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":null,"usage":{"prompt_tokens":32,"completion_tokens":9,"total_tokens":151,"prompt_tokens_details":{"text_tokens":32,"audio_tokens":0,"image_tokens":0,"cached_tokens":8},"completion_tokens_details":{"reasoning_tokens":110,"audio_tokens":0,"accepted_prediction_tokens":0,"rejected_prediction_tokens":0},"num_sources_used":0},"user":null,"incomplete_details":null,"status":"completed","store":true}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"404":{"description":"Not found. No responses could be found with the given response_id."}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["v1"],"summary":"Delete a previously generated response.","operationId":"handle_delete_stored_completion_request","parameters":[{"name":"response_id","in":"path","description":"The response id returned by a previous create response request.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteStoredCompletionResponse"},"example":{"id":"ad5663da-63e6-86c6-e0be-ff15effa8357","object":"response","deleted":true}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"404":{"description":"Not found. No responses could be found with the given response_id."}},"security":[{"bearerAuth":[]}]}},"/v1/tokenize-text":{"post":{"tags":["v1"],"summary":"Tokenize text with the specified model","operationId":"handle_tokenize_text_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenizeRequest"},"example":{"text":"Hello world!","model":"latest"}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenizeResponse"},"example":{"token_ids":[{"token_id":13902,"string_token":"Hello","token_bytes":[72,101,108,108,111]},{"token_id":1749,"string_token":" world","token_bytes":[32,119,111,114,108,100]},{"token_id":161,"string_token":"!","token_bytes":[33]}]}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."}},"security":[{"bearerAuth":[]}]}},"/v1/video-generation-models":{"get":{"tags":["v1"],"summary":"List all video generation models available to the authenticating API key with full information.","operationId":"handle_video_generation_models_list_request","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListVideoGenerationModelsResponse"},"example":{"models":[{"id":"grok-imagine-video","fingerprint":"fp_898ae9f31c","created":1743724800,"object":"model","owned_by":"xai","version":"1.0.0","input_modalities":["text","image"],"output_modalities":["video"],"aliases":[]}]}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."}},"security":[{"bearerAuth":[]}]}},"/v1/video-generation-models/{model_id}":{"get":{"tags":["v1"],"summary":"Get full information about a video generation model with its model_id.","operationId":"handle_video_generation_model_get_request","parameters":[{"name":"model_id","in":"path","description":"ID of the model to get.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoGenerationModel"},"example":{"id":"grok-imagine-video","fingerprint":"fp_898ae9f31c","created":1743724800,"object":"model","owned_by":"xai","version":"1.0","input_modalities":["text","image"],"output_modalities":["video"],"aliases":[]}}}},"400":{"description":"Bad request. The request is invalid or an invalid API key is provided."},"404":{"description":"Model not found"}},"security":[{"bearerAuth":[]}]}},"/v1/videos/edits":{"post":{"tags":["v1"],"summary":"Edit a video based on a prompt.\nThis is an asynchronous operation that returns a request_id for polling.","operationId":"handle_edit_video_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditVideoRequest"},"example":{"prompt":"Add snow to the scene","video":{"url":"https://example.com/video.mp4"},"model":"grok-imagine-video"}}},"required":true},"responses":{"200":{"description":"Vi
# --- truncated at 32 KB (170 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xai/refs/heads/main/openapi/xai-openapi.json