API GetFacade pro agenty

Rychlý start

1. Vydejte klíč

   app.getfacade.ai→Účet→Nastavení→API→Vytvořit klíč

   Hodnota se zobrazí jednou a nelze ji obnovit, jen nahradit. Strop útraty se nastavuje při vydání a platí u každého placeného volání.

   Vydat agentní klíč

2. Zaregistrujte server MCP

   Jeden záznam v konfiguraci klienta, pak restart klienta. Claude Desktop jej drží v claude_desktop_config.json; každý jiný klient MCP přijímá stejná tři pole.

   claude_desktop_config.jsonKopírovat

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

   Proměnné prostředí

   Proměnná	Povinná	Výchozí hodnota
   GETFACADE_API_KEY	Ano	—
   GETFACADE_API_BASE_URL	Ne	https://api.getfacade.ai/api/v1

3. Nebo volejte HTTP API přímo

   Týž klíč slouží jako token Bearer. Požadavky i odpovědi jsou dokumenty JSON:API, kde id je pole nejvyšší úrovně a nikdy neleží uvnitř attributes.

   shellKopírovat

   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"}}}'

Nástroje

Dvacet jedna nástrojů. Server MCP nedrží stav ani vlastní pravidla: každý nástroj je jedno či několik volání endpointů uvedených vedle a každou zprávu, kterou agent zopakuje, píše API.

• create_building

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

  Založí budovu. Název je v rámci účtu jedinečný a nejvýše padesátiznakový; duplicitu odmítne kód 422.

  VoláPOST /projects

• upload_photo

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

  Zaregistruje pohled, nahraje bajty na předpodepsanou URL, potvrdí je a dotazuje se, dokud fotografii systém nepřijme nebo neodmítne. Šířku, výšku a md5 spočítá klient; poměr stran odvodí server.

  VoláPOST /projects/{project}/angles → PUT (presigned) → POST /angles/{angle}/confirm → GET /angles/{angle}/validation

• start_designasynchronní

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

  Navrhne fasádu na zvoleném pohledu a ukáže ji na fotografii: materiály použitelné v zemi stavby, produkty, které se tam skutečně prodávají, a skladbu za povrchem. Vytvoří návrh, zařadí práci do fronty a vrátí id úlohy. Seed je volitelný: když ho vynecháte, server ho vygeneruje sám a vrátí.

  VoláPOST /projects/{project}/concepts → POST /concepts/{concept}/angles/{conceptAngle}/renders

• refine_designasynchronní

  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 }

  Upraví slovy hotový návrh. Pokyn se aplikuje na hotový návrh, takže vše, co nezmiňuje, zůstává. Úprava hlavního pohledu vytvoří nový návrh, takže se ten předchozí nikdy nepřepíše.

  Volá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? }

  Přečte stav jednoho renderu, rozpočtu nebo alba.

  VoláGET /renders/{render} · GET /estimates/{estimate}

• list_jobs

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

  Nedávné úlohy napříč účtem, nedokončené nahoře.

  VoláGET /history

• list_designs

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

  Návrhy budovy i s jejich rendery. Odsud pocházejí identifikátory renderů pro rozpočet a album.

  VoláGET /projects/{project}/concepts

• order_estimateasynchronní

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

  Ocení návrh položku po položce, v materiálu a práci, za ceny uvedených materiálů v zemi stavby. Měna a soustava měr se ve výchozím stavu řídí touto zemí.

  VoláPOST /projects/{project}/concepts/{concept}/estimates

• order_albumasynchronní

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

  Zdokumentuje návrh pro partu, která bude stavět: materiály, skladbu fasády, bezpečnostní poznámky a normy, o které se opírají. Vyžaduje dokončený hlavní render.

  VoláPOST /concepts/{concept}/album/generate

• upscale_renderasynchronní

  upscale_render(render_id)
    -> { job_id, status }

  Zvětší dokončený render. Stojí tokeny a běží asynchronně.

  Volá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 }] }

  Samotný rozpočet: součty, předpoklady za nimi a každá položka s množstvím, jednotkou a cenou. get_job hlásí stav rozpočtu, nikdy jeho obsah.

  VoláGET /estimates/{estimate}

