GetFacade aracı API'si

Hızlı başlangıç

1. Bir anahtar oluşturun

   app.getfacade.ai→Hesap→Ayarlar→API→Anahtar oluştur

   Değer bir kez gösterilir; geri alınamaz, yalnızca değiştirilebilir. Harcama tavanı oluşturma anında belirlenir ve her ücretli çağrıda uygulanır.

   Aracı anahtarı oluştur

2. MCP sunucusunu tanımlayın

   İstemci yapılandırmasına tek bir kayıt, sonra istemciyi yeniden başlatın. Claude Desktop bunu claude_desktop_config.json içinde tutar; diğer her MCP istemcisi aynı üç alanı kabul eder.

   claude_desktop_config.jsonKopyala

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

   Ortam değişkenleri

   Değişken	Zorunlu	Varsayılan
   GETFACADE_API_KEY	Evet	—
   GETFACADE_API_BASE_URL	Hayır	https://api.getfacade.ai/api/v1

3. Ya da HTTP API'sini doğrudan çağırın

   Aynı anahtar Bearer jetonu olarak çalışır. İstekler ve yanıtlar JSON:API belgeleridir; id üst düzey bir alandır ve hiçbir zaman attributes içinde yer almaz.

   shellKopyala

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

Araçlar

Yirmi bir araç. MCP sunucusu durum tutmaz ve kendine ait kural taşımaz: her araç, yanında yazan uç noktalara yapılan bir veya birkaç çağrıdır ve aracının aktardığı her mesajı API yazar.

• create_building

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

  Bir bina oluşturur. Ad hesap içinde benzersizdir ve en fazla 50 karakterdir; yinelenen ad 422 ile reddedilir.

  ÇağırırPOST /projects

• upload_photo

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

  Bir görünüm kaydeder, baytları önceden imzalanmış bir adrese yükler, onaylar ve fotoğraf kabul veya reddedilene kadar sorgular. Genişlik, yükseklik ve md5 yerelde hesaplanır; en boy oranını sunucu çıkarır.

  ÇağırırPOST /projects/{project}/angles → PUT (presigned) → POST /angles/{angle}/confirm → GET /angles/{angle}/validation

• start_designeşzamansız

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

  Seçilen görünüş üzerinde cepheyi tasarlar ve fotoğrafta gösterir: binanın bulunduğu ülkede uygulanabilir malzemeler, orada gerçekten satılan ürünler ve yüzeyin ardındaki katman kurgusu. Bir tasarım oluşturur, işi kuyruğa alır ve iş id'sini döndürür. Seed isteğe bağlıdır: verilmezse sunucu kendisi üretir ve geri döndürür.

  ÇağırırPOST /projects/{project}/concepts → POST /concepts/{concept}/angles/{conceptAngle}/renders

• refine_designeşzamansız

  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 }

  Bitmiş bir tasarımı sözle revize eder. Talimat bitmiş tasarıma uygulanır, dolayısıyla değinilmeyen her şey olduğu gibi kalır. Ana görünüşü revize etmek yeni bir tasarım oluşturur, böylece önceki asla üzerine yazılmaz.

  ÇağırırGET /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? }

  Tek bir render'ın, tahminin veya albümün durumunu okur.

  ÇağırırGET /renders/{render} · GET /estimates/{estimate}

• list_jobs

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

  Hesaptaki son işler, tamamlanmamışlar üstte.

  ÇağırırGET /history

• list_designs

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

  Bir binanın tasarımları ve render'ları. Tahmin ve albüm için gereken render kimlikleri buradan gelir.

  ÇağırırGET /projects/{project}/concepts

• order_estimateeşzamansız

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

  Tasarımı kalem kalem, malzeme ve işçilik olarak fiyatlandırır; fiyatlar belirtilen malzemelerin binanın bulunduğu ülkedeki karşılığıdır. Para birimi ve ölçü sistemi varsayılan olarak o ülkeden alınır.

  ÇağırırPOST /projects/{project}/concepts/{concept}/estimates

• order_albumeşzamansız

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

  Tasarımı, uygulamayı yapacak ekip için kayda geçirir: malzemeler, cephenin katman kurgusu, güvenlik notları ve bunların dayandığı normlar. Tamamlanmış bir ana render gerektirir.

  ÇağırırPOST /concepts/{concept}/album/generate

• upscale_rendereşzamansız

  upscale_render(render_id)
    -> { job_id, status }

  Tamamlanmış bir görselleştirmeyi büyütür. Jeton harcar ve asenkron çalışır.

  ÇağırırPOST /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 }] }

  Keşfin kendisi: toplamlar, arkalarındaki varsayımlar ve miktarı, birimi ve fiyatıyla her satır. get_job bir keşfin durumunu bildirir, içeriğini asla.

  ÇağırırGET /estimates/{estimate}

