API agen GetFacade

Mulai cepat

1. Terbitkan kunci

   app.getfacade.ai→Akun→Pengaturan→API→Buat kunci

   Nilainya ditampilkan satu kali dan tidak dapat dipulihkan, hanya diganti. Batas pengeluaran ditetapkan saat penerbitan dan berlaku pada setiap panggilan berbayar.

   Terbitkan kunci agen

2. Daftarkan server MCP

   Satu entri pada konfigurasi klien, lalu mulai ulang klien. Claude Desktop menyimpannya di claude_desktop_config.json; klien MCP lain menerima tiga bidang yang sama.

   claude_desktop_config.jsonSalin

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

   Variabel lingkungan

   Variabel	Wajib	Nilai bawaan
   GETFACADE_API_KEY	Ya	—
   GETFACADE_API_BASE_URL	Tidak	https://api.getfacade.ai/api/v1

3. Atau panggil API HTTP langsung

   Kunci yang sama berfungsi sebagai token Bearer. Permintaan dan respons berupa dokumen JSON:API, dengan id sebagai bidang tingkat atas dan tidak pernah berada di dalam attributes.

   shellSalin

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

Alat

Dua puluh satu alat. Server MCP tidak menyimpan status maupun aturan sendiri: setiap alat adalah satu atau beberapa panggilan ke endpoint yang tercantum di sampingnya, dan setiap pesan yang diteruskan agen ditulis oleh API.

• create_building

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

  Membuat bangunan. Nama bersifat unik dalam akun dan maksimal 50 karakter; duplikat ditolak dengan 422.

  MemanggilPOST /projects

• upload_photo

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

  Mendaftarkan tampak, mengunggah bita ke URL bertanda tangan, mengonfirmasinya, dan menanyakan status sampai foto diterima atau ditolak. Lebar, tinggi, dan md5 dihitung secara lokal; rasio aspek disimpulkan oleh server.

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

• start_designasinkron

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

  Merancang fasad pada tampilan yang dipilih dan menampilkannya pada foto: material yang dapat dipakai di negara bangunan, produk yang benar-benar dijual di sana, dan susunan lapisan di balik permukaan. Membuat sebuah desain, mengantrekan pekerjaan, lalu mengembalikan id pekerjaan. Seed bersifat opsional: bila dihilangkan, server membuatnya sendiri dan mengembalikannya.

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

• refine_designasinkron

  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 }

  Merevisi desain yang sudah jadi, dengan kata-kata. Instruksi diterapkan pada desain yang sudah jadi, sehingga apa pun yang tidak disebut tetap dipertahankan. Merevisi tampilan utama membuat desain baru, jadi yang sebelumnya tidak pernah tertimpa.

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

  Membaca keadaan satu render, estimasi, atau album.

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

• list_jobs

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

  Tugas terbaru di seluruh akun, yang belum selesai lebih dulu.

  MemanggilGET /history

• list_designs

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

  Desain sebuah bangunan beserta render-nya. Dari sinilah id render untuk estimasi dan album berasal.

  MemanggilGET /projects/{project}/concepts

• order_estimateasinkron

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

  Menghitung biaya desain baris demi baris, dalam material dan tenaga kerja, pada harga material yang disebutkan di negara bangunan. Mata uang dan sistem satuan secara bawaan mengikuti negara itu.

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

• order_albumasinkron

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

  Mencatat desain untuk tim yang membangun: material, susunan lapisan fasad, catatan keselamatan, dan norma yang mendasarinya. Membutuhkan render utama yang sudah selesai.

  MemanggilPOST /concepts/{concept}/album/generate

• upscale_renderasinkron

  upscale_render(render_id)
    -> { job_id, status }

  Memperbesar render yang sudah selesai. Menghabiskan token dan berjalan asinkron.

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

  Estimasi itu sendiri: total, asumsi di baliknya, dan setiap baris dengan jumlah, satuan, dan harga. get_job melaporkan status estimasi, bukan isinya.

  MemanggilGET /estimates/{estimate}

• add_estimate_line

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

  Menambahkan satu baris ke estimasi. Satuannya berasal dari sistem ukur estimasi itu sendiri.

  MemanggilPOST /estimates/{estimate}/items

