GetFacade एजेंट API

त्वरित शुरुआत

1. कुंजी जारी करें

   app.getfacade.ai→खाता→सेटिंग्स→API→कुंजी बनाएँ

   मान एक ही बार दिखता है और वापस नहीं मिलता, केवल बदला जा सकता है। खर्च सीमा जारी करते समय तय होती है और हर सशुल्क कॉल पर लागू होती है।

   एजेंट कुंजी जारी करें

2. MCP सर्वर दर्ज करें

   क्लाइंट कॉन्फ़िगरेशन में एक प्रविष्टि जोड़ें और क्लाइंट पुनः आरंभ करें। Claude Desktop इसे claude_desktop_config.json में रखता है; हर दूसरा MCP क्लाइंट वही तीन फ़ील्ड लेता है।

   claude_desktop_config.jsonकॉपी करें

   {
     "mcpServers": {
       "getfacade": {
         "command": "npx",
         "args": ["-y", "@getfacade/mcp"],
         "env": { "GETFACADE_API_KEY": "your-key" }
       }
     }
   }

   पर्यावरण चर

   चर	अनिवार्य	डिफ़ॉल्ट मान
   GETFACADE_API_KEY	हाँ	—
   GETFACADE_API_BASE_URL	नहीं	https://api.getfacade.ai/api/v1

3. या HTTP API सीधे बुलाएँ

   वही कुंजी Bearer टोकन के रूप में काम करती है। अनुरोध और उत्तर JSON:API दस्तावेज़ हैं, जिनमें id शीर्ष स्तर का फ़ील्ड है और कभी attributes के भीतर नहीं होता।

   shellकॉपी करें

   curl -X POST https://api.getfacade.ai/api/v1/projects \
     -H "Authorization: Bearer $GETFACADE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"data":{"type":"project","attributes":{"name":"Maple Street 14"}}}'

टूल

इक्कीस टूल। MCP सर्वर न कोई स्थिति रखता है, न अपने नियम: हर टूल बगल में लिखे एंडपॉइंट पर एक या अधिक कॉल है, और एजेंट जो भी संदेश दोहराता है वह API लिखता है।

• create_building

  create_building(name, goals?, construction_region?)
    -> { building_id, name }

  भवन बनाता है। नाम खाते के भीतर अद्वितीय और अधिकतम 50 वर्ण का होता है; दोहराव 422 के साथ अस्वीकृत होता है।

  कॉल करता हैPOST /projects

• upload_photo

  upload_photo(building_id, file_path, wait_for_validation? = true)
    -> { view_id, validation: { status, reason? } }

  दृश्य दर्ज करता है, बाइट पूर्व-हस्ताक्षरित URL पर भेजता है, उनकी पुष्टि करता है और तब तक पूछता है जब तक तस्वीर स्वीकृत या अस्वीकृत न हो जाए। चौड़ाई, ऊँचाई और md5 स्थानीय रूप से निकाले जाते हैं; पक्षानुपात सर्वर तय करता है।

  कॉल करता हैPOST /projects/{project}/angles → PUT (presigned) → POST /angles/{angle}/confirm → GET /angles/{angle}/validation

• start_designअतुल्यकालिक

  start_design(building_id, view_id, prompt?, style_ids?, colors?,
               brand_selections?, render_effort?, seed?)
    -> { design_id, job_id, status, seed }

  चुने हुए दृश्य पर मुखौटे का डिज़ाइन बनाता है और उसे तस्वीर पर दिखाता है: भवन के देश में लागू सामग्री, वहाँ वास्तव में बिकने वाले उत्पाद, और सतह के पीछे की परत संरचना। एक डिज़ाइन बनाता है, काम को कतार में लगाता है और कार्य id लौटाता है। seed वैकल्पिक है: न देने पर सर्वर स्वयं बनाकर लौटा देता है।

  कॉल करता हैPOST /projects/{project}/concepts → POST /concepts/{concept}/angles/{conceptAngle}/renders

