{"openapi":"3.1.0","info":{"title":"Clavue API","version":"1.0.0","summary":"OpenAI-compatible models, membership, and imux-link tickets.","description":"Public contract for https://api.clavue.com. Short /v1 paths rewrite to /api/membership/v1 on api.clavue.com and www.clavue.com. One membership ledger. Web uses cookie imux_membership_session. CLI and scripts use Authorization: Bearer (device session or cv_live_ key). GET /v1/usage is the quota snapshot implemented by the membership API. GET /v1/quota is the developer-facing alias documented here with the same snapshot shape."},"servers":[{"url":"https://api.clavue.com"}],"tags":[{"name":"Models"},{"name":"Chat"},{"name":"Images"},{"name":"Audio"},{"name":"Embeddings"},{"name":"Translate"},{"name":"MCP"},{"name":"Quota"},{"name":"Membership"},{"name":"Relay"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Device session token or cv_live_ API key."},"cookieAuth":{"type":"apiKey","in":"cookie","name":"imux_membership_session"}},"schemas":{"ErrorEnvelope":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"requestId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"messageZh":{"type":"string"},"stage":{"type":"string"},"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":"string"}}}}},"ChatRequest":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","examples":["auto","clavue-2.1","clavue-2.1-pro"]},"messages":{"type":"array","items":{"type":"object"}},"stream":{"type":"boolean"},"tools":{"type":"array","items":{"type":"object"}},"tool_choice":{"type":["string","object"]}}}}},"paths":{"/v1/models":{"get":{"tags":["Models"],"operationId":"listModels","summary":"List official product models","description":"OpenAI-style catalog. Unauthenticated callers receive the public allowlist. Signed-in callers also receive plan and usage.","responses":{"200":{"description":"Model list","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"owned_by":{"type":"string"}}}}}}}}}}}},"/v1/chat/completions":{"post":{"tags":["Chat"],"operationId":"createChatCompletion","summary":"Chat completions","description":"OpenAI-compatible chat. Text product ids accept tools. clavue-img on this path is wrapped as a chat completion with Markdown stills. Media product ids reject tools.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}},"responses":{"200":{"description":"Chat completion or SSE stream"},"401":{"description":"sign_in_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"quota_exceeded"}}}},"/v1/images/generations":{"post":{"tags":["Images"],"operationId":"createImage","summary":"Generate an image","description":"Official image product clavue-img. Size whitelist includes 1024x1024, 768x1344, and 1344x768.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"model":{"type":"string","examples":["clavue-img"]},"prompt":{"type":"string","maxLength":4000},"size":{"type":"string","enum":["1024x1024","768x1344","1344x768"]},"n":{"type":"integer","minimum":1,"maximum":4}}}}}},"responses":{"200":{"description":"Image payload with public URL and b64_json"},"401":{"description":"sign_in_required"}}}},"/v1/images/edits":{"post":{"tags":["Images"],"operationId":"editImage","summary":"Edit an image","description":"Image-to-image edit. JSON body accepts image as a data:image/ URL, or images[]. Product id clavue-img.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"model":{"type":"string"},"prompt":{"type":"string"},"image":{"type":"string","description":"data:image/ URL"}}}}}},"responses":{"200":{"description":"Edited image"},"401":{"description":"sign_in_required"}}}},"/v1/audio/speech":{"post":{"tags":["Audio"],"operationId":"createSpeech","summary":"Speech or song audio","description":"Split on product id. clavue-tts is broadcast speech (voice Uncle_Fu or Vivian). clavue-music is a song. Unauthenticated calls are 401.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string","enum":["clavue-tts","clavue-music"]},"input":{"type":"string"},"voice":{"type":"string"}}}}}},"responses":{"200":{"description":"Audio bytes","content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"sign_in_required"}}}},"/v1/audio/transcriptions":{"post":{"tags":["Audio"],"operationId":"createTranscription","summary":"Transcribe audio","description":"OpenAI-compatible transcriptions. multipart/form-data with a file.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"model":{"type":"string"}}}}}},"responses":{"200":{"description":"Transcript text"},"401":{"description":"sign_in_required"}}}},"/v1/embeddings":{"post":{"tags":["Embeddings"],"operationId":"createEmbedding","summary":"Embeddings","description":"OpenAI-compatible embeddings on api.clavue.com. Send a product model id and an input string or string array. Clients that only have chat can still embed by asking a text model, but this path is the vector contract.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string"},"input":{"type":["string","array"],"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Embedding vectors"},"401":{"description":"sign_in_required"}}}},"/v1/translate":{"post":{"tags":["Translate"],"operationId":"translate","summary":"Translate text","description":"Translation helper. Text product ids also translate through POST /v1/chat/completions. This path takes text plus a target language.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text","target_lang"],"properties":{"model":{"type":"string","examples":["auto"]},"text":{"type":"string"},"target_lang":{"type":"string","examples":["zh-CN","en"]}}}}}},"responses":{"200":{"description":"Translated text"},"401":{"description":"sign_in_required"}}}},"/v1/mcp":{"get":{"tags":["MCP"],"operationId":"discoverMcp","summary":"Official MCP discovery","description":"Hosted tools (web_search). Equivalent capability to model clavue-2.1-search. Tool calls go to POST /v1/mcp/tools/call.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Tool list"},"401":{"description":"sign_in_required"}}}},"/v1/quota":{"get":{"tags":["Quota"],"operationId":"getQuota","summary":"Quota snapshot","description":"Developer-facing quota read: plan, day/week/month usage, boost, and wallet. The membership route implemented in this tree is GET /v1/usage, which returns that snapshot. Use /v1/usage if /v1/quota is not rewritten on the host you are calling.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Quota snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"requestId":{"type":"string"},"usage":{"type":"object"},"plan":{"type":"object"},"walletCents":{"type":"integer"}}}}}},"401":{"description":"sign_in_required"}}}},"/v1/usage":{"get":{"tags":["Quota"],"operationId":"getUsage","summary":"Usage snapshot","description":"Implemented membership ledger read. Day, week, and month remaining, boost, plan, and wallet.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Usage snapshot"},"401":{"description":"sign_in_required"}}}},"/api/membership/auth/login":{"post":{"tags":["Membership"],"operationId":"login","summary":"Password login","description":"identifier or legacy email, plus password. Sets imux_membership_session. Honeypot field website must be empty.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password"],"properties":{"identifier":{"type":"string"},"email":{"type":"string"},"password":{"type":"string"},"client":{"type":"string"}}}}}},"responses":{"200":{"description":"Session cookie set"},"401":{"description":"Invalid email or password"},"429":{"description":"Too many attempts"}}}},"/api/membership/auth/register":{"post":{"tags":["Membership"],"operationId":"register","summary":"Register","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8,"maxLength":128},"displayName":{"type":"string"},"client":{"type":"string"}}}}}},"responses":{"200":{"description":"Account created and session cookie set"},"429":{"description":"Too many attempts"}}}},"/api/membership/auth/delete":{"post":{"tags":["Membership"],"operationId":"deleteAccount","summary":"Delete the signed-in account","description":"POST, not DELETE. Password accounts send password. OTP-only accounts send confirmPhrase DELETE.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"},"confirmPhrase":{"type":"string"}}}}}},"responses":{"200":{"description":"Account deleted"},"401":{"description":"Unauthorized"}}}},"/api/membership/devices":{"get":{"tags":["Relay"],"operationId":"listDevices","summary":"List linked devices","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"devices array"},"401":{"description":"Sign in required"}}},"post":{"tags":["Relay"],"operationId":"registerDevice","summary":"Register this machine","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"deviceId":{"type":"string"},"name":{"type":"string"},"platform":{"type":"string","enum":["macos","windows","linux","other"]},"appVersion":{"type":"string"},"hostLabel":{"type":"string"}}}}}},"responses":{"200":{"description":"Device registered"}}}},"/api/membership/relay/ticket":{"post":{"tags":["Relay"],"operationId":"issueRelayTicket","summary":"Issue an imux-link v2 ticket","description":"Host mode: deviceId + deviceSecret (or x-imux-device-id and x-imux-device-secret). Client mode: Bearer session plus deviceId and optional clientId. Returns relayUrl wss://relay.clavue.com/v2/channel, ticket, and expiresAt.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["deviceId"],"properties":{"deviceId":{"type":"string"},"deviceSecret":{"type":"string"},"clientId":{"type":"string"}}}}}},"responses":{"200":{"description":"Signed ticket","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"relayUrl":{"type":"string"},"ticket":{"type":"string"},"expiresAt":{"type":"string"}}}}}},"401":{"description":"Unauthorized device or sign-in required"}}}}}}