• update_estimate_line

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

  Mengubah satu baris estimasi. Hanya bidang yang dikirim yang berubah; total dihitung ulang oleh server.

  MemanggilPATCH /estimates/{estimate}/items/{item}

• delete_estimate_line

  delete_estimate_line(estimate_id, line_id)
    -> { deleted }

  Menghapus satu baris dari estimasi.

  MemanggilDELETE /estimates/{estimate}/items/{item}

• delete_render

  delete_render(render_id)
    -> { deleted }

  Menghapus satu render. Menghapus render utama mengembalikan desainnya ke draf.

  MemanggilDELETE /renders/{render}

• delete_design

  delete_design(building_id, design_id)
    -> { deleted }

  Menghapus satu desain beserta render di bawahnya.

  MemanggilDELETE /projects/{project}/concepts/{concept}

• delete_building

  delete_building(building_id)
    -> { deleted }

  Menghapus bangunan beserta seluruh isinya. Token yang sudah terpakai tidak dikembalikan.

  MemanggilDELETE /projects/{project}

• list_token_packages

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

  Paket yang bisa dibeli akun ini, lengkap dengan harga dan jumlah token.

  MemanggilGET /tokens/packages

• buy_tokensasinkron

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

  Membeli satu paket untuk dompet kunci ini. Perlu kunci yang diterbitkan dengan pembelian diaktifkan, dan tidak pernah melampaui yang masih boleh dibelanjakan kunci.

  MemanggilPOST /tokens/purchase

• get_balance

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

  Dompet agen, batas kunci ini, dan apakah panggilan berbayar berikutnya akan diterima.

  MemanggilGET /tokens/balance

• report_problem

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

  Melaporkan cacat pada API ini: bidang yang dijelaskan di sini tetapi tidak pernah datang, penolakan yang kalimatnya tidak menunjukkan langkah berikutnya, hasil yang tidak sesuai permintaan. Gratis dan diterima meski dompet kosong; yang kembali adalah nomor rujukan, bukan balasan.

  MemanggilPOST /feedback

Autentikasi dan kunci

• Kunci dikirim sebagai token Bearer pada header Authorization. Server MCP membacanya dari GETFACADE_API_KEY dan tidak mengirim apa pun selain itu.
• Nilainya ditampilkan sekali, saat penerbitan, dan hanya hash-nya yang disimpan. Rotasi berarti menerbitkan kunci baru dan mencabut yang lama.
• Setiap kunci membawa batas pengeluaran yang diberlakukan di server sebelum panggilan mencapai controller. Batas yang tercapai menghentikan kunci itu, bukan akunnya.
• Kunci tidak mengelola kunci: itu tindakan manusia, dan endpoint tersebut menjawab 403 untuk kunci agen.
• Pencabutan berlaku seketika. Panggilan dengan kunci yang dicabut menjawab 401.

Kerja asinkron dan penanyaan status

• start_design, order_estimate, dan order_album mengembalikan id tugas lalu selesai. Render memakan waktu beberapa menit: tanyakan GET /renders/{render} atau GET /estimates/{estimate} sampai keadaannya final.
• Selesainya validasi foto diumumkan lewat websocket yang tidak dimiliki agen. Tanyakan GET /angles/{angle}/validation dan baca validation.is_in_progress; jangan menyimpulkan sendiri kefinalan dari teks status.
• Render yang selesai dan album yang selesai berada di URL publik permanen: tanpa tanda tangan dan tanpa masa berlaku. Tautan itu bisa diberikan langsung kepada seseorang, dan itulah jawaban atas «tunjukkan hasilnya». Karena tidak ditandatangani, ia tidak meminta izin siapa pun: tetap bekerja bagi siapa saja yang menerimanya dan tidak dapat ditarik kembali.
• GET /renders/{render}/download adalah hal lain: URL bertanda tangan yang kedaluwarsa dalam hitungan menit dan membawa nama berkas. Gunanya untuk menyimpan berkas, bukan untuk membagikannya.

Batas laju per kunci

Kunci agen memiliki kuota sendiri, terpisah dari sesi manusia pada akun yang sama, sehingga agen yang terjebak perulangan tidak menghabiskan jatah orang yang sedang di depan layar. Penolakan itu murah: diputuskan di middleware, sebelum ada kerja basis data.

Idempotensi

