{"openapi":"3.1.0","info":{"title":"Grok via Locus MPP","version":"1.0.0","description":"xAI models — chat, web/X search, code execution, image generation/editing, and text-to-speech.","contact":{"email":"api@paywithlocus.com"},"x-guidance":"Use the documented POST operations for Grok. Send JSON matching each requestBody schema. Unpaid public x402 requests return an x402 v2 payment challenge; retry the same body with PAYMENT-SIGNATURE and the returned x-locus-request-id."},"x-agentcash-guidance":{"llmsTxtUrl":"https://paywithlocus.com/mpp/grok.md"},"x-service-info":{"categories":["ai"],"docs":{"homepage":"https://x.ai","apiReference":"https://docs.x.ai","llms":"https://paywithlocus.com/mpp/grok.md"}},"paths":{"/grok/models":{"post":{"operationId":"grok_models","summary":"List Models","description":"List the xAI models available to the configured upstream account, including pricing metadata.","tags":["AI / LLM"],"security":[],"x-payment-info":{"intent":"charge","method":"tempo","amount":"0","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Free"},"parameters":[{"name":"x-locus-request-id","in":"header","required":false,"description":"UUID returned by the initial 402. Echo it on the paid retry and later recovery attempts.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":true},"example":{}}}},"responses":{"200":{"description":"Successful response with PAYMENT-RESPONSE and durable request receipt"},"202":{"description":"The supplied request ID is already in progress"},"400":{"description":"Invalid request"},"402":{"description":"Payment Required"},"409":{"description":"Request ID conflict or terminal failed request"}}}},"/grok/chat":{"post":{"operationId":"grok_chat","summary":"Chat Completions","description":"Generate text with Grok models. OpenAI-compatible format with support for text, vision, and function calling.","tags":["AI / LLM"],"security":[],"x-payment-info":{"intent":"charge","method":"tempo","amount":null,"currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Usage-based; the 402 challenge advertises the authorization maximum"},"parameters":[{"name":"x-locus-request-id","in":"header","required":false,"description":"UUID returned by the initial 402. Echo it on the paid retry and later recovery attempts.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Metered x402 model ID: 'grok-4.6', 'grok-4.5', 'grok-4.5-latest', 'grok-4.3', 'grok-4.20-0309-reasoning', or 'grok-4.20-0309-non-reasoning'. Multi-agent is excluded because xAI does not support an output-token cap for it."},"messages":{"description":"Conversation messages. Each: { role: \"system\"|\"user\"|\"assistant\", content: \"text\" } or multimodal: { role: \"user\", content: [{ type: \"text\", text: \"...\" }, { type: \"image_url\", image_url: { url: \"...\" } }] }","type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"},"image_url":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":true}},"required":["type"],"additionalProperties":true}},{"type":"null"}]},"name":{"type":"string"},"tool_call_id":{"type":"string"},"tool_calls":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["role"],"additionalProperties":true}},"temperature":{"type":"number","description":"Sampling temperature (0.0–2.0, default 1.0)"},"top_p":{"type":"number","description":"Nucleus sampling threshold (0.0–1.0)"},"max_tokens":{"type":"number","description":"Maximum output tokens. Required to bound metered x402 authorization."},"stop":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Stop sequences"},"frequency_penalty":{"type":"number","description":"Frequency penalty (-2.0 to 2.0, default 0)"},"presence_penalty":{"type":"number","description":"Presence penalty (-2.0 to 2.0, default 0)"},"n":{"type":"number","description":"Number of completions to generate (default 1)"},"stream":{"type":"boolean","description":"Stream partial results as SSE (text/event-stream). Recommended for reasoning models that exceed the edge buffered-response timeout."}},"required":["model","messages","max_tokens"],"additionalProperties":true},"example":{"model":"grok-4.6","messages":[{"role":"user","content":"Reply with exactly the word PONG."}],"max_tokens":128}}}},"responses":{"200":{"description":"Successful response with PAYMENT-RESPONSE and durable request receipt"},"202":{"description":"The supplied request ID is already in progress"},"400":{"description":"Invalid request"},"402":{"description":"Payment Required"},"409":{"description":"Request ID conflict or terminal failed request"}}}},"/grok/image-generate":{"post":{"operationId":"grok_image_generate","summary":"Image Generation","description":"Generate images from text prompts using Grok Imagine models.","tags":["AI / LLM"],"security":[],"x-payment-info":{"intent":"charge","method":"tempo","amount":null,"currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"$0.02–$0.08 per image"},"parameters":[{"name":"x-locus-request-id","in":"header","required":false,"description":"UUID returned by the initial 402. Echo it on the paid retry and later recovery attempts.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"Text description of the image to generate"},"model":{"type":"string","description":"Metered x402 image model ID: 'grok-imagine-image-2.0', 'grok-imagine-image', or 'grok-imagine-image-quality'"},"n":{"type":"number","description":"Number of images to generate (default 1)"},"aspect_ratio":{"type":"string","description":"Aspect ratio (e.g. '1:1', '16:9', '9:16', '4:3', '3:2', 'auto')"},"resolution":{"type":"string","description":"Output resolution: '1k' (default) or '2k'"},"response_format":{"type":"string","description":"Response format: 'url' (default, temporary hosted URL) or 'b64_json' (image bytes retained in the customer response artifact)."}},"required":["prompt","model"],"additionalProperties":true},"example":{"prompt":"A single purple compass rose centered on a plain white background","model":"grok-imagine-image-2.0","n":1,"resolution":"1k","response_format":"b64_json"}}}},"responses":{"200":{"description":"Successful response with PAYMENT-RESPONSE and durable request receipt"},"202":{"description":"The supplied request ID is already in progress"},"400":{"description":"Invalid request"},"402":{"description":"Payment Required"},"409":{"description":"Request ID conflict or terminal failed request"}}}},"/grok/image-edit":{"post":{"operationId":"grok_image_edit","summary":"Image Editing","description":"Edit existing images with natural language. Provide a source image and describe the changes.","tags":["AI / LLM"],"security":[],"x-payment-info":{"intent":"charge","method":"tempo","amount":null,"currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"$0.02–$0.08 per image"},"parameters":[{"name":"x-locus-request-id","in":"header","required":false,"description":"UUID returned by the initial 402. Echo it on the paid retry and later recovery attempts.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"Text description of the edits to apply (e.g. \"Add a hat to the person\")"},"image":{"description":"Source image: { url: \"https://...\" } or { url: \"data:image/jpeg;base64,...\" }","type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":true},"model":{"type":"string","description":"Metered x402 image model ID: 'grok-imagine-image-2.0', 'grok-imagine-image', or 'grok-imagine-image-quality'"},"n":{"type":"number","description":"Number of edited images to generate (default 1)"},"resolution":{"type":"string","description":"Output resolution: '1k' (default) or '2k'"},"response_format":{"type":"string","description":"Response format: 'url' (default, temporary hosted URL) or 'b64_json' (image bytes retained in the customer response artifact)."}},"required":["prompt","image","model"],"additionalProperties":true},"example":{"prompt":"Add a subtle purple border","image":{"url":"<png data url: supply valid media bytes>"},"model":"grok-imagine-image","n":1,"resolution":"1k","response_format":"b64_json"}}}},"responses":{"200":{"description":"Successful response with PAYMENT-RESPONSE and durable request receipt"},"202":{"description":"The supplied request ID is already in progress"},"400":{"description":"Invalid request"},"402":{"description":"Payment Required"},"409":{"description":"Request ID conflict or terminal failed request"}}}},"/grok/web-search":{"post":{"operationId":"grok_web_search","summary":"Chat with Web Search","description":"Generate text with current Grok models grounded in live web search results. Uses the xAI Responses API with automatic web search.","tags":["AI / LLM"],"security":[],"x-payment-info":{"intent":"charge","method":"tempo","amount":null,"currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Usage-based; the 402 challenge advertises the authorization maximum"},"parameters":[{"name":"x-locus-request-id","in":"header","required":false,"description":"UUID returned by the initial 402. Echo it on the paid retry and later recovery attempts.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Metered x402 model ID: 'grok-4.6', 'grok-4.5', 'grok-4.5-latest', 'grok-4.3', 'grok-4.20-0309-reasoning', or 'grok-4.20-0309-non-reasoning'. Multi-agent is excluded because xAI does not support an output-token cap for it."},"messages":{"description":"Conversation messages. Each: { role: \"system\"|\"user\"|\"assistant\", content: \"text\" }","type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"},"image_url":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":true}},"required":["type"],"additionalProperties":true}},{"type":"null"}]},"name":{"type":"string"},"tool_call_id":{"type":"string"},"tool_calls":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["role"],"additionalProperties":true}},"search_parameters":{"type":"object","additionalProperties":true,"description":"Web search filters: { allowed_domains: string[] (max 5), excluded_domains: string[] (max 5) }"},"temperature":{"type":"number","description":"Sampling temperature (0.0–2.0, default 1.0)"},"max_tokens":{"type":"number","description":"Maximum output tokens per model turn. Required for metered x402."},"max_turns":{"type":"number","description":"Maximum agentic tool turns (1–10, default 3). Each turn may run several server tool calls in parallel. Enforced upstream and priced into the quote per turn."},"max_tool_calls":{"type":"number","description":"Required for metered x402 (1–10). Sets the metered spend bound and is applied upstream as the max_turns cap; when both are sent the lower value wins."}},"required":["model","messages","max_tokens","max_tool_calls"],"additionalProperties":true},"example":{"model":"grok-4.6","messages":[{"role":"user","content":"What is 2+2? Reply with the result."}],"max_tokens":256,"max_tool_calls":1}}}},"responses":{"200":{"description":"Successful response with PAYMENT-RESPONSE and durable request receipt"},"202":{"description":"The supplied request ID is already in progress"},"400":{"description":"Invalid request"},"402":{"description":"Payment Required"},"409":{"description":"Request ID conflict or terminal failed request"}}}},"/grok/x-search":{"post":{"operationId":"grok_x_search","summary":"Chat with X Search","description":"Generate text with current Grok models grounded in live X (Twitter) search results. Uses the xAI Responses API with X search.","tags":["AI / LLM"],"security":[],"x-payment-info":{"intent":"charge","method":"tempo","amount":null,"currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Usage-based; the 402 challenge advertises the authorization maximum"},"parameters":[{"name":"x-locus-request-id","in":"header","required":false,"description":"UUID returned by the initial 402. Echo it on the paid retry and later recovery attempts.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Metered x402 model ID: 'grok-4.6', 'grok-4.5', 'grok-4.5-latest', 'grok-4.3', 'grok-4.20-0309-reasoning', or 'grok-4.20-0309-non-reasoning'. Multi-agent is excluded because xAI does not support an output-token cap for it."},"messages":{"description":"Conversation messages. Each: { role: \"system\"|\"user\"|\"assistant\", content: \"text\" }","type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"},"image_url":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":true}},"required":["type"],"additionalProperties":true}},{"type":"null"}]},"name":{"type":"string"},"tool_call_id":{"type":"string"},"tool_calls":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["role"],"additionalProperties":true}},"temperature":{"type":"number","description":"Sampling temperature (0.0–2.0, default 1.0)"},"max_tokens":{"type":"number","description":"Maximum output tokens per model turn. Required for metered x402."},"max_turns":{"type":"number","description":"Maximum agentic tool turns (1–10, default 3). Each turn may run several server tool calls in parallel. Enforced upstream and priced into the quote per turn."},"max_tool_calls":{"type":"number","description":"Required for metered x402 (1–10). Sets the metered spend bound and is applied upstream as the max_turns cap; when both are sent the lower value wins."}},"required":["model","messages","max_tokens","max_tool_calls"],"additionalProperties":true},"example":{"model":"grok-4.6","messages":[{"role":"user","content":"What is 2+2? Reply with the result."}],"max_tokens":256,"max_tool_calls":1}}}},"responses":{"200":{"description":"Successful response with PAYMENT-RESPONSE and durable request receipt"},"202":{"description":"The supplied request ID is already in progress"},"400":{"description":"Invalid request"},"402":{"description":"Payment Required"},"409":{"description":"Request ID conflict or terminal failed request"}}}},"/grok/code-execution":{"post":{"operationId":"grok_code_execution","summary":"Chat with Code Execution","description":"Generate text with current Grok models that can write and execute code in a sandboxed environment. Uses the xAI Responses API with code execution.","tags":["AI / LLM"],"security":[],"x-payment-info":{"intent":"charge","method":"tempo","amount":null,"currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Usage-based; the 402 challenge advertises the authorization maximum"},"parameters":[{"name":"x-locus-request-id","in":"header","required":false,"description":"UUID returned by the initial 402. Echo it on the paid retry and later recovery attempts.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Metered x402 model ID: 'grok-4.6', 'grok-4.5', 'grok-4.5-latest', 'grok-4.3', 'grok-4.20-0309-reasoning', or 'grok-4.20-0309-non-reasoning'. Multi-agent is excluded because xAI does not support an output-token cap for it."},"messages":{"description":"Conversation messages. Each: { role: \"system\"|\"user\"|\"assistant\", content: \"text\" }","type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"},"image_url":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":true}},"required":["type"],"additionalProperties":true}},{"type":"null"}]},"name":{"type":"string"},"tool_call_id":{"type":"string"},"tool_calls":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["role"],"additionalProperties":true}},"tools":{"type":"array","items":{},"description":"Additional tools to enable alongside code execution."},"temperature":{"type":"number","description":"Sampling temperature (0.0–2.0, default 1.0)"},"max_tokens":{"type":"number","description":"Maximum output tokens per model turn. Required for metered x402."},"max_turns":{"type":"number","description":"Maximum agentic tool turns (1–10, default 3). Each turn may run several server tool calls in parallel. Enforced upstream and priced into the quote per turn."},"max_tool_calls":{"type":"number","description":"Required for metered x402 (1–10). Sets the metered spend bound and is applied upstream as the max_turns cap; when both are sent the lower value wins."}},"required":["model","messages","max_tokens","max_tool_calls"],"additionalProperties":true},"example":{"model":"grok-4.6","messages":[{"role":"user","content":"What is 2+2? Reply with the result."}],"max_tokens":256,"max_tool_calls":1}}}},"responses":{"200":{"description":"Successful response with PAYMENT-RESPONSE and durable request receipt"},"202":{"description":"The supplied request ID is already in progress"},"400":{"description":"Invalid request"},"402":{"description":"Payment Required"},"409":{"description":"Request ID conflict or terminal failed request"}}}},"/grok/tts":{"post":{"operationId":"grok_tts","summary":"Text-to-Speech","description":"Convert text to spoken audio. Supports multiple voices, speech tags for expressive delivery, and various output formats.","tags":["AI / LLM"],"security":[],"x-payment-info":{"intent":"charge","method":"tempo","amount":null,"currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"~$0.005 per 1,000 characters"},"parameters":[{"name":"x-locus-request-id","in":"header","required":false,"description":"UUID returned by the initial 402. Echo it on the paid retry and later recovery attempts.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"Text to convert to speech (max 15,000 characters). Supports inline speech tags like [pause], [laugh], <whisper>text</whisper>."},"language":{"type":"string","description":"BCP-47 language code (e.g. 'en', 'zh', 'fr', 'de', 'ja') or 'auto' for detection"},"voice_id":{"type":"string","description":"Voice: 'eve' (energetic, default), 'ara' (warm), 'rex' (confident), 'sal' (smooth), 'leo' (authoritative)"},"output_format":{"type":"object","additionalProperties":true,"description":"Audio format config: { codec: 'mp3'|'wav'|'pcm'|'mulaw'|'alaw', sample_rate: 24000, bit_rate: 128000 }"}},"required":["text","language"],"additionalProperties":true},"example":{"text":"Hello from x402","language":"en"}}}},"responses":{"200":{"description":"Successful response with PAYMENT-RESPONSE and durable request receipt"},"202":{"description":"The supplied request ID is already in progress"},"400":{"description":"Invalid request"},"402":{"description":"Payment Required"},"409":{"description":"Request ID conflict or terminal failed request"}}}}}}