• refine_designअतुल्यकालिक

  refine_design(render_id | design_id + building_id, instruction,
                style_ids?, colors?, brand_selections?, render_effort?, seed?)
    -> { design_id, job_id, status, parent_render_id, seed }

  तैयार डिज़ाइन को शब्दों में संशोधित करता है। निर्देश तैयार डिज़ाइन पर लागू होता है, इसलिए जिसका उल्लेख नहीं है वह वैसा ही रहता है। मुख्य दृश्य का संशोधन नया डिज़ाइन बनाता है, इसलिए पिछला कभी नहीं मिटता।

  कॉल करता हैGET /renders/{render} → POST /concepts/{concept}/angles/{conceptAngle}/renders (mode: refine)

• get_job

  get_job(job_id, kind: "render" | "album" | "estimate" = "render")
    -> { status, expected_seconds?, result_url?, error?, error_code? }

  एक रेंडर, अनुमान या एल्बम की स्थिति पढ़ता है।

  कॉल करता हैGET /renders/{render} · GET /estimates/{estimate}

• list_jobs

  list_jobs(kind?, limit? = 20)
    -> [{ job_id, kind, status, building_id, created_at }]

  खाते भर के हाल के कार्य, अधूरे सबसे ऊपर।

  कॉल करता हैGET /history

• list_designs

  list_designs(building_id)
    -> [{ design_id, note, has_main_render, main_render_id,
         main_render_url, renders }]

  किसी भवन के डिज़ाइन और उनके रेंडर। अनुमान और एल्बम के लिए रेंडर आईडी यहीं से मिलती हैं।

  कॉल करता हैGET /projects/{project}/concepts

• order_estimateअतुल्यकालिक

  order_estimate(design_id, render_ids, currency?,
                 measurement_system?, special_requirements?)
    -> { job_id, status }

  डिज़ाइन की लागत सामग्री और श्रम में पंक्ति दर पंक्ति निकालता है, उन्हीं दामों पर जो बताई गई सामग्री के भवन के देश में हैं। मुद्रा और माप प्रणाली डिफ़ॉल्ट रूप से उसी देश से ली जाती हैं।

  कॉल करता हैPOST /projects/{project}/concepts/{concept}/estimates

• order_albumअतुल्यकालिक

  order_album(design_id, render_ids, language?, include_blueprints?,
              include_estimate?, requirements?)
    -> { job_id, status }

  निर्माण करने वाली टीम के लिए डिज़ाइन दर्ज करता है: सामग्री, मुखौटे की परत संरचना, सुरक्षा टिप्पणियाँ और उनके पीछे के मानक। पूर्ण मुख्य रेंडर आवश्यक है।

  कॉल करता हैPOST /concepts/{concept}/album/generate

• upscale_renderअतुल्यकालिक

  upscale_render(render_id)
    -> { job_id, status }

  पूरे हो चुके रेंडर को बड़ा करता है। टोकन लगते हैं और यह अतुल्यकालिक चलता है।

  कॉल करता हैPOST /renders/{render}/upscale

• get_estimate

  get_estimate(estimate_id)
    -> { status, currency, facade_area, materials_total, labor_total,
         grand_total, notes, lines: [{ line_id, section, name, quantity,
         unit, unit_price, line_total }] }

  अनुमान स्वयं: कुल राशि, उनके पीछे की मान्यताएँ और मात्रा, इकाई तथा मूल्य के साथ हर पंक्ति। get_job अनुमान की स्थिति बताता है, उसकी सामग्री कभी नहीं।

  कॉल करता हैGET /estimates/{estimate}

• add_estimate_line

  add_estimate_line(estimate_id, section, name, quantity,
                    unit_price, unit?, category?)
    -> { line_id }

  अनुमान में एक पंक्ति जोड़ता है। इकाइयाँ अनुमान की अपनी माप प्रणाली से आती हैं।

  कॉल करता हैPOST /estimates/{estimate}/items