• add_estimate_line

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

  Keşfe bir satır ekler. Birimler keşfin kendi ölçü sisteminden gelir.

  ÇağırırPOST /estimates/{estimate}/items

• update_estimate_line

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

  Keşfin bir satırını değiştirir. Yalnızca gönderilen alanlar değişir; toplamları sunucu yeniden hesaplar.

  ÇağırırPATCH /estimates/{estimate}/items/{item}

• delete_estimate_line

  delete_estimate_line(estimate_id, line_id)
    -> { deleted }

  Keşiften bir satırı kaldırır.

  ÇağırırDELETE /estimates/{estimate}/items/{item}

• delete_render

  delete_render(render_id)
    -> { deleted }

  Bir görselleştirmeyi siler. Ana görselleştirme silinirse tasarımı taslağa döner.

  ÇağırırDELETE /renders/{render}

• delete_design

  delete_design(building_id, design_id)
    -> { deleted }

  Bir tasarımı, altındaki görselleştirmelerle birlikte siler.

  ÇağırırDELETE /projects/{project}/concepts/{concept}

• delete_building

  delete_building(building_id)
    -> { deleted }

  Bir binayı içindeki her şeyle siler. Harcanmış jetonlar iade edilmez.

  ÇağırırDELETE /projects/{project}

• list_token_packages

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

  Bu hesabın satın alabileceği paketler, fiyat ve jeton sayısıyla.

  ÇağırırGET /tokens/packages

• buy_tokenseşzamansız

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

  Bu anahtarın cüzdanına bir paket satın alır. Satın alma izniyle oluşturulmuş bir anahtar gerektirir ve anahtarın hâlâ harcayabileceğini asla aşmaz.

  ÇağırırPOST /tokens/purchase

• get_balance

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

  Aracı cüzdanı, bu anahtarın tavanı ve bir sonraki ücretli çağrının kabul edilip edilmeyeceği.

  ÇağırırGET /tokens/balance

• report_problem

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

  Bu API'deki bir kusuru bildirir: burada anlatılan ama hiç gelmeyen bir alan, ifadesinden sonraki adım çıkmayan bir ret, istenene uymayan bir sonuç. Ücretsizdir ve boş cüzdanla da kabul edilir; geriye bir referans döner, yanıt değil.

  ÇağırırPOST /feedback

Kimlik doğrulama ve anahtarlar

• Anahtar, Authorization başlığında Bearer jetonu olarak taşınır. MCP sunucusu onu GETFACADE_API_KEY değişkeninden okur ve başka bir şey göndermez.
• Değer oluşturma anında bir kez gösterilir ve yalnızca özeti saklanır. Döndürme, yeni bir anahtar oluşturup eskisini iptal etmek demektir.
• Her anahtar bir harcama tavanı taşır; bu tavan, çağrı bir denetleyiciye ulaşmadan önce sunucuda uygulanır. Tavana ulaşmak o anahtarı durdurur, hesabı değil.
• Anahtarlar anahtar yönetmez: bu bir insan eylemidir ve ilgili uç noktalar aracı anahtarına 403 yanıtı verir.
• İptal hemen geçerli olur. İptal edilmiş anahtarla yapılan çağrılar 401 döndürür.

Eşzamansız iş ve durum sorgulama

• start_design, order_estimate ve order_album bir iş kimliği döndürüp biter. Render dakikalar sürer: durum kesinleşene kadar GET /renders/{render} veya GET /estimates/{estimate} sorgulayın.
• Fotoğraf doğrulamasının bittiğini, aracıda bulunmayan bir websocket bildirir. GET /angles/{angle}/validation sorgulayın ve validation.is_in_progress alanını okuyun; kesinliği durum metninden kendiniz çıkarmayın.
• Tamamlanmış render ve albüm kalıcı genel adreslerde durur: imzasız ve süresiz. Bu bağlantı doğrudan bir kişiye verilebilir; «sonucu göster» sorusunun yanıtı budur. İmzasız olduğu için kimseden izin istemez: eline geçen herkeste çalışmayı sürdürür ve sonradan geri alınamaz.
• GET /renders/{render}/download başka bir şeydir: dakikalar içinde geçerliliğini yitiren ve dosya adı taşıyan imzalı bir URL. Dosyayı kaydetmek içindir, paylaşmak için değil.

Anahtar başına hız sınırları

Aracı anahtarının, aynı hesabın insan oturumlarından ayrı kendi kotaları vardır; böylece döngüye giren bir aracı, ekran başındaki kişinin kotasını yemez. Ret ucuzdur: ara katmanda, herhangi bir veritabanı işinden önce verilir.

