GetFacaden agenttirajapinta

Pika-aloitus

1. Luo avain

   app.getfacade.ai→Tili→Asetukset→API→Luo avain

   Arvo näytetään kerran eikä sitä voi palauttaa, vain korvata. Kulutuskatto asetetaan luonnin yhteydessä ja se pätee jokaiseen maksulliseen kutsuun.

   Luo agenttiavain

2. Rekisteröi MCP-palvelin

   Yksi merkintä asiakasohjelman asetuksiin ja sen jälkeen uudelleenkäynnistys. Claude Desktop säilyttää sen tiedostossa claude_desktop_config.json; mikä tahansa muu MCP-asiakas ottaa samat kolme kenttää.

   claude_desktop_config.jsonKopioi

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

   Ympäristömuuttujat

   Muuttuja	Pakollinen	Oletusarvo
   GETFACADE_API_KEY	Kyllä	—
   GETFACADE_API_BASE_URL	Ei	https://api.getfacade.ai/api/v1

3. Tai kutsu HTTP-rajapintaa suoraan

   Sama avain toimii bearer-tunnisteena. Pyynnöt ja vastaukset ovat JSON:API-dokumentteja, joissa id on ylimmän tason kenttä eikä koskaan attributes-lohkon sisällä.

   shellKopioi

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

Työkalut

Kaksikymmentäyksi työkalua. MCP-palvelin ei säilytä tilaa eikä omia sääntöjä: jokainen työkalu on yksi tai useampi kutsu vieressä lueteltuihin päätepisteisiin, ja jokaisen viestin, jonka agentti toistaa, kirjoittaa rajapinta.

• create_building

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

  Luo rakennuksen. Nimi on tilin sisällä yksilöllinen ja enintään 50 merkkiä; kaksoiskappale hylätään koodilla 422.

  KutsuuPOST /projects

• upload_photo

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

  Rekisteröi näkymän, lataa tavut esiallekirjoitettuun osoitteeseen, vahvistaa ne ja kysyy tilaa, kunnes kuva hyväksytään tai hylätään. Leveys, korkeus ja md5 lasketaan paikallisesti; kuvasuhteen päättelee palvelin.

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

• start_designasynkroninen

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

  Suunnittelee julkisivun valitussa kuvakulmassa ja näyttää sen valokuvassa: kohteen maassa käyttökelpoiset materiaalit, siellä oikeasti myytävät tuotteet ja pinnan takainen rakenne. Luo suunnitelman, jonottaa työn ja palauttaa työn tunnisteen. Seed on valinnainen: jos se jätetään pois, palvelin luo sen itse ja palauttaa sen.

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

• refine_designasynkroninen

  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 }

  Korjaa sanoin valmista suunnitelmaa. Ohje kohdistuu valmiiseen suunnitelmaan, joten kaikki mitä siinä ei mainita säilyy. Pääkuvakulman korjaus luo uuden suunnitelman, joten aiempi ei koskaan korvaudu.

  KutsuuGET /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? }

  Lukee yhden renderöinnin, kustannusarvion tai albumin tilan.

  KutsuuGET /renders/{render} · GET /estimates/{estimate}

• list_jobs

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

  Tilin viimeisimmät työt, keskeneräiset ensin.

  KutsuuGET /history

• list_designs

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

  Rakennuksen suunnitelmat renderöinteineen. Täältä saadaan renderöintien tunnisteet arviota ja albumia varten.

  KutsuuGET /projects/{project}/concepts

• order_estimateasynkroninen

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

  Hinnoittelee suunnitelman rivi riviltä, materiaaleina ja työnä, sillä hinnalla joka mainituilla materiaaleilla on kohteen maassa. Valuutta ja mittajärjestelmä tulevat oletuksena tuosta maasta.

  KutsuuPOST /projects/{project}/concepts/{concept}/estimates

• order_albumasynkroninen

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

  Dokumentoi suunnitelman rakentavalle porukalle: materiaalit, julkisivun rakenteen, turvallisuushuomiot ja niiden taustalla olevat normit. Vaatii valmiin pääkuvan.

  KutsuuPOST /concepts/{concept}/album/generate

• upscale_renderasynkroninen

  upscale_render(render_id)
    -> { job_id, status }

  Suurentaa valmiin renderin. Maksaa krediittejä ja toimii asynkronisesti.

  KutsuuPOST /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 }] }

  Itse kustannusarvio: summat, niiden taustaoletukset ja jokainen rivi määrineen, yksikköineen ja hintoineen. get_job kertoo arvion tilan, ei koskaan sen sisältöä.

  KutsuuGET /estimates/{estimate}