• update_estimate_line

  update_estimate_line(estimate_id, line_id, name?, quantity?,
                       unit_price?, unit?, category?, section?)
    -> { line_id }

  अनुमान की एक पंक्ति बदलता है। केवल भेजे गए फ़ील्ड बदलते हैं; कुल सर्वर दोबारा जोड़ता है।

  कॉल करता हैPATCH /estimates/{estimate}/items/{item}

• delete_estimate_line

  delete_estimate_line(estimate_id, line_id)
    -> { deleted }

  अनुमान से एक पंक्ति हटाता है।

  कॉल करता हैDELETE /estimates/{estimate}/items/{item}

• delete_render

  delete_render(render_id)
    -> { deleted }

  एक रेंडर हटाता है। मुख्य रेंडर हटाने पर उसका डिज़ाइन ड्राफ़्ट में लौट जाता है।

  कॉल करता हैDELETE /renders/{render}

• delete_design

  delete_design(building_id, design_id)
    -> { deleted }

  एक डिज़ाइन को उसके रेंडर सहित हटाता है।

  कॉल करता हैDELETE /projects/{project}/concepts/{concept}

• delete_building

  delete_building(building_id)
    -> { deleted }

  भवन को उसकी पूरी सामग्री सहित हटाता है। खर्च हो चुके टोकन वापस नहीं मिलते।

  कॉल करता हैDELETE /projects/{project}

• list_token_packages

  list_token_packages()
    -> [{ package, tokens, price, currency }]

  इस खाते के लिए उपलब्ध पैकेज, उनकी कीमत और टोकन संख्या के साथ।

  कॉल करता हैGET /tokens/packages

• buy_tokensअतुल्यकालिक

  buy_tokens(package)
    -> { status, transaction_id, tokens, checkout_url?, detail }

  इस कुंजी के वॉलेट के लिए एक पैकेज खरीदता है। खरीद-अनुमति वाली कुंजी चाहिए, और यह उससे आगे कभी नहीं जाता जितना कुंजी अब भी खर्च कर सकती है।

  कॉल करता हैPOST /tokens/purchase

• get_balance

  get_balance()
    -> { balance, scope: "api", spend_cap, spent, remaining, is_admissible }

  एजेंट बटुआ, इस कुंजी की सीमा, और क्या अगली सशुल्क कॉल स्वीकार होगी।

  कॉल करता हैGET /tokens/balance

• report_problem

  report_problem(message, category?,
                 context?: { tool, endpoint, status_code, job_id,
                             expected, actual })
    -> { reference, message }

  इस API की खराबी की रिपोर्ट करता है: यहाँ बताया गया कोई फ़ील्ड जो कभी नहीं आता, ऐसा इनकार जिसके शब्दों से अगला कदम नहीं निकलता, या माँगे गए से अलग परिणाम। निःशुल्क और खाली वॉलेट पर भी स्वीकार; बदले में संदर्भ संख्या मिलती है, उत्तर नहीं।

  कॉल करता हैPOST /feedback

प्रमाणीकरण और कुंजियाँ

• कुंजी Authorization शीर्षक में Bearer टोकन के रूप में जाती है। MCP सर्वर उसे GETFACADE_API_KEY से पढ़ता है और इसके अलावा कुछ नहीं भेजता।
• मान जारी करते समय एक बार दिखता है और केवल उसका हैश संचित होता है। घुमाव का अर्थ है नई कुंजी जारी करना और पुरानी रद्द करना।
• हर कुंजी पर खर्च सीमा होती है, जो कॉल के कंट्रोलर तक पहुँचने से पहले सर्वर पर लागू होती है। सीमा पूरी होने पर वही कुंजी रुकती है, खाता नहीं।
• कुंजियाँ कुंजियों का प्रबंधन नहीं करतीं: यह मनुष्य का कार्य है, और वे एंडपॉइंट एजेंट कुंजी को 403 देते हैं।
• रद्दीकरण तुरंत प्रभावी होता है। रद्द कुंजी से की गई कॉल 401 लौटाती हैं।

अतुल्यकालिक कार्य और पोलिंग

