README.md

metadata

title: Freshly Universal API
colorFrom: green
colorTo: pink
sdk: docker
pinned: false
license: mit

FRESHLY Universal API

Selamat datang di repositori backend resmi FRESHLY API!

API ini dibangun menggunakan FastAPI dan ditenagai oleh model Deep Learning kustom (arsitektur CNN dengan Spatial Attention) yang dilatih dari nol (Training from Scratch). API ini berfungsi sebagai otak utama aplikasi FRESHLY untuk mengklasifikasikan jenis buah/sayur beserta tingkat kematangannya guna mengurangi food waste.

🧠 Spesifikasi Arsitektur Model

Berbeda dengan API pada umumnya yang menggunakan Pre-trained Model (Transfer Learning), model AI FRESHLY dibangun 100% dari awal. Keunggulan utama model kami terletak pada penggunaan Spatial Attention Layer buatan sendiri.

Fitur ini memungkinkan "mata" AI kami untuk berfokus pada titik-titik krusial pada gambar (seperti bercak hitam pembusukan atau transisi warna mentah ke matang), mengabaikan background yang tidak penting, dan menghasilkan akurasi prediksi yang sangat tinggi.

🛠️ Tech Stack & Teknologi

• Framework Backend: FastAPI, Uvicorn
• Machine Learning: TensorFlow, Keras
• Arsitektur Utama: Custom CNN Cascade System
• Deployment: Docker, Hugging Face Spaces

📚 Dokumentasi Interaktif & Uji Coba (Swagger UI)

Bagi tim Frontend atau penguji yang ingin langsung mencoba mengunggah gambar ke AI tanpa perlu menulis kode, silakan akses halaman Swagger UI kami di bawah ini:

👉 Buka Halaman Uji Coba API Interaktif (/docs) ---

🚀 Daftar Endpoint

1. Health Check

Endpoint ini digunakan untuk memastikan server dalam keadaan aktif (cocok dihubungkan dengan UptimeRobot untuk mencegah cold start).

• URL: /health
• Method: GET
• Response: JSON berisi status server.

2. Predict Freshness (Main AI)

Endpoint utama untuk mendeteksi tingkat kematangan buah/sayur. Untuk menjaga akurasi tertinggi, API ini membutuhkan jenis buah yang dipilih oleh pengguna sebagai parameter.

• URL: /predict
• Method: POST
• Body: multipart/form-data
  • fruit_type (String): Tulis salah satu dari kelas yang didukung (contoh: banana, mango, chili).
  • file (File): File gambar buah/sayur.
• Response Contoh:

  {
    "status": "success",
    "data": {
      "detected_fruit": "banana",
      "condition": "ripe",
      "condition_confidence": 98.5
    }
  }
  

💻 Panduan Integrasi (Untuk Tim Frontend)

Berikut adalah contoh implementasi pemanggilan API /predict menggunakan JavaScript (Fetch API) di sisi client:

// 1. Ambil elemen dari HTML
const fileInput = document.getElementById('imageInput');
const file = fileInput.files[0];
const selectedFruit = "banana"; // Sesuai pilihan user di UI (dropdown/icon)

// 2. Siapkan form data
const formData = new FormData();
formData.append("fruit_type", selectedFruit); // Wajib dikirimkan!
formData.append("file", file);

// 3. Panggil API Freshly
fetch("https://freshlyteam-freshly-api.hf.space/predict", {
    method: "POST",
    body: formData
})
.then(response => response.json())
.then(result => {
    console.log("Status:", result.status);
    console.log("Kondisi Buah:", result.data.condition);
})
.catch(error => {
    console.error("Terjadi kesalahan:", error);
});

(Catatan: Ganti URL freshlyteam-freshly-api.hf.space dengan URL Direct Space kalian jika ada perubahan).

🍎 Parameter fruit_type yang Valid

Sangat penting bagi tim Frontend atau Penguji untuk mengirimkan fruit_type dengan ejaan huruf kecil yang tepat. Saat ini, model kami mendukung 6 kelas berikut:

• banana (Pisang)
• mango (Mangga)
• orange (Jeruk)
• chili (Cabai)
• paprika (Paprika)
• tomato (Tomat)

Sistem akan mengembalikan error 400 (Bad Request) atau 422 (Validation Error) jika memasukkan jenis buah selain daftar di atas.

⚙️ Cara Menjalankan Server di Local (Local Development)

Jika tim Frontend ingin menguji API ini secara offline di komputer masing-masing:

# 1. Clone repository
git clone https://huggingface.co/spaces/freshlyTeam/freshly-api

# 2. Install library yang dibutuhkan
pip install -r requirements.txt

# 3. Jalankan server lokal
uvicorn main:app --reload

Server akan berjalan di http://127.0.0.0:8000. Akses http://127.0.0.0:8000/docs untuk Swagger UI lokal.

Developed with 🔥💪 by Tim AI FRESHLY - Coding Camp powered by DBS Foundation 2026