• add_estimate_line

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

  Přidá do rozpočtu položku. Jednotky pocházejí z jeho vlastní měrné soustavy.

  VoláPOST /estimates/{estimate}/items

• update_estimate_line

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

  Změní položku rozpočtu. Mění se jen předaná pole; součty přepočítá server.

  VoláPATCH /estimates/{estimate}/items/{item}

• delete_estimate_line

  delete_estimate_line(estimate_id, line_id)
    -> { deleted }

  Odebere položku z rozpočtu.

  VoláDELETE /estimates/{estimate}/items/{item}

• delete_render

  delete_render(render_id)
    -> { deleted }

  Smaže render. Smazáním hlavního renderu se jeho návrh vrátí do konceptu.

  VoláDELETE /renders/{render}

• delete_design

  delete_design(building_id, design_id)
    -> { deleted }

  Smaže návrh i s rendery pod ním.

  VoláDELETE /projects/{project}/concepts/{concept}

• delete_building

  delete_building(building_id)
    -> { deleted }

  Smaže objekt se vším obsahem. Už utracené tokeny se nevracejí.

  VoláDELETE /projects/{project}

• list_token_packages

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

  Balíčky, které si účet může koupit, s cenou a počtem tokenů.

  VoláGET /tokens/packages

• buy_tokensasynchronní

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

  Koupí balíček do peněženky tohoto klíče. Vyžaduje klíč vydaný s povolením nakupovat a nikdy nepřekročí to, co klíč ještě smí utratit.

  VoláPOST /tokens/purchase

• get_balance

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

  Peněženka agenta, strop tohoto klíče a údaj, zda bude příští placené volání připuštěno.

  VoláGET /tokens/balance

• report_problem

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

  Nahlásí vadu tohoto API: pole popsané zde, které nikdy nedorazí, odmítnutí, z jehož znění neplyne další krok, výsledek, který neodpovídá zadání. Zdarma a přijme se i s prázdnou peněženkou; vrací se číslo jednací, ne odpověď.

  VoláPOST /feedback

Autentizace a klíče

• Klíč cestuje jako token Bearer v hlavičce Authorization. Server MCP jej čte z GETFACADE_API_KEY a nic dalšího neposílá.
• Hodnota se zobrazí jednou, při vydání, a ukládá se jen její otisk. Rotace znamená vydat nový klíč a starý zneplatnit.
• Každý klíč nese strop útraty, vynucený na serveru dřív, než volání dorazí ke kontroleru. Dosažený strop zastaví ten klíč, nikoli účet.
• Klíče nespravují klíče: to je lidský úkon a tyto endpointy odpovídají agentnímu klíči kódem 403.
• Zneplatnění působí okamžitě. Volání zneplatněným klíčem dostane 401.

Asynchronní práce a dotazování

• start_design, order_estimate a order_album vrátí identifikátor úlohy a tím končí. Render trvá minuty: dotazujte se na GET /renders/{render} nebo GET /estimates/{estimate}, dokud není stav konečný.
• Konec kontroly fotografie oznamuje websocket, který agent nemá. Dotazujte se na GET /angles/{angle}/validation a čtěte validation.is_in_progress; konečnost si sami z textu stavu neodvozujte.
• Hotový render a hotové album leží na trvalých veřejných adresách: bez podpisu a bez expirace. Takový odkaz lze dát člověku přímo, a je to odpověď na „ukaž mi výsledek“. Protože není podepsaný, nikoho se neptá: funguje komukoli, kdo ho dostane, a nelze ho odvolat.
• GET /renders/{render}/download je něco jiného: podepsaná URL, která vyprší během minut a nese název souboru. Slouží k uložení souboru, ne ke sdílení.

Limity četnosti na klíč

Agentní klíč má vlastní přihrádky, oddělené od lidských relací téhož účtu, aby zacyklený agent nesnědl příděl člověka u obrazovky. Odmítnutí je levné: padne v middleware, před jakoukoli prací s databází.