• add_estimate_line

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

  Lisää kustannusarvioon rivin. Yksiköt tulevat arvion omasta mittajärjestelmästä.

  KutsuuPOST /estimates/{estimate}/items

• update_estimate_line

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

  Muuttaa kustannusarvion riviä. Vain lähetetyt kentät muuttuvat; summat laskee palvelin.

  KutsuuPATCH /estimates/{estimate}/items/{item}

• delete_estimate_line

  delete_estimate_line(estimate_id, line_id)
    -> { deleted }

  Poistaa rivin kustannusarviosta.

  KutsuuDELETE /estimates/{estimate}/items/{item}

• delete_render

  delete_render(render_id)
    -> { deleted }

  Poistaa renderin. Päärenderin poisto palauttaa sen suunnitelman luonnokseksi.

  KutsuuDELETE /renders/{render}

• delete_design

  delete_design(building_id, design_id)
    -> { deleted }

  Poistaa suunnitelman ja sen alla olevat renderit.

  KutsuuDELETE /projects/{project}/concepts/{concept}

• delete_building

  delete_building(building_id)
    -> { deleted }

  Poistaa kohteen kaikkine sisältöineen. Jo käytettyjä krediittejä ei palauteta.

  KutsuuDELETE /projects/{project}

• list_token_packages

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

  Paketit, joita tili voi ostaa, hintoineen ja krediittimäärineen.

  KutsuuGET /tokens/packages

• buy_tokensasynkroninen

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

  Ostaa yhden paketin tämän avaimen lompakkoon. Vaatii osto-oikeudella luodun avaimen eikä ylitä sitä, mitä avain saa vielä kuluttaa.

  KutsuuPOST /tokens/purchase

• get_balance

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

  Agentin lompakko, tämän avaimen katto ja tieto siitä, päästetäänkö seuraava maksullinen kutsu läpi.

  KutsuuGET /tokens/balance

• report_problem

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

  Ilmoittaa tämän rajapinnan viasta: kenttä, joka on kuvattu tässä mutta ei koskaan saavu, hylkäys, jonka sanamuodosta ei seuraa seuraavaa askelta, tulos joka ei vastaa pyydettyä. Maksuton ja hyväksytään tyhjällä saldolla; vastauksena tulee viite, ei vastaus.

  KutsuuPOST /feedback

Todennus ja avaimet

• Avain kulkee bearer-tunnisteena Authorization-otsakkeessa. MCP-palvelin lukee sen muuttujasta GETFACADE_API_KEY eikä lähetä muuta.
• Arvo näytetään kerran, luonnin yhteydessä, ja siitä tallennetaan vain tiiviste. Kierrätys tarkoittaa uuden avaimen luomista ja vanhan mitätöintiä.
• Jokaisella avaimella on kulutuskatto, joka pannaan täytäntöön palvelimella ennen kuin kutsu saavuttaa ohjaimen. Katon täyttyminen pysäyttää sen avaimen, ei tiliä.
• Avaimet eivät hallinnoi avaimia: se on ihmisen toimi, ja kyseiset päätepisteet vastaavat agenttiavaimelle 403.
• Mitätöinti astuu voimaan heti. Mitätöidyllä avaimella tehdyt kutsut vastaavat 401.

Asynkroninen työ ja kysely

• start_design, order_estimate ja order_album palauttavat työn tunnisteen ja päättyvät siihen. Renderöinti kestää minuutteja: kysele GET /renders/{render} tai GET /estimates/{estimate}, kunnes tila on lopullinen.
• Kuvan tarkistuksen valmistumisesta kertoo websocket, jota agentilla ei ole. Kysele GET /angles/{angle}/validation ja lue validation.is_in_progress; älä päättele lopullisuutta itse tilan merkkijonosta.
• Valmis renderöinti ja valmis albumi sijaitsevat pysyvissä julkisissa osoitteissa: ilman allekirjoitusta ja ilman vanhenemista. Linkin voi antaa ihmiselle suoraan, ja se on vastaus pyyntöön ”näytä tulos”. Koska sitä ei ole allekirjoitettu, se ei kysy keneltäkään lupaa: se toimii kaikilla jotka sen saavat, eikä sitä voi perua.
• GET /renders/{render}/download on eri asia: allekirjoitettu URL, joka vanhenee minuuteissa ja kantaa tiedostonimen. Se on tiedoston tallentamiseen, ei jakamiseen.

Nopeusrajat avainta kohti

Agenttiavaimella on omat kiintiönsä, erillään saman tilin ihmisistunnoista, jottei silmukkaan jäänyt agentti syö näytön ääressä olevan ihmisen kiintiötä. Hylkäys on halpa: se tehdään väliohjelmistossa, ennen mitään tietokantatyötä.

