{"openapi":"3.1.0","info":{"title":"HyperAI API","version":"1.0.0","description":"Run the AI models you keep in HyperAI on a picture, on HyperCluster members' graphics cards; read pictures on HyperCluster's AI chips; add, rename and delete models. Paid from your HyperAI credit; a call that fails costs nothing. Make a key at /developers. AI agents can also use the MCP server at /mcp with the same key."},"servers":[{"url":"https://ai.hypercluster.org/v1"}],"security":[{"apiKey":[]}],"paths":{"/models":{"get":{"operationId":"listModels","summary":"Your models, newest first","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"addModel","summary":"Add a model: from a link, or by uploading it in pieces","description":"With { url }: the file is fetched from that public https link and checked in the background (202; ask GET /models/{id} until status is ready or failed). With { fileName, bytes }: send the file in pieces of at most upload.chunkBytes with PUT /models/{id}/chunk?offset=…, then POST /models/{id}/done. Needs a key allowed to change models.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"name":{"type":"string","maxLength":120},"fileName":{"type":"string","description":"only if the link does not end with the file's name"}}},{"type":"object","required":["fileName","bytes"],"properties":{"fileName":{"type":"string","description":".pt, .pth or .onnx; a LoRA adapter as .zip"},"bytes":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":120}}}]}}}},"responses":{"201":{"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"$ref":"#/components/schemas/Model"},"upload":{"type":"object","properties":{"chunkBytes":{"type":"integer"},"chunk":{"type":"string"},"done":{"type":"string"}}}}}}}},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/models/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The model's id."}],"get":{"operationId":"getModel","summary":"One of your models","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateModel","summary":"Rename it, or change its labels (class 0 first)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"labels":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"deleteModel","summary":"Delete it for good","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"const":true}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/models/{id}/chunk":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The model's id."},{"name":"offset","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Where this piece starts in the file."}],"put":{"operationId":"uploadModelPiece","summary":"One piece of the file","requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/models/{id}/done":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The model's id."}],"post":{"operationId":"finishModelUpload","summary":"The whole file is sent: check and keep it","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/models/{id}/predict":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The model's id."}],"post":{"operationId":"runModel","summary":"Run your model on one picture, on a member's graphics card","description":"Paid by the second of GPU time (at least one second, usually one to three). A detection model answers with objects; a classification model with classes.","requestBody":{"required":true,"description":"The picture (JPEG, PNG or WebP, at most 10 MB): as a form upload (field \"image\"), as the body itself, or as JSON with the picture in base64 or a public https link to it.","content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","format":"binary"},"tasks":{"type":"string","description":"vision.analyze only: e.g. \"objects,text\""}},"required":["image"]}},"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"base64, or a data: URL"},"image_url":{"type":"string","format":"uri","description":"a public https link"},"tasks":{"type":"array","items":{"type":"string","enum":["objects","labels","text","faces"]}}}}},"image/*":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prediction"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/models/{id}/chat":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The model's id."}],"post":{"operationId":"chatWithModel","summary":"Chat with your fine-tuned chat model (a LoRA adapter you keep), on a member's graphics card","description":"Paid by the second of GPU time. Waits up to 90 seconds for the reply (200). The first chat with a model on a PC can take some minutes (the PC fetches the model it was trained on, not charged): then 202 with status \"running\" and a poll address (GET /chat-runs/{id}).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","maxItems":40,"items":{"type":"object","required":["role","content"],"properties":{"role":{"enum":["system","user","assistant"]},"content":{"type":"string","maxLength":16000}}},"description":"Oldest first; the last is the user's."},"max_tokens":{"type":"integer","minimum":1,"maximum":2048,"default":512},"temperature":{"type":"number","minimum":0,"maximum":2,"default":0.7}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRun"}}}},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRun"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/chat-runs/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"wait","in":"query","schema":{"type":"integer","maximum":60000},"description":"Wait up to this many milliseconds for it to end."}],"get":{"operationId":"getChatRun","summary":"A chat that was still running: its reply when it has one (kept for 10 minutes)","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRun"}}}},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRun"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/vision/analyze":{"post":{"operationId":"analyzePicture","summary":"Read one picture on HyperCluster's AI chips","parameters":[{"name":"tasks","in":"query","schema":{"type":"string"},"description":"Any of objects, labels, text, faces (comma-separated); all four when left out."}],"requestBody":{"required":true,"description":"The picture (JPEG, PNG or WebP, at most 10 MB): as a form upload (field \"image\"), as the body itself, or as JSON with the picture in base64 or a public https link to it.","content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","format":"binary"},"tasks":{"type":"string","description":"vision.analyze only: e.g. \"objects,text\""}},"required":["image"]}},"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"base64, or a data: URL"},"image_url":{"type":"string","format":"uri","description":"a public https link"},"tasks":{"type":"array","items":{"type":"string","enum":["objects","labels","text","faces"]}}}}},"image/*":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analysis"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/balance":{"get":{"operationId":"getBalance","summary":"Your HyperAI credit","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"hypec":{"type":"number"},"usd":{"type":"number"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Your API key, hc_…"}},"responses":{"Error":{"description":"Something is wrong; the message says what.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}},"schemas":{"Box":{"type":"array","items":{"type":"number"},"minItems":4,"maxItems":4,"description":"[left, top, right, bottom] in pixels of your picture, the right way up"},"Model":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"model"},"name":{"type":"string"},"kind":{"enum":["yolo","onnx","pytorch","lora"],"description":"lora: a chat model's LoRA adapter (kept as a .zip; it does not look at pictures)"},"baseModel":{"type":["string","null"],"description":"lora: the model it was trained on"},"rank":{"type":["integer","null"]},"task":{"type":["string","null"]},"labels":{"type":"array","items":{"type":"string"}},"bytes":{"type":"integer"},"created":{"type":"string","format":"date-time"},"status":{"enum":["ready","preparing","uploading","failed"]},"ready":{"type":"boolean"},"problem":{"type":"string"},"runnable":{"type":"boolean"},"notRunnableBecause":{"type":"string"},"source":{"enum":["job","upload","link"]},"sourceHost":{"type":"string"},"fileName":{"type":"string"}}},"Prediction":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"model.prediction"},"model":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"task":{"type":"string"}}},"image":{"type":"object","properties":{"width":{"type":"integer"},"height":{"type":"integer"}}},"objects":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"class":{"type":"integer"},"score":{"type":"number"},"box":{"$ref":"#/components/schemas/Box"}}}},"classes":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"class":{"type":"integer"},"score":{"type":"number"}}}},"gpu":{"type":"string"},"device":{"type":["string","null"],"description":"the GPU it ran on, e.g. 'cuda:0' (null: the PC did not say)"},"seconds":{"type":"number"},"ms":{"type":"integer"},"cost":{"type":"object","properties":{"hypec":{"type":"number"},"usd":{"type":"number"}}},"balance":{"type":"object","properties":{"hypec":{"type":"number"}}}}},"ChatRun":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"model.chat"},"status":{"enum":["running","done","failed"]},"phase":{"type":"string","description":"running: waiting, building, prefetch (fetching the model it was trained on) or running"},"poll":{"type":"string"},"reply":{"type":"object","properties":{"role":{"const":"assistant"},"content":{"type":"string"}}},"usage":{"type":"object","properties":{"tokensIn":{"type":["integer","null"]},"tokensOut":{"type":["integer","null"]}}},"gpu":{"type":"string"},"device":{"type":["string","null"]},"seconds":{"type":"number"},"cost":{"type":"object","properties":{"hypec":{"type":"number"},"usd":{"type":"number"}}},"balance":{"type":"object","properties":{"hypec":{"type":"number"}}},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Analysis":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"vision.analysis"},"image":{"type":"object","properties":{"width":{"type":"integer"},"height":{"type":"integer"}}},"tasks":{"type":"array","items":{"type":"string"}},"objects":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"score":{"type":"number"},"box":{"$ref":"#/components/schemas/Box"}}}},"labels":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"score":{"type":"number"}}}},"text":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"score":{"type":"number"},"box":{"type":"array","items":{"type":"array","items":{"type":"number"}}}}}},"faces":{"type":"object","properties":{"count":{"type":"integer"},"boxes":{"type":"array","items":{"type":"object","properties":{"score":{"type":"number"},"box":{"$ref":"#/components/schemas/Box"}}}}}},"ms":{"type":"integer"},"cost":{"type":"object","properties":{"hypec":{"type":"number"},"usd":{"type":"number"}}},"balance":{"type":"object","properties":{"hypec":{"type":"number"}}}}}}}}