Idempotency

Ücretli bir çağrı bir iş oluşturur ve ücret işi takip eder. Çağrıya ad vermek, tekrarın ikinci bir iş oluşturmak yerine aynı işi döndürmesini sağlayan şeydir.

• API anahtarıyla yapılan her ücretli çağrıda Idempotency-Key zorunludur: tasarım başlatma veya iyileştirme, render büyütme, keşif ya da albüm siparişi, keşfi yeniden üretme. Başlık olmadan çağrı 422 IDEMPOTENCY_KEY_REQUIRED yanıtı verir ve sıraya hiçbir şey girmez.
• 8 ile 191 karakter arasında herhangi bir değer, sipariş başına bir tane; genellikle UUID kullanılır. Yeni sipariş yeni değer alır: iki değer altındaki iki aynı çağrı, iki tasarımdır.
• Aynı değer ve aynı gövdeyle çağrıyı tekrarlamak, yanıtta Idempotent-Replay: true ile birlikte özgün durumu ve gövdeyi döndürür. Sıraya hiçbir şey girmez ve iki kez ücret alınmaz.
• Aynı değer farklı bir gövdeyle 422 IDEMPOTENCY_KEY_REUSED yanıtı verir. İlk çağrı sürerken gelen tekrar 409 IDEMPOTENCY_IN_PROGRESS yanıtı verir: bekleyin ve aynı çağrıyı yeniden gönderin.
• Herhangi bir 4xx değeri serbest bırakır; neden giderildiğinde aynı değer yeniden gönderilebilir. Değerler hesap bazında 24 saat hatırlanır.
• @getfacade/mcp değeri kendisi üretir ve çağrıyı onunla kendisi yineler, bu yüzden araç çağrısında iletilecek bir şey yoktur.

Hatalar

Başarısızlıklar JSON:API hata belgeleri olarak gelir. Laravel doğrulama yanıtları JSON:API biçiminde değildir ve metinlerini message alanında taşır.

Okunabilir metni API yazar, çağıranın dilinde. errors[].detail alanını olduğu gibi gösterin, kendi mesajınızı kurmayın.

Ücretlendirme ve kabul

• Ücretli çağrılar api kapsamındaki kredilerden düşer ve kabul yalnızca bu bakiyeye bakar: her anahtar kredi öder.
• Etkin bir Pro Plan, api cüzdanını her fatura döneminde bir kez 1.000 krediye tamamlar. Bunun ötesinde krediler satın alınır.
• Bir anahtar kendi cüzdanını yalnızca satın alma izniyle oluşturulmuşsa doldurur ve en fazla hâlâ harcayabileceği kadar; yani satın alma harcama tavanını asla yükseltmez.
• api kapsamı ayrı bir cüzdandır. Uygulamanın kredileri, ücretsiz kademe dahil, bir anahtar tarafından asla harcanmaz.
• Harcama anahtar başına sayılır; böylece her asistanın tüketimi ayrı görünür.
• Ön kontrol GET /tokens/balance, alan data.attributes.agent.is_admissible. Blok yalnızca aracı anahtarlarında bulunur ve bayrak kabul ara katmanını birebir yansıtır. Bakiyeyi tavanla kendiniz karşılaştırmak yerine bu bayrağı okuyun.
• Kabul, iş kuyruğa alınmadan önce verilir; bu yüzden reddedilen çağrı hiçbir şey harcamaz.

Renk ve marka jetonları

start_design, her biri en fazla on kayıtlık iki bağımsız liste alır. Sıra 60/30/10 rolünü taşır: ilk kayıt duvarların baskın rengidir.

colors

brand_selections

Dilbilgisi şudur: category:level:id[@value][.value]. @ işaretinden sonraki bölüm, kendi kategorisi içinde benzersiz olan geometri değeri kısa adlarını taşır; bu yüzden ait oldukları eksen jetona yazılmaz, aranır. Bilinmeyen jeton 422 ile reddedilir, sessizce yok sayılmaz.

Uçtan uca oturum

Bir bina, bir fotoğraf, bir tasarım ve ardından iki belge. Bunu üreten yönerge:

Maple Street 14 adında bir bina oluştur, ./front.jpg dosyasını görünümü olarak yükle ve sıcak gri duvarlar ile beyaz denizliklerle bir tasarım başlat. Sonuç için tahmini ve albümü sipariş et.

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)

Kaynaklar

• Bu sayfa Markdown olarak
• OpenAPI 3.1 belirtimi (YAML)
• npm üzerinde @getfacade/mcp
• Bize ulaşın