Idempotenssi

Maksullinen kutsu luo työn, ja veloitus seuraa työtä. Kutsun nimeäminen on se, mikä saa toiston palauttamaan saman työn sen sijaan, että se loisi toisen.

• Idempotency-Key vaaditaan jokaisessa API-avaimella tehdyssä maksullisessa kutsussa: suunnitelman aloitus tai hienosäätö, renderin suurennus, kustannusarvion tai albumin tilaus, kustannusarvion uudelleenluonti. Ilman sitä kutsu vastaa 422 IDEMPOTENCY_KEY_REQUIRED, eikä mitään mene jonoon.
• Mikä tahansa 8-191 merkin arvo, yksi tilausta kohden; tavallisesti UUID. Uusi tilaus saa uuden arvon: kaksi samanlaista kutsua kahdella arvolla ovat kaksi suunnitelmaa.
• Saman arvon ja saman rungon kanssa toistettu kutsu palauttaa alkuperäisen tilan ja rungon, ja vastauksessa on Idempotent-Replay: true. Mitään ei mene jonoon eikä mitään veloiteta kahdesti.
• Sama arvo eri rungolla vastaa 422 IDEMPOTENCY_KEY_REUSED. Toisto, joka saapuu ensimmäisen kutsun ollessa yhä kesken, vastaa 409 IDEMPOTENCY_IN_PROGRESS: odota ja lähetä sama kutsu uudelleen.
• Mikä tahansa 4xx vapauttaa arvon, joten saman voi lähettää uudelleen, kun syy on korjattu. Arvot muistetaan 24 tuntia, tilikohtaisesti.
• @getfacade/mcp luo arvon ja toistaa kutsun sillä itse, joten työkalukutsussa ei tarvitse välittää mitään.

Virheet

Virheet saapuvat JSON:API-virhedokumentteina. Laravelin validointivastaukset eivät noudata JSON:API-muotoa ja kantavat tekstinsä message-kentässä.

Luettavan tekstin kirjoittaa rajapinta, kutsujan kielellä. Näytä errors[].detail sellaisenaan sen sijaan, että kirjoittaisit oman viestin.

Laskutus ja pääsy

• Maksulliset kutsut käyttävät api-scopen krediittejä, ja pääsy katsoo vain tätä saldoa: jokainen avain maksaa krediiteillä.
• Aktiivinen Pro Plan täydentää api-lompakon 1 000 krediittiin kerran laskutuskaudessa. Sen yli krediitit ostetaan.
• Avain täydentää omaa lompakkoaan vain, jos se luotiin osto-oikeudella, ja enintään sen verran kuin se saa vielä kuluttaa, joten osto ei koskaan nosta kulutuskattoa.
• api-alue on oma lompakkonsa. Sovelluksen krediittejä, ilmaistaso mukaan lukien, avain ei kuluta koskaan.
• Kulutus lasketaan avainkohtaisesti, joten kunkin avustajan käyttö näkyy erikseen.
• Ennakkotarkistus on GET /tokens/balance, kenttä data.attributes.agent.is_admissible. Lohko esiintyy vain agenttiavaimilla, ja lippu heijastaa pääsyn väliohjelmistoa täsmälleen. Lue se sen sijaan, että vertaisit itse saldoa ja kattoa.
• Pääsy ratkaistaan ennen työn asettamista jonoon, joten hylätty kutsu ei kuluta mitään.

Väri- ja merkkitunnisteet

start_design ottaa kaksi toisistaan riippumatonta listaa, kummassakin enintään kymmenen merkintää. Järjestys kantaa 60/30/10-roolia: ensimmäinen merkintä on seinien hallitseva väri.

colors

brand_selections

Kielioppi on category:level:id[@value][.value]. @-merkin jälkeinen osa kantaa geometria-arvojen tunnuksia, jotka ovat kategoriansa sisällä yksilöllisiä, joten niiden akseli haetaan eikä kirjoiteta tunnisteeseen. Tuntematon tunniste hylätään koodilla 422 eikä sitä koskaan ohiteta hiljaisesti.

Läpimenevä istunto

Yksi rakennus, yksi valokuva, yksi suunnitelma ja sitten kaksi dokumenttia. Ohje, joka tuottaa sen:

Luo rakennus nimeltä Maple Street 14, lataa ./front.jpg sen näkymäksi ja käynnistä suunnitelma lämpimän harmailla seinillä ja valkoisilla listoilla. Tilaa tulokselle kustannusarvio ja albumi.

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)

Aineistot

• Tämä sivu Markdownina
• OpenAPI 3.1 -määrittely (YAML)
• @getfacade/mcp npm:ssä
• Ota yhteyttä