Add comprehensive cURL examples for API testing

CURL_EXAMPLES.md

@@ -1,83 +1,152 @@
-# cURL Examples for Colorization API
+# cURL Examples for Image Colorization API
 
 ## Base URL
+Replace `YOUR_SPACE_URL` with your Hugging Face Space URL (e.g., `https://your-space-name.hf.space`)
+
+```bash
+BASE_URL="https://YOUR_SPACE_URL"
+# Or for local testing:
+# BASE_URL="http://localhost:7860"
 ```
-https://logicgoinfotechspaces-text-guided-image-colorization.hf.space
+
+## 1. Health Check
+Check if the API is running and models are loaded:
+
+```bash
+curl -X GET "${BASE_URL}/health"
 ```
 
-## 1. Health Check (No Auth Required)
+**Response:**
+```json
+{
+  "status": "healthy",
+  "model_loaded": true,
+  "model_type": "hf_inference_api",
+  "provider": "fal-ai"
+}
+```
+
+## 2. API Info
+Get API information:
+
 ```bash
-curl -X GET "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/health" \
-  -H "User-Agent: Mozilla/5.0"
+curl -X GET "${BASE_URL}/api"
 ```
 
-## 2. Colorize Image (With Firebase Auth)
+## 3. Colorize Image (with Firebase Auth)
 
-### Using Firebase ID Token
+### With Bearer Token (Firebase ID Token):
 ```bash
-curl -X POST "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize" \
+curl -X POST "${BASE_URL}/colorize" \
   -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
-  -H "User-Agent: Mozilla/5.0" \
-  -F "file=@/path/to/your/image.jpg"
+  -F "file=@path/to/your/image.jpg" \
+  -F "positive_prompt=vibrant natural colors, high quality" \
+  -F "negative_prompt=blurry, low quality" \
+  -F "seed=123" \
+  -F "num_inference_steps=8"
 ```
 
-### Using App Check Token
+### With App Check Token:
 ```bash
-curl -X POST "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize" \
+curl -X POST "${BASE_URL}/colorize" \
   -H "X-Firebase-AppCheck: YOUR_APP_CHECK_TOKEN" \
-  -H "User-Agent: Mozilla/5.0" \
-  -F "file=@/path/to/your/image.jpg"
+  -F "file=@path/to/your/image.jpg" \
+  -F "positive_prompt=vibrant natural colors, high quality"
 ```
 
-### Without Auth (if DISABLE_AUTH=true)
+### Minimal Request (default prompt):
 ```bash
-curl -X POST "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize" \
-  -H "User-Agent: Mozilla/5.0" \
-  -F "file=@/path/to/your/image.jpg" \
-  -o colorized_result.png
+curl -X POST "${BASE_URL}/colorize" \
+  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
+  -F "file=@image.jpg"
 ```
 
-## 3. Windows PowerShell Example
-```powershell
-$imagePath = "C:\projects\colorize_text\pexels-andrey-grushnikov-223358-707676.jpg"
-$headers = @{
-    "User-Agent" = "Mozilla/5.0"
-}
-$form = @{
-    file = Get-Item $imagePath
+**Response:**
+```json
+{
+  "success": true,
+  "result_id": "uuid-here",
+  "caption": "colorize this image with vibrant natural colors, high quality",
+  "download_url": "/results/uuid-here.png",
+  "api_download": "/download/uuid-here"
 }
-Invoke-RestMethod -Uri "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize" `
-    -Method Post `
-    -Headers $headers `
-    -Form $form `
-    -OutFile "colorized_result.png"
 ```
 
-## 4. Python requests Example
-```python
-import requests
+## 4. Download Colorized Image
 
-url = "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize"
-headers = {
-    "User-Agent": "Mozilla/5.0",
-    # "Authorization": "Bearer YOUR_FIREBASE_ID_TOKEN",  # Uncomment if auth enabled
-}
-files = {
-    "file": ("image.jpg", open("path/to/image.jpg", "rb"), "image/jpeg")
-}
+### With Authentication:
+```bash
+curl -X GET "${BASE_URL}/download/RESULT_ID" \
+  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
+  -o colorized_image.png
+```
+
+### Public Access (if available):
+```bash
+curl -X GET "${BASE_URL}/results/FILENAME.png" \
+  -o colorized_image.png
+```
+
+## 5. Complete Workflow Example
+
+```bash
+# 1. Check health
+curl -X GET "${BASE_URL}/health"
 
-response = requests.post(url, headers=headers, files=files)
-if response.status_code == 200:
-    with open("colorized_result.png", "wb") as f:
-        f.write(response.content)
-    print("Colorized image saved!")
-else:
-    print(f"Error: {response.status_code} - {response.text}")
+# 2. Colorize image
+RESPONSE=$(curl -X POST "${BASE_URL}/colorize" \
+  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
+  -F "file=@input.jpg" \
+  -F "positive_prompt=colorize with vibrant natural colors")
+
+# 3. Extract result_id from response
+RESULT_ID=$(echo $RESPONSE | jq -r '.result_id')
+
+# 4. Download the result
+curl -X GET "${BASE_URL}/download/${RESULT_ID}" \
+  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
+  -o output.png
+```
+
+## 6. Testing Without Authentication
+
+If `DISABLE_AUTH=true` is set in environment variables:
+
+```bash
+curl -X POST "${BASE_URL}/colorize" \
+  -F "file=@image.jpg" \
+  -F "positive_prompt=colorize this image"
+```
+
+## 7. Using jq for Pretty JSON Output
+
+```bash
+# Health check with formatted output
+curl -X GET "${BASE_URL}/health" | jq
+
+# Colorize with formatted response
+curl -X POST "${BASE_URL}/colorize" \
+  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
+  -F "file=@image.jpg" | jq
 ```
 
-## Response
-- **Success (200)**: Returns PNG image file
-- **Error (400)**: Bad request (invalid file type)
-- **Error (401)**: Unauthorized (missing/invalid auth token)
-- **Error (503)**: Service unavailable (model not loaded)
+## 8. Error Handling Examples
+
+### Check for errors:
+```bash
+curl -X GET "${BASE_URL}/health" | jq '.model_error'
+```
+
+### Verbose output for debugging:
+```bash
+curl -v -X POST "${BASE_URL}/colorize" \
+  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
+  -F "file=@image.jpg"
+```
 
+## Notes:
+- Replace `YOUR_FIREBASE_ID_TOKEN` with your actual Firebase authentication token
+- Replace `YOUR_SPACE_URL` with your Hugging Face Space URL
+- Image formats supported: JPG, PNG, etc.
+- The API uses Hugging Face Inference API (fal-ai provider) for colorization
+- Default model: `black-forest-labs/FLUX.1-Kontext-dev`