{"openapi":"3.1.0","info":{"title":"Cluster Protocol — Decentralized AI Inference Gateway","version":"1.0.0","description":"Pay-per-request AI inference API powered by 500+ models across multiple providers. Supports LLM chat completions, embeddings, image generation, audio transcription, text-to-speech, document reranking, and autonomous AI agents. Settlement via x402 micropayments in USDC on Base mainnet. Decentralized AI infrastructure for the open internet.","x-guidance":"## How to use Cluster Protocol API\n\nThis API provides AI inference services payable via the x402 protocol using USDC on Base mainnet.\n\n### Quick Start\n1. Send a POST request to any endpoint (e.g. /v1/chat/completions).\n2. You will receive HTTP 402 with payment instructions in the response headers.\n3. Sign a USDC authorization (EIP-3009, gasless) matching the required amount on Base (chain ID 8453).\n4. Resend the original request with the signed payment in the X-PAYMENT header.\n5. Receive your AI inference result.\n\n### Endpoints\n- POST /v1/chat/completions — LLM chat inference ($0.003/req). Body: { \"model\": \"llama-3.3-70b-instruct\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}] }\n- POST /v1/embeddings — Text embeddings ($0.0005/req). Body: { \"model\": \"text-embedding-3-small\", \"input\": \"text to embed\" }\n- POST /v1/images/generations — Image generation ($0.02/req). Body: { \"model\": \"flux-1-schnell\", \"prompt\": \"a cat\" }\n- POST /v1/audio/transcriptions — Speech-to-text ($0.006/req). Multipart form with audio file.\n- POST /v1/audio/speech — Text-to-speech ($0.015/req). Body: { \"model\": \"tts-1\", \"input\": \"Hello world\", \"voice\": \"alloy\" }\n- POST /v1/rerank — Document reranking ($0.001/req). Body: { \"model\": \"rerank-v1\", \"query\": \"search query\", \"documents\": [\"doc1\", \"doc2\"] }\n- POST /v1/agents/execute — Autonomous AI agent execution ($1.00/req). Body: { \"task\": \"Analyze market trends for AI infrastructure\" }\n\n### Models\nOver 40 models available. Specify a \"provider\" field to pin routing (e.g. \"venice\", \"groq\", \"phala\", \"redpill\", \"zerog\", \"together\", \"fireworks\", \"deepinfra\", \"sambanova\").\n\n### Alternative Auth\nIf you have a Cluster Protocol API key, include it as Authorization: Bearer <key> to bypass x402 payment (usage billed to your account balance)."},"tags":[{"name":"AI","description":"AI inference endpoints — chat completions, embeddings, image generation, audio, reranking"},{"name":"Agents","description":"Autonomous AI agents with multi-step reasoning and tool use"}],"x-discovery":{"ownershipProofs":[]},"servers":[{"url":"https://api.clusterprotocol.ai","description":"Production"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Cluster Protocol API key (sk-cluster-xxx). Use as alternative to x402 payment."},"x402":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"x402 payment proof. Signed USDC authorization on Base mainnet."}}},"paths":{"/v1/chat/completions":{"post":{"operationId":"chatCompletions","summary":"AI Chat Completion","tags":["AI"],"description":"Generate a chat completion using LLM models. Supports 40+ models across multiple providers. Optionally specify a provider for direct routing.","security":[{"x402":[]},{"bearerAuth":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003000"},"protocols":[{"x402":{}}]},"x-bazaar":{"discoverable":true,"schema":{"properties":{"input":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","description":"Model slug (e.g. 'llama-3.3-70b-instruct')"},"messages":{"type":"array","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"type":"string"}}}},"provider":{"type":"string","description":"Optional provider (e.g. 'venice', 'groq', 'phala', 'redpill', 'zerog')"},"stream":{"type":"boolean"},"temperature":{"type":"number","minimum":0,"maximum":2},"max_tokens":{"type":"integer","minimum":1}}},"output":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"}}},"finish_reason":{"type":"string"}}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","description":"Model slug (e.g. 'llama-3.3-70b-instruct', 'deepseek-r1', 'qwen-2.5-72b-instruct')"},"messages":{"type":"array","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"type":"string"}}}},"provider":{"type":"string","description":"Optional provider to pin routing (e.g. 'venice', 'groq', 'phala', 'redpill', 'zerog', 'together')"},"stream":{"type":"boolean","description":"Enable streaming response"},"temperature":{"type":"number","minimum":0,"maximum":2},"max_tokens":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"Chat completion response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["chat.completion"]},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"}}},"finish_reason":{"type":"string"}}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}}}}},"402":{"description":"Payment Required"}}}},"/v1/embeddings":{"post":{"operationId":"createEmbeddings","summary":"Text Embedding Generation","tags":["AI"],"description":"Generate vector embeddings for text input using embedding models.","security":[{"x402":[]},{"bearerAuth":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.000500"},"protocols":[{"x402":{}}]},"x-bazaar":{"discoverable":true,"schema":{"properties":{"input":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string","description":"Embedding model slug"},"input":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Text(s) to embed"}}},"output":{"type":"object","properties":{"object":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"embedding":{"type":"array","items":{"type":"number"}},"index":{"type":"integer"}}}},"model":{"type":"string"},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string","description":"Embedding model slug (e.g. 'text-embedding-3-small')"},"input":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Text or array of texts to embed"}}}}}},"responses":{"200":{"description":"Embedding response","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string"},"embedding":{"type":"array","items":{"type":"number"}},"index":{"type":"integer"}}}},"model":{"type":"string"},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}}}}},"402":{"description":"Payment Required"}}}},"/v1/images/generations":{"post":{"operationId":"generateImage","summary":"AI Image Generation","tags":["AI"],"description":"Generate images from text prompts using image models like FLUX and Stable Diffusion.","security":[{"x402":[]},{"bearerAuth":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}]},"x-bazaar":{"discoverable":true,"schema":{"properties":{"input":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string","description":"Image model slug"},"prompt":{"type":"string","description":"Text prompt describing the image"},"n":{"type":"integer","minimum":1,"maximum":4},"size":{"type":"string","description":"Image dimensions (e.g. '1024x1024')"}}},"output":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"b64_json":{"type":"string"}}}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string","description":"Image model slug"},"prompt":{"type":"string","description":"Text prompt describing the image"},"n":{"type":"integer","minimum":1,"maximum":4,"description":"Number of images to generate"},"size":{"type":"string","description":"Image dimensions (e.g. '1024x1024')"}}}}}},"responses":{"200":{"description":"Generated image(s)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"b64_json":{"type":"string"}}}}}}}}},"402":{"description":"Payment Required"}}}},"/v1/audio/transcriptions":{"post":{"operationId":"transcribeAudio","summary":"Audio Transcription (Speech-to-Text)","tags":["AI"],"description":"Transcribe audio files to text using Whisper-compatible models.","security":[{"x402":[]},{"bearerAuth":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.006000"},"protocols":[{"x402":{}}]},"x-bazaar":{"discoverable":true,"schema":{"properties":{"input":{"type":"object","required":["file","model"],"properties":{"file":{"type":"string","format":"binary","description":"Audio file"},"model":{"type":"string","description":"Transcription model (e.g. 'whisper-large-v3')"},"language":{"type":"string","description":"ISO 639-1 language code"}}},"output":{"type":"object","properties":{"text":{"type":"string","description":"Transcribed text"}}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","model"],"properties":{"file":{"type":"string","format":"binary","description":"Audio file to transcribe"},"model":{"type":"string","description":"Transcription model (e.g. 'whisper-large-v3')"},"language":{"type":"string","description":"ISO 639-1 language code"}}}}}},"responses":{"200":{"description":"Transcription result","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}}},"402":{"description":"Payment Required"}}}},"/v1/audio/speech":{"post":{"operationId":"textToSpeech","summary":"Text-to-Speech Synthesis","tags":["AI"],"description":"Convert text to natural-sounding speech audio.","security":[{"x402":[]},{"bearerAuth":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.015000"},"protocols":[{"x402":{}}]},"x-bazaar":{"discoverable":true,"schema":{"properties":{"input":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string","description":"TTS model slug"},"input":{"type":"string","description":"Text to synthesize"},"voice":{"type":"string","description":"Voice preset (e.g. 'alloy', 'nova')"},"speed":{"type":"number","minimum":0.25,"maximum":4}}},"output":{"type":"string","format":"binary","description":"Audio stream (audio/mpeg)"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string","description":"TTS model slug"},"input":{"type":"string","description":"Text to synthesize into speech"},"voice":{"type":"string","description":"Voice preset (e.g. 'alloy', 'nova')"},"speed":{"type":"number","minimum":0.25,"maximum":4}}}}}},"responses":{"200":{"description":"Audio stream","content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}}}},"402":{"description":"Payment Required"}}}},"/v1/rerank":{"post":{"operationId":"rerankDocuments","summary":"Document Reranking","tags":["AI"],"description":"Rerank a list of documents by relevance to a query using cross-encoder models.","security":[{"x402":[]},{"bearerAuth":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001000"},"protocols":[{"x402":{}}]},"x-bazaar":{"discoverable":true,"schema":{"properties":{"input":{"type":"object","required":["model","query","documents"],"properties":{"model":{"type":"string","description":"Reranker model slug"},"query":{"type":"string","description":"The search query"},"documents":{"type":"array","items":{"type":"string"},"description":"Documents to rerank"},"top_n":{"type":"integer","description":"Number of top results"}}},"output":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"relevance_score":{"type":"number"},"document":{"type":"string"}}}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","query","documents"],"properties":{"model":{"type":"string","description":"Reranker model slug"},"query":{"type":"string","description":"The search query"},"documents":{"type":"array","items":{"type":"string"},"description":"Documents to rerank"},"top_n":{"type":"integer","description":"Number of top results to return"}}}}}},"responses":{"200":{"description":"Reranked results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"relevance_score":{"type":"number"},"document":{"type":"string"}}}}}}}}},"402":{"description":"Payment Required"}}}},"/v1/agents/execute":{"post":{"operationId":"agentExecute","summary":"Autonomous AI Agent Execution","tags":["Agents"],"description":"Execute an autonomous AI agent that performs multi-step reasoning, tool use, and action planning. The agent decomposes complex tasks, reasons through sub-problems, invokes tools (web search, code execution, data analysis), and returns a synthesized result with confidence scoring.","security":[{"x402":[]},{"bearerAuth":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"1.000000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["task"],"properties":{"task":{"type":"string","description":"Natural language task description for the agent to execute"},"context":{"type":"string","description":"Additional context or constraints for execution"},"max_steps":{"type":"integer","minimum":1,"maximum":20,"description":"Maximum reasoning/action steps"},"tools":{"type":"array","items":{"type":"string"},"description":"Tools the agent may use (e.g. 'web_search', 'code_exec', 'data_analysis')"}}}}}},"responses":{"200":{"description":"Agent execution result","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"model":{"type":"string"},"task":{"type":"string"},"status":{"type":"string","enum":["completed","failed","timeout"]},"steps_executed":{"type":"integer"},"output":{"type":"object","properties":{"reasoning":{"type":"string"},"result":{"type":"string"},"confidence":{"type":"number"}}},"usage":{"type":"object","properties":{"reasoning_tokens":{"type":"integer"},"action_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"tools_invoked":{"type":"integer"}}}}}}}},"402":{"description":"Payment Required"}}}}}}