Panggilan berbayar membuat sebuah pekerjaan, dan biaya mengikuti pekerjaan itu. Memberi nama pada panggilan adalah yang membuat pengulangan mengembalikan pekerjaan yang sama, bukan membuat yang kedua.

• Idempotency-Key wajib pada setiap panggilan berbayar dengan kunci API: memulai atau menyempurnakan desain, memperbesar render, memesan estimasi atau album, membuat ulang estimasi. Tanpa header itu panggilan menjawab 422 IDEMPOTENCY_KEY_REQUIRED dan tidak ada yang masuk antrean.
• Nilai apa pun sepanjang 8 sampai 191 karakter, satu per pesanan; biasanya UUID. Pesanan baru memakai nilai baru: dua panggilan identik dengan dua nilai adalah dua desain.
• Mengulang panggilan dengan nilai dan body yang sama mengembalikan status dan body aslinya, dengan Idempotent-Replay: true pada respons. Tidak ada yang masuk antrean dan tidak ada yang ditagih dua kali.
• Nilai yang sama dengan body berbeda menjawab 422 IDEMPOTENCY_KEY_REUSED. Pengulangan yang tiba saat panggilan pertama masih berjalan menjawab 409 IDEMPOTENCY_IN_PROGRESS: tunggu, lalu kirim panggilan yang sama lagi.
• Setiap 4xx melepaskan nilai itu, jadi nilai yang sama bisa dikirim lagi setelah penyebabnya diperbaiki. Nilai diingat selama 24 jam, per akun.
• @getfacade/mcp membuat nilai dan mengulang panggilan dengannya sendiri, jadi tidak ada yang perlu diteruskan dalam panggilan tool.

Kesalahan

Kegagalan datang sebagai dokumen kesalahan JSON:API. Respons validasi Laravel tidak berbentuk JSON:API dan membawa teksnya di message.

Teks yang terbaca ditulis oleh API, dalam bahasa pemanggil. Tampilkan errors[].detail apa adanya alih-alih menyusun pesan sendiri.

Penagihan dan penerimaan

• Panggilan berbayar mengambil dari kredit lingkup api, dan admisi hanya melihat saldo itu: setiap kunci membayar dengan kredit.
• Pro Plan aktif mengisi dompet api hingga 1.000 kredit sekali setiap periode penagihan. Di luar itu, kredit dibeli.
• Kunci mengisi dompetnya sendiri hanya jika diterbitkan dengan pembelian diaktifkan, dan paling banyak sebesar yang masih boleh dibelanjakannya, sehingga pembelian tidak pernah menaikkan batas pengeluaran.
• Cakupan api adalah dompet tersendiri. Kredit aplikasi, termasuk tingkat gratis, tidak pernah dipakai oleh kunci.
• Pengeluaran dihitung per kunci, sehingga konsumsi tiap asisten terlihat terpisah.
• Pemeriksaan awal adalah GET /tokens/balance, bidang data.attributes.agent.is_admissible. Blok itu hanya muncul untuk kunci agen, dan flag-nya mencerminkan middleware penerimaan secara persis. Bacalah flag itu, jangan membandingkan sendiri saldo dengan batas.
• Penerimaan diputuskan sebelum pekerjaan masuk antrean, jadi panggilan yang ditolak tidak menghabiskan apa pun.

Token warna dan merek

start_design menerima dua daftar independen, masing-masing paling banyak sepuluh entri. Urutan membawa peran 60/30/10: entri pertama adalah warna dinding yang dominan.

colors

brand_selections

Tata bahasanya adalah category:level:id[@value][.value]. Bagian setelah @ membawa slug nilai geometri yang unik dalam kategorinya, sehingga sumbu pemiliknya dicari, bukan dituliskan pada token. Token tak dikenal ditolak dengan 422 dan tidak pernah diabaikan diam-diam.

Sesi menyeluruh

Satu bangunan, satu foto, satu desain, lalu dua dokumen. Perintah yang menghasilkannya:

Buat bangunan bernama Maple Street 14, unggah ./front.jpg sebagai tampaknya, dan mulai desain dengan dinding abu-abu hangat serta lis putih. Pesan estimasi dan album untuk hasilnya.

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)

Sumber

• Halaman ini dalam Markdown
• Spesifikasi OpenAPI 3.1 (YAML)
• @getfacade/mcp di npm
• Hubungi kami