Idempotence

Placené volání vytvoří úlohu a platba jde za úlohou. Právě pojmenování volání umožňuje, aby opakování vrátilo tutéž úlohu místo vytvoření druhé.

• Idempotency-Key je povinná u každého placeného volání s klíčem API: založení nebo úprava návrhu, zvětšení renderu, objednání rozpočtu nebo alba, přegenerování rozpočtu. Bez ní volání odpoví 422 IDEMPOTENCY_KEY_REQUIRED a do fronty se nic nedostane.
• Libovolná hodnota o 8 až 191 znacích, jedna na objednávku; obvykle UUID. Nová objednávka dostane novou hodnotu: dvě stejná volání pod dvěma hodnotami jsou dva návrhy.
• Opakování volání se stejnou hodnotou a stejným tělem vrátí původní stav a tělo, s hlavičkou Idempotent-Replay: true. Do fronty se nic nedostane a nic se neúčtuje dvakrát.
• Stejná hodnota s jiným tělem odpoví 422 IDEMPOTENCY_KEY_REUSED. Opakování, které přijde, zatímco první volání ještě běží, odpoví 409 IDEMPOTENCY_IN_PROGRESS: počkejte a pošlete stejné volání znovu.
• Jakákoli odpověď 4xx hodnotu uvolní, takže ji lze poslat znovu, jakmile je příčina odstraněna. Hodnoty se pamatují 24 hodin, v rámci účtu.
• @getfacade/mcp hodnotu vytvoří i volání pod ní zopakuje sám, ve volání nástroje tedy není co předávat.

Chyby

Selhání přicházejí jako chybové dokumenty JSON:API. Validační odpovědi Laravelu tvar JSON:API nemají a text nesou v poli message.

Čitelný text píše API, v jazyce volajícího. Zobrazte errors[].detail beze změny, místo skládání vlastní hlášky.

Platby a připuštění

• Placená volání čerpají z kreditů rozsahu api a přijetí se dívá jen na tento zůstatek: každý klíč platí kredity.
• Aktivní Pro Plan jednou za zúčtovací období doplní peněženku api na 1000 kreditů. Nad rámec toho se kredity kupují.
• Klíč si doplní peněženku, jen pokud byl vydán s povolením nakupovat, a nejvýš o to, co ještě smí utratit, takže nákup nikdy nezvedne strop útraty.
• Oblast api je samostatná peněženka. Kredity aplikace, včetně bezplatné úrovně, klíč nikdy neutratí.
• Útrata se počítá po klíčích, takže spotřeba každého asistenta je vidět zvlášť.
• Předletová kontrola je GET /tokens/balance, pole data.attributes.agent.is_admissible. Blok se objevuje jen u agentních klíčů a příznak přesně zrcadlí middleware připuštění. Čtěte jej místo vlastního porovnávání zůstatku se stropem.
• O připuštění se rozhoduje dřív, než práce vstoupí do fronty, odmítnuté volání tedy nic nestojí.

Barevné a značkové tokeny

start_design bere dva nezávislé seznamy, každý nejvýše o deseti položkách. Pořadí nese roli 60/30/10: první položka je dominantní barva stěn.

colors

brand_selections

Gramatika zní category:level:id[@value][.value]. Část za @ nese slugy hodnot geometrie, jedinečné v rámci kategorie, takže osa, k níž patří, se dohledá a nepíše se do tokenu. Neznámý token je odmítnut kódem 422 a nikdy tiše ignorován.

Průchozí relace

Jedna budova, jedna fotografie, jeden návrh a pak dva dokumenty. Pokyn, který to vytvoří:

Založ budovu s názvem Maple Street 14, nahraj ./front.jpg jako její pohled a spusť návrh s teple šedými stěnami a bílými lištami. Objednej rozpočet a album pro výsledek.

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)

Materiály

• Tato stránka v Markdownu
• Specifikace OpenAPI 3.1 (YAML)
• @getfacade/mcp na npm
• Ozvěte se nám