{"openapi":"3.1.0","info":{"title":"MacLustr LLM API","version":"1.0.0","description":"Inférence locale sur Apple Silicon (MLX). API compatible OpenAI."},"servers":[{"url":"https://llm.spboucher.ai"}],"paths":{"/v1/models":{"get":{"summary":"Lister les modèles","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Liste","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}}}}},"400":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/models/{model}":{"get":{"summary":"Décrire un modèle","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Succès","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"}}}},"400":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"model","in":"path","required":true,"schema":{"type":"string","enum":["maclustr-qwen3"]}}]}},"/v1/chat/completions":{"post":{"summary":"Créer une complétion de conversation","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Réponse JSON, ou flux `text/event-stream` si `stream: true`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletion"}},"text/event-stream":{"schema":{"$ref":"#/components/schemas/ChatCompletionChunk"}}}},"400":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}}}},"/v1/completions":{"post":{"summary":"Créer une complétion de texte brut","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Réponse JSON ou flux SSE.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionRequest"}}}}}},"/health":{"get":{"summary":"Vivacité de la passerelle","responses":{"200":{"description":"ok"}}}},"/ready":{"get":{"summary":"Moteur prêt à servir","responses":{"200":{"description":"prêt"},"503":{"description":"moteur indisponible"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Clé API MacLustr (`mlx_sk_…`)."}},"schemas":{"ChatRequest":{"properties":{"model":{"maxLength":128,"minLength":1,"title":"Model","type":"string"},"stream":{"default":false,"title":"Stream","type":"boolean"},"stream_options":{"anyOf":[{"$ref":"#/components/schemas/StreamOptions"},{"type":"null"}],"default":null},"max_tokens":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Max Tokens"},"temperature":{"anyOf":[{"maximum":2,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"title":"Temperature"},"top_p":{"anyOf":[{"exclusiveMinimum":0,"maximum":1,"type":"number"},{"type":"null"}],"default":null,"title":"Top P"},"top_k":{"anyOf":[{"maximum":1000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"title":"Top K"},"min_p":{"anyOf":[{"maximum":1,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"title":"Min P"},"presence_penalty":{"anyOf":[{"maximum":2,"minimum":-2,"type":"number"},{"type":"null"}],"default":null,"title":"Presence Penalty"},"frequency_penalty":{"anyOf":[{"maximum":2,"minimum":-2,"type":"number"},{"type":"null"}],"default":null,"title":"Frequency Penalty"},"repetition_penalty":{"anyOf":[{"maximum":2,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"title":"Repetition Penalty"},"stop":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Stop"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Seed"},"n":{"anyOf":[{"maximum":1,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"N"},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"User"},"messages":{"items":{"$ref":"#/components/schemas/Message"},"minItems":1,"title":"Messages","type":"array"},"max_completion_tokens":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Max Completion Tokens"},"tools":{"anyOf":[{"items":{"$ref":"#/components/schemas/Tool"},"maxItems":128,"type":"array"},{"type":"null"}],"default":null,"title":"Tools"},"tool_choice":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Tool Choice"},"response_format":{"anyOf":[{"$ref":"#/components/schemas/ResponseFormat"},{"type":"null"}],"default":null},"enable_thinking":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Enable Thinking"},"reasoning_effort":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reasoning Effort"},"logprobs":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Logprobs"},"top_logprobs":{"anyOf":[{"maximum":10,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"title":"Top Logprobs"}},"required":["model","messages"],"title":"ChatRequest","type":"object"},"CompletionRequest":{"properties":{"model":{"maxLength":128,"minLength":1,"title":"Model","type":"string"},"stream":{"default":false,"title":"Stream","type":"boolean"},"stream_options":{"anyOf":[{"$ref":"#/components/schemas/StreamOptions"},{"type":"null"}],"default":null},"max_tokens":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Max Tokens"},"temperature":{"anyOf":[{"maximum":2,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"title":"Temperature"},"top_p":{"anyOf":[{"exclusiveMinimum":0,"maximum":1,"type":"number"},{"type":"null"}],"default":null,"title":"Top P"},"top_k":{"anyOf":[{"maximum":1000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"title":"Top K"},"min_p":{"anyOf":[{"maximum":1,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"title":"Min P"},"presence_penalty":{"anyOf":[{"maximum":2,"minimum":-2,"type":"number"},{"type":"null"}],"default":null,"title":"Presence Penalty"},"frequency_penalty":{"anyOf":[{"maximum":2,"minimum":-2,"type":"number"},{"type":"null"}],"default":null,"title":"Frequency Penalty"},"repetition_penalty":{"anyOf":[{"maximum":2,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"title":"Repetition Penalty"},"stop":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Stop"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Seed"},"n":{"anyOf":[{"maximum":1,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"N"},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"User"},"prompt":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}],"title":"Prompt"}},"required":["model","prompt"],"title":"CompletionRequest","type":"object"},"FunctionDef":{"properties":{"name":{"maxLength":64,"minLength":1,"pattern":"^[a-zA-Z0-9_.-]+$","title":"Name","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"parameters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Parameters"},"strict":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Strict"}},"required":["name"],"title":"FunctionDef","type":"object"},"JsonSchemaSpec":{"properties":{"name":{"default":"response","title":"Name","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Schema"},"strict":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Strict"}},"title":"JsonSchemaSpec","type":"object"},"Message":{"properties":{"role":{"enum":["system","developer","user","assistant","tool"],"title":"Role","type":"string"},"content":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"default":null,"title":"Content"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"tool_calls":{"anyOf":[{"items":{"$ref":"#/components/schemas/ToolCall"},"type":"array"},{"type":"null"}],"default":null,"title":"Tool Calls"},"tool_call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tool Call Id"}},"required":["role"],"title":"Message","type":"object"},"ResponseFormat":{"properties":{"type":{"enum":["text","json_object","json_schema"],"title":"Type","type":"string"},"json_schema":{"anyOf":[{"$ref":"#/components/schemas/JsonSchemaSpec"},{"type":"null"}],"default":null}},"required":["type"],"title":"ResponseFormat","type":"object"},"StreamOptions":{"properties":{"include_usage":{"default":false,"title":"Include Usage","type":"boolean"}},"title":"StreamOptions","type":"object"},"Tool":{"properties":{"type":{"const":"function","title":"Type","type":"string"},"function":{"$ref":"#/components/schemas/FunctionDef"}},"required":["type","function"],"title":"Tool","type":"object"},"ToolCall":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"type":{"const":"function","default":"function","title":"Type","type":"string"},"function":{"$ref":"#/components/schemas/ToolCallFunction"}},"required":["function"],"title":"ToolCall","type":"object"},"ToolCallFunction":{"properties":{"name":{"title":"Name","type":"string"},"arguments":{"title":"Arguments","type":"string"}},"required":["name","arguments"],"title":"ToolCallFunction","type":"object"},"Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"prompt_tokens_details":{"type":"object","properties":{"cached_tokens":{"type":"integer"}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"type":"string"},"type":{"type":"string"},"param":{"type":["string","null"]},"code":{"type":["string","null"],"enum":["invalid_request","context_length_exceeded","unsupported_parameter","missing_api_key","invalid_api_key","model_not_allowed","endpoint_not_allowed","model_not_found","request_too_large","json_validation_failed","rate_limit_exceeded","tokens_rate_limit_exceeded","concurrency_limit_exceeded","insufficient_quota","too_many_attempts","internal_error","engine_error","engine_overloaded","engine_unavailable","memory_pressure","queue_timeout","engine_timeout","request_timeout",null]},"request_id":{"type":"string"}}}}},"Model":{"type":"object","properties":{"id":{"type":"string","enum":["maclustr-qwen3"]},"object":{"const":"model"},"created":{"type":"integer"},"owned_by":{"type":"string"},"display_name":{"type":"string"},"context_window":{"type":"integer"},"max_output_tokens":{"type":"integer"},"quantization":{"type":"string"},"license":{"type":"string"},"capabilities":{"type":"object"}}},"ChatCompletion":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"chat.completion"},"created":{"type":"integer"},"model":{"type":"string"},"system_fingerprint":{"type":"string"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"finish_reason":{"type":"string","enum":["stop","length","tool_calls"]},"message":{"type":"object","properties":{"role":{"const":"assistant"},"content":{"type":["string","null"]},"reasoning_content":{"type":"string"},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/ToolCall"}}}}}}},"usage":{"$ref":"#/components/schemas/Usage"}}},"ChatCompletionChunk":{"type":"object","description":"Un événement SSE `data:` du flux.","properties":{"id":{"type":"string"},"object":{"const":"chat.completion.chunk"},"created":{"type":"integer"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"finish_reason":{"type":["string","null"]},"delta":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"},"reasoning_content":{"type":"string"},"tool_calls":{"type":"array"}}}}}},"usage":{"$ref":"#/components/schemas/Usage"}}}}},"x-error-codes":{"invalid_request":{"status":400,"description":"Corps de requête invalide (champ manquant, type ou valeur incorrects)."},"context_length_exceeded":{"status":400,"description":"Le prompt dépasse la fenêtre de contexte du modèle."},"unsupported_parameter":{"status":400,"description":"Paramètre valide chez OpenAI mais non pris en charge par ce moteur."},"missing_api_key":{"status":401,"description":"Aucune clé API fournie."},"invalid_api_key":{"status":401,"description":"Clé API inconnue, révoquée, désactivée ou expirée."},"model_not_allowed":{"status":403,"description":"La clé n'a pas accès à ce modèle."},"endpoint_not_allowed":{"status":403,"description":"La clé n'a pas accès à cet endpoint."},"model_not_found":{"status":404,"description":"Modèle inexistant."},"request_too_large":{"status":413,"description":"Corps de requête au-delà de la taille maximale."},"json_validation_failed":{"status":422,"description":"Mode JSON : la sortie du modèle n'a pas pu être validée."},"rate_limit_exceeded":{"status":429,"description":"Limite de requêtes par minute atteinte."},"tokens_rate_limit_exceeded":{"status":429,"description":"Limite de tokens par minute atteinte."},"concurrency_limit_exceeded":{"status":429,"description":"Trop de requêtes simultanées pour cette clé."},"insufficient_quota":{"status":429,"description":"Quota quotidien ou mensuel de tokens épuisé."},"too_many_attempts":{"status":429,"description":"Trop de tentatives d'authentification échouées depuis cette adresse."},"internal_error":{"status":500,"description":"Erreur interne."},"engine_error":{"status":502,"description":"Le moteur d'inférence a renvoyé une erreur."},"engine_overloaded":{"status":503,"description":"File d'attente pleine."},"engine_unavailable":{"status":503,"description":"Moteur d'inférence indisponible (redémarrage en cours)."},"memory_pressure":{"status":503,"description":"Mémoire du serveur sous pression critique."},"queue_timeout":{"status":503,"description":"La requête a attendu trop longtemps en file."},"engine_timeout":{"status":504,"description":"Le moteur n'a pas répondu dans le délai imparti."},"request_timeout":{"status":504,"description":"Durée maximale de génération dépassée."}},"x-limits":{"max_body_bytes":4194304,"max_messages":512,"request_timeout_s":600.0,"nonstream_timeout_s":280.0,"queue_timeout_s":120.0,"max_queue":64}}