• start_design, order_estimate और order_album कार्य आईडी लौटाकर समाप्त हो जाते हैं। रेंडर में मिनट लगते हैं: स्थिति अंतिम होने तक GET /renders/{render} या GET /estimates/{estimate} पूछें।
• तस्वीर की जाँच पूरी होने की सूचना उस वेबसॉकेट से आती है जो एजेंट के पास नहीं होता। GET /angles/{angle}/validation पूछें और validation.is_in_progress पढ़ें; स्थिति के पाठ से स्वयं अंतिमता तय न करें।
• तैयार रेंडर और तैयार एल्बम स्थायी सार्वजनिक पतों पर रहते हैं: न हस्ताक्षर, न समय सीमा। यह लिंक सीधे किसी व्यक्ति को दिया जा सकता है, और «परिणाम दिखाओ» का उत्तर यही है। हस्ताक्षर न होने के कारण यह किसी से अनुमति नहीं माँगता: जिसे भी मिले उसके लिए चलता रहता है और बाद में वापस नहीं लिया जा सकता।
• GET /renders/{render}/download अलग बात है: एक हस्ताक्षरित URL जो कुछ मिनटों में समाप्त हो जाता है और फ़ाइल नाम रखता है। यह फ़ाइल सहेजने के लिए है, साझा करने के लिए नहीं।

प्रति कुंजी दर सीमाएँ

एजेंट कुंजी के अपने कोटे होते हैं, उसी खाते के मानवीय सत्रों से अलग, ताकि लूप में फँसा एजेंट स्क्रीन के सामने बैठे व्यक्ति का कोटा न खा जाए। अस्वीकृति सस्ती है: वह मिडलवेयर में तय होती है, किसी भी डेटाबेस कार्य से पहले।

इडेम्पोटेंसी

सशुल्क कॉल एक जॉब बनाती है, और शुल्क जॉब के पीछे चलता है। कॉल को नाम देना ही वह चीज़ है जिससे दोबारा भेजने पर दूसरी जॉब बनने के बजाय वही जॉब लौटती है।

• API की से किया गया हर सशुल्क कॉल Idempotency-Key के साथ आना चाहिए: डिज़ाइन शुरू करना या सुधारना, रेंडर बड़ा करना, अनुमान या एल्बम मंगाना, अनुमान दोबारा बनवाना। इसके बिना कॉल 422 IDEMPOTENCY_KEY_REQUIRED लौटाती है और कतार में कुछ नहीं जाता।
• 8 से 191 वर्णों का कोई भी मान, हर ऑर्डर के लिए एक; आमतौर पर UUID। नए ऑर्डर के लिए नया मान: दो मानों के साथ दो एक जैसी कॉल दो डिज़ाइन हैं।
• वही मान और वही बॉडी लेकर कॉल दोहराने पर मूल स्टेटस और बॉडी लौटती है, जवाब में Idempotent-Replay: true के साथ। कतार में कुछ नहीं जाता और दोबारा शुल्क नहीं लगता।
• वही मान अलग बॉडी के साथ 422 IDEMPOTENCY_KEY_REUSED लौटाता है। पहली कॉल चलते समय आई दोबारा कॉल 409 IDEMPOTENCY_IN_PROGRESS लौटाती है: रुकें और वही कॉल फिर भेजें।
• कोई भी 4xx मान को छोड़ देता है, इसलिए कारण ठीक होने पर वही मान दोबारा भेजा जा सकता है। मान 24 घंटे तक, प्रति खाता याद रखे जाते हैं।
• @getfacade/mcp मान खुद बनाता है और उसी के साथ खुद दोबारा भेजता है, इसलिए टूल कॉल में कुछ भी देना नहीं है।

त्रुटियाँ

विफलताएँ JSON:API त्रुटि दस्तावेज़ के रूप में आती हैं। Laravel की सत्यापन प्रतिक्रियाएँ JSON:API रूप में नहीं होतीं और अपना पाठ message में रखती हैं।

पढ़ने योग्य पाठ API लिखता है, बुलाने वाले की भाषा में। errors[].detail को ज्यों का त्यों दिखाएँ, अपना संदेश न गढ़ें।

