└── README.md


/README.md:
--------------------------------------------------------------------------------
  1 | # 👁️ FaceSeek [Face Search](https://faceseek.online) API
  2 | 
  3 | ---
  4 | 
  5 | ## 🧠 Overview
  6 | 
  7 | FaceSeek provides an AI-powered [Face Search](https://faceseek.online) API that enables you to find matching faces from large datasets or the web using a single photo.  
  8 | Integrate our facial recognition system into your apps, sites, or backend services easily.
  9 | 
 10 | ---
 11 | 
 12 | ## 🚀 Quick Start
 13 | 
 14 | ### 1️⃣ Set Up Your API Credentials
 15 | Create a `.env` file in your project root with your API credentials:
 16 | 
 17 | ```bash
 18 | API_HOST=https://faceseek.online
 19 | API_KEY=your_api_key_here
 20 | ````
 21 | 
 22 | ### 2️⃣ Install Dependencies
 23 | 
 24 | * For Python:
 25 | 
 26 | ```bash
 27 | pip install gradio_client
 28 | ```
 29 | 
 30 | * For JavaScript:
 31 | 
 32 | ```bash
 33 | npm i -D @gradio/client
 34 | ```
 35 | 
 36 | ---
 37 | 
 38 | ## 🔐 Authentication
 39 | 
 40 | You’ll receive your credentials from the [FaceSeek](https://faceseek.online) team:
 41 | 
 42 | | Variable   | Description                              |
 43 | | ---------- | ---------------------------------------- |
 44 | | `API_HOST` | Base endpoint for your API instance      |
 45 | | `API_KEY`  | Your authentication key for API requests |
 46 | 
 47 | All endpoints require a valid `API_KEY`.
 48 | Pass it in your request payload under the `api_token` or `token` field.
 49 | 
 50 | ---
 51 | 
 52 | ## ⚙️ Endpoints
 53 | 
 54 | | Endpoint        | Method | Description                                               |
 55 | | --------------- | ------ | --------------------------------------------------------- |
 56 | | `/search_face`  | `POST` | Upload an image or image URL to search for matching faces |
 57 | | `/token_status` | `POST` | Check your API key balance and remaining usage quota      |
 58 | 
 59 | ---
 60 | 
 61 | ## 🐍 Python Integration
 62 | 
 63 | ### 1️⃣ Install Dependency
 64 | 
 65 | ```bash
 66 | pip install gradio_client
 67 | ```
 68 | 
 69 | ### 2️⃣ Example Usage
 70 | 
 71 | ```python
 72 | from gradio_client import Client, handle_file
 73 | 
 74 | client = Client(API_HOST)
 75 | 
 76 | # 1. Search Face
 77 | result = client.predict(
 78 |     file=handle_file(IMAGE_FILE_PATH or URL),
 79 |     api_token=API_KEY,
 80 |     is_premium=True,
 81 |     api_name="/search_face"
 82 | )
 83 | print(result)
 84 | 
 85 | # 2. Token Balance
 86 | result = client.predict(
 87 |     token=API_KEY,
 88 |     api_name="/token_status"
 89 | )
 90 | print(result)
 91 | ```
 92 | 
 93 | ---
 94 | 
 95 | ## 💻 JavaScript Integration
 96 | 
 97 | ### 1️⃣ Install Dependency
 98 | 
 99 | ```bash
100 | npm i -D @gradio/client
101 | ```
102 | 
103 | ### 2️⃣ Example Usage
104 | 
105 | ```javascript
106 | import { Client } from "@gradio/client";
107 | 
108 | const client = await Client.connect(API_HOST);
109 | 
110 | // 1. Search Face
111 | const response = await fetch(IMAGE_FILE_PATH or URL);
112 | const exampleImage = await response.blob();
113 | 
114 | const result = await client.predict("/search_face", { 
115 |     file: exampleImage, 
116 |     api_token: API_KEY,
117 |     is_premium: true,
118 | });
119 | console.log(result.data);
120 | 
121 | // 2. Token Balance
122 | const balance = await client.predict("/token_status", { token: API_KEY });
123 | console.log(balance.data);
124 | ```
125 | 
126 | ---
127 | 
128 | ## 🌀 Curl Integration
129 | 
130 | ### 1️⃣ Search Face
131 | 
132 | ```bash
133 | curl -X POST API_HOST/gradio_api/call/search_face -s \
134 |   -H "Content-Type: application/json" \
135 |   -d '{"data": [{"path": IMAGE_URL}, API_KEY, true]}' \
136 |   | awk -F'"' '{ print $4}' \
137 |   | read EVENT_ID; curl -N API_HOST/gradio_api/call/search_face/$EVENT_ID
138 | ```
139 | 
140 | ### 2️⃣ Token Balance
141 | 
142 | ```bash
143 | curl -X POST API_HOST/gradio_api/call/token_status -s \
144 |   -H "Content-Type: application/json" \
145 |   -d '{"data": [API_KEY]}' \
146 |   | awk -F'"' '{ print $4}' \
147 |   | read EVENT_ID; curl -N API_HOST/gradio_api/call/token_status/$EVENT_ID
148 | ```
149 | 
150 | ---
151 | 
152 | ## 📘 Notes
153 | 
154 | * `is_premium`: Set to `true` if you have a premium plan.
155 | * `IMAGE_FILE_PATH or URL`: Can be a local file path or a public image URL.
156 | * Responses are returned in JSON.
157 | * Use `/token_status` to monitor your remaining balance.
158 | 


--------------------------------------------------------------------------------