शुल्क और प्रवेश

• भुगतान वाले कॉल api स्कोप के क्रेडिट से जाते हैं, और प्रवेश केवल उसी बैलेंस को देखता है: हर की क्रेडिट में भुगतान करती है।
• सक्रिय Pro Plan हर बिलिंग अवधि में एक बार api वॉलेट को 1,000 क्रेडिट तक भर देता है। उससे आगे क्रेडिट खरीदे जाते हैं।
• कुंजी अपना वॉलेट तभी भरती है जब उसे खरीद-अनुमति के साथ जारी किया गया हो, और उतना ही जितना वह अब भी खर्च कर सकती है, इसलिए खरीद कभी खर्च सीमा नहीं बढ़ाती।
• api क्षेत्र अलग बटुआ है। ऐप के क्रेडिट, नि:शुल्क स्तर सहित, कुंजी कभी खर्च नहीं करती।
• खर्च हर कुंजी के हिसाब से गिना जाता है, इसलिए प्रत्येक सहायक की खपत अलग दिखती है।
• पूर्व जाँच है GET /tokens/balance, फ़ील्ड data.attributes.agent.is_admissible। यह खंड केवल एजेंट कुंजियों में आता है और यह ध्वज प्रवेश मिडलवेयर को हूबहू दर्शाता है। शेष और सीमा की स्वयं तुलना करने के बजाय इसे पढ़ें।
• प्रवेश का निर्णय कार्य कतार में जाने से पहले होता है, इसलिए अस्वीकृत कॉल पर कुछ खर्च नहीं होता।

रंग और ब्रांड टोकन

start_design दो स्वतंत्र सूचियाँ लेता है, प्रत्येक में अधिकतम दस प्रविष्टियाँ। क्रम 60/30/10 की भूमिका रखता है: पहली प्रविष्टि दीवारों का प्रमुख रंग है।

colors

brand_selections

व्याकरण है category:level:id[@value][.value]। @ के बाद का भाग ज्यामिति मानों के स्लग रखता है, जो अपनी श्रेणी में अद्वितीय हैं, इसलिए वे किस अक्ष के हैं यह खोजा जाता है, टोकन में लिखा नहीं जाता। अज्ञात टोकन 422 के साथ अस्वीकृत होता है, चुपचाप अनदेखा कभी नहीं।

आद्योपांत सत्र

एक भवन, एक तस्वीर, एक डिज़ाइन, फिर दो दस्तावेज़। इसे उत्पन्न करने वाला निर्देश:

Maple Street 14 नाम का भवन बनाओ, ./front.jpg को उसका दृश्य बनाकर अपलोड करो, और गर्म धूसर दीवारों तथा सफेद किनारों के साथ डिज़ाइन शुरू करो। परिणाम के लिए अनुमान और एल्बम का ऑर्डर दो।

create_building(name: "Maple Street 14")
  -> { building_id: "0f8c…" }

upload_photo(building_id: "0f8c…", file_path: "./front.jpg")
  -> { view_id: "41ab…", validation: { status: "approved" } }

start_design(building_id: "0f8c…", view_id: "41ab…",
             colors: ["#8A8F7D", "#F2F0EB"],
             brand_selections: ["siding:line:40@double-4-dutchlap"])
  -> { design_id: "7d21…", job_id: "b933…", status: "queued" }

get_job(job_id: "b933…")
  -> { status: "completed", result_url: "https://…" }

refine_design(render_id: "b933…",
              instruction: "put a canopy over the front door")
  -> { design_id: "9e44…", job_id: "c07f…", status: "queued" }

order_estimate(design_id: "9e44…", render_ids: ["c07f…"])
order_album(design_id: "9e44…", render_ids: ["c07f…"], include_estimate: true)

सामग्री

• यह पृष्ठ Markdown में
• OpenAPI 3.1 विशिष्टि (YAML)
• npm पर @getfacade/mcp
• हमसे संपर्क करें