feat(auth): accept Firebase Auth id_token (Authorization Bearer) in addition to App Check; add Postman collection and test script; default MODEL_ID to ControlNet color

API_DOCUMENTATION.md

@@ -0,0 +1,494 @@
+# Colorize API Documentation
+
+## Base URL
+
+```
+https://logicgoinfotechspaces-text-guided-image-colorization.hf.space
+```
+
+For local development:
+```
+http://localhost:7860
+```
+
+## Authentication
+
+All endpoints (except `/health` and public result endpoints) require Firebase App Check authentication.
+
+Include the App Check token in the request header:
+```
+X-Firebase-AppCheck: <your-app-check-token>
+```
+
+## Endpoints
+
+### 1. Health Check
+
+Check the health status of the API and model.
+
+**Endpoint:** `GET /health`
+
+**Authentication:** Not required
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "model_loaded": true
+}
+```
+
+**Example:**
+```bash
+curl https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/health
+```
+
+**Response Codes:**
+- `200 OK` - API is healthy
+- `503 Service Unavailable` - Model not loaded
+
+---
+
+### 2. Upload Image
+
+Upload an image and get the uploaded image URL.
+
+**Endpoint:** `POST /upload`
+
+**Authentication:** Required (Firebase App Check token)
+
+**Request:**
+- **Method:** `POST`
+- **Content-Type:** `multipart/form-data`
+- **Headers:**
+  - `X-Firebase-AppCheck: <token>`
+- **Body:**
+  - `file`: Image file (JPEG, PNG, etc.)
+
+**Response:**
+```json
+{
+  "success": true,
+  "image_id": "550e8400-e29b-41d4-a716-446655440000",
+  "image_url": "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/uploads/550e8400-e29b-41d4-a716-446655440000.jpg",
+  "filename": "550e8400-e29b-41d4-a716-446655440000.jpg"
+}
+```
+
+**Example using cURL:**
+```bash
+curl -X POST \
+  https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/upload \
+  -H "X-Firebase-AppCheck: YOUR_APP_CHECK_TOKEN" \
+  -F "file=@/path/to/image.jpg"
+```
+
+**Example using JavaScript:**
+```javascript
+const formData = new FormData();
+formData.append('file', imageFile);
+
+const response = await fetch('https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/upload', {
+  method: 'POST',
+  headers: {
+    'X-Firebase-AppCheck': appCheckToken
+  },
+  body: formData
+});
+
+const result = await response.json();
+console.log(result.image_url);
+```
+
+**Response Codes:**
+- `200 OK` - Image uploaded successfully
+- `400 Bad Request` - Invalid file type or missing file
+- `401 Unauthorized` - Missing or invalid App Check token
+- `500 Internal Server Error` - Server error during upload
+
+---
+
+### 3. Colorize Image
+
+Colorize a grayscale or low-color image using ColorizeNet model.
+
+**Endpoint:** `POST /colorize`
+
+**Authentication:** Required (Firebase App Check token)
+
+**Request:**
+- **Method:** `POST`
+- **Content-Type:** `multipart/form-data`
+- **Headers:**
+  - `X-Firebase-AppCheck: <token>`
+- **Body:**
+  - `file`: Image file (JPEG, PNG, etc.)
+
+**Response:**
+```json
+{
+  "success": true,
+  "result_id": "550e8400-e29b-41d4-a716-446655440000",
+  "download_url": "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/results/550e8400-e29b-41d4-a716-446655440000.jpg",
+  "api_download_url": "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/download/550e8400-e29b-41d4-a716-446655440000",
+  "filename": "550e8400-e29b-41d4-a716-446655440000.jpg"
+}
+```
+
+**Example using cURL:**
+```bash
+curl -X POST \
+  https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize \
+  -H "X-Firebase-AppCheck: YOUR_APP_CHECK_TOKEN" \
+  -F "file=@/path/to/grayscale_image.jpg"
+```
+
+**Example using JavaScript:**
+```javascript
+const formData = new FormData();
+formData.append('file', imageFile);
+
+const response = await fetch('https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize', {
+  method: 'POST',
+  headers: {
+    'X-Firebase-AppCheck': appCheckToken
+  },
+  body: formData
+});
+
+const result = await response.json();
+console.log('Colorized image:', result.download_url);
+// Open in browser: window.open(result.download_url);
+```
+
+**Response Codes:**
+- `200 OK` - Image colorized successfully
+- `400 Bad Request` - Invalid file type or missing file
+- `401 Unauthorized` - Missing or invalid App Check token
+- `503 Service Unavailable` - Colorization model not loaded
+- `500 Internal Server Error` - Error during colorization
+
+**Processing Time:**
+- CPU: ~15-30 seconds
+- GPU: ~5-15 seconds
+
+---
+
+### 4. Download Result (API)
+
+Download the colorized image by file ID using the API endpoint.
+
+**Endpoint:** `GET /download/{file_id}`
+
+**Authentication:** Required (Firebase App Check token)
+
+**Parameters:**
+- `file_id` (path parameter): The result ID returned from `/colorize` endpoint
+
+**Response:**
+- **Content-Type:** `image/jpeg`
+- **Body:** Image file binary data
+
+**Example using cURL:**
+```bash
+curl -X GET \
+  https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/download/550e8400-e29b-41d4-a716-446655440000 \
+  -H "X-Firebase-AppCheck: YOUR_APP_CHECK_TOKEN" \
+  -o colorized_image.jpg
+```
+
+**Example using JavaScript:**
+```javascript
+const response = await fetch(
+  `https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/download/${fileId}`,
+  {
+    headers: {
+      'X-Firebase-AppCheck': appCheckToken
+    }
+  }
+);
+
+const blob = await response.blob();
+const url = URL.createObjectURL(blob);
+// Use the URL to display or download the image
+```
+
+**Response Codes:**
+- `200 OK` - Image downloaded successfully
+- `401 Unauthorized` - Missing or invalid App Check token
+- `404 Not Found` - Result not found
+
+---
+
+### 5. Get Result (Public)
+
+Get the colorized image directly (public endpoint, no authentication required).
+
+**Endpoint:** `GET /results/{filename}`
+
+**Authentication:** Not required
+
+**Parameters:**
+- `filename` (path parameter): The filename returned from `/colorize` endpoint
+
+**Response:**
+- **Content-Type:** `image/jpeg`
+- **Body:** Image file binary data
+
+**Example:**
+```bash
+# Direct browser access
+https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/results/550e8400-e29b-41d4-a716-446655440000.jpg
+```
+
+**Example using HTML:**
+```html
+<img src="https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/results/550e8400-e29b-41d4-a716-446655440000.jpg" alt="Colorized Image">
+```
+
+**Example using JavaScript:**
+```javascript
+// Direct URL - can be opened in browser or used in img tag
+const imageUrl = `https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/results/${filename}`;
+window.open(imageUrl); // Opens in new tab
+```
+
+**Response Codes:**
+- `200 OK` - Image retrieved successfully
+- `404 Not Found` - File not found
+
+---
+
+### 6. Get Uploaded File (Public)
+
+Get an uploaded image directly (public endpoint, no authentication required).
+
+**Endpoint:** `GET /uploads/{filename}`
+
+**Authentication:** Not required
+
+**Parameters:**
+- `filename` (path parameter): The filename returned from `/upload` endpoint
+
+**Response:**
+- **Content-Type:** `image/jpeg`
+- **Body:** Image file binary data
+
+**Example:**
+```bash
+# Direct browser access
+https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/uploads/550e8400-e29b-41d4-a716-446655440000.jpg
+```
+
+**Response Codes:**
+- `200 OK` - Image retrieved successfully
+- `404 Not Found` - File not found
+
+---
+
+## Firebase App Check Integration
+
+### Frontend Setup
+
+```javascript
+import { initializeApp } from "firebase/app";
+import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
+
+const firebaseConfig = {
+  apiKey: "AIzaSyBIB6rcfyyqy5niERTXWvVD714Ter4Vx68",
+  authDomain: "colorize-662df.firebaseapp.com",
+  projectId: "colorize-662df",
+  storageBucket: "colorize-662df.firebasestorage.app",
+  messagingSenderId: "69166278311",
+  appId: "1:69166278311:web:0e8c50b8dd8627aaeadd82",
+  measurementId: "G-58CC2J8XKX"
+};
+
+const app = initializeApp(firebaseConfig);
+
+// Initialize App Check
+const appCheck = initializeAppCheck(app, {
+  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_SITE_KEY'),
+  isTokenAutoRefreshEnabled: true
+});
+
+// Get token for API requests
+async function getAppCheckToken() {
+  const { getToken } = await import('firebase/app-check');
+  try {
+    const token = await getToken(appCheck);
+    return token.token;
+  } catch (error) {
+    console.error('Error getting App Check token:', error);
+    return null;
+  }
+}
+```
+
+### Using the Token
+
+```javascript
+async function colorizeImage(imageFile) {
+  const token = await getAppCheckToken();
+  
+  if (!token) {
+    throw new Error('Failed to get App Check token');
+  }
+  
+  const formData = new FormData();
+  formData.append('file', imageFile);
+  
+  const response = await fetch(
+    'https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize',
+    {
+      method: 'POST',
+      headers: {
+        'X-Firebase-AppCheck': token
+      },
+      body: formData
+    }
+  );
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.detail || 'Colorization failed');
+  }
+  
+  return await response.json();
+}
+```
+
+---
+
+## Error Responses
+
+All error responses follow this format:
+
+```json
+{
+  "detail": "Error message description"
+}
+```
+
+### Common Error Codes
+
+- `400 Bad Request` - Invalid request (missing file, wrong file type, etc.)
+- `401 Unauthorized` - Missing or invalid Firebase App Check token
+- `404 Not Found` - Resource not found (file, result, etc.)
+- `500 Internal Server Error` - Server error during processing
+- `503 Service Unavailable` - Model not loaded or service unavailable
+
+---
+
+## Complete Example: Colorize Image Workflow
+
+### Step 1: Get App Check Token
+
+```javascript
+const token = await getAppCheckToken();
+```
+
+### Step 2: Upload and Colorize
+
+```javascript
+const formData = new FormData();
+formData.append('file', imageFile);
+
+const response = await fetch(
+  'https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize',
+  {
+    method: 'POST',
+    headers: {
+      'X-Firebase-AppCheck': token
+    },
+    body: formData
+  }
+);
+
+const result = await response.json();
+```
+
+### Step 3: Display Result
+
+```javascript
+// Option 1: Use the public URL (no auth needed)
+const imageUrl = result.download_url;
+document.getElementById('result-image').src = imageUrl;
+
+// Option 2: Download via API (requires auth)
+const downloadResponse = await fetch(
+  `https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/download/${result.result_id}`,
+  {
+    headers: {
+      'X-Firebase-AppCheck': token
+    }
+  }
+);
+const blob = await downloadResponse.blob();
+const url = URL.createObjectURL(blob);
+document.getElementById('result-image').src = url;
+```
+
+---
+
+## Rate Limits
+
+- No explicit rate limits set
+- Processing time: 15-30 seconds (CPU) or 5-15 seconds (GPU)
+- Concurrent requests may be queued
+
+## Supported Image Formats
+
+- JPEG (.jpg, .jpeg)
+- PNG (.png)
+- Other formats supported by PIL/Pillow
+
+## Image Size Recommendations
+
+- Maximum recommended: 2048x2048 pixels
+- Images are automatically resized to 512x512 for processing
+- Original aspect ratio is preserved in the output
+
+---
+
+## Testing
+
+### Test Health Endpoint
+
+```bash
+curl https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/health
+```
+
+### Test Colorize Endpoint (with token)
+
+```bash
+curl -X POST \
+  https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize \
+  -H "X-Firebase-AppCheck: YOUR_TOKEN" \
+  -F "file=@test_image.jpg" \
+  -o response.json
+
+cat response.json
+```
+
+---
+
+## Support
+
+For issues or questions:
+1. Check the health endpoint to verify API status
+2. Verify your Firebase App Check token is valid
+3. Check the build logs in Hugging Face Spaces
+4. Ensure the model is loaded (check `/health` endpoint)
+
+---
+
+## Changelog
+
+### Version 1.0.0
+- Initial release
+- Image upload endpoint
+- Image colorization endpoint
+- Firebase App Check integration
+- Public result URLs
+

API_EXAMPLES.md

@@ -0,0 +1,541 @@
+# API Usage Examples
+
+## Python Examples
+
+### Example 1: Colorize Image with Requests
+
+```python
+import requests
+
+# Your Firebase App Check token
+APP_CHECK_TOKEN = "your-app-check-token-here"
+API_BASE_URL = "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space"
+
+# Colorize an image
+def colorize_image(image_path):
+    url = f"{API_BASE_URL}/colorize"
+    headers = {
+        "X-Firebase-AppCheck": APP_CHECK_TOKEN
+    }
+    
+    with open(image_path, "rb") as f:
+        files = {"file": f}
+        response = requests.post(url, headers=headers, files=files)
+    
+    if response.status_code == 200:
+        result = response.json()
+        print(f"Success! Download URL: {result['download_url']}")
+        return result
+    else:
+        print(f"Error: {response.status_code} - {response.text}")
+        return None
+
+# Usage
+result = colorize_image("grayscale_image.jpg")
+if result:
+    print(f"Colorized image available at: {result['download_url']}")
+```
+
+### Example 2: Upload and Colorize
+
+```python
+import requests
+
+APP_CHECK_TOKEN = "your-app-check-token-here"
+API_BASE_URL = "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space"
+
+def upload_and_colorize(image_path):
+    headers = {"X-Firebase-AppCheck": APP_CHECK_TOKEN}
+    
+    # Step 1: Upload image
+    with open(image_path, "rb") as f:
+        files = {"file": f}
+        upload_response = requests.post(
+            f"{API_BASE_URL}/upload",
+            headers=headers,
+            files=files
+        )
+    
+    if upload_response.status_code != 200:
+        print(f"Upload failed: {upload_response.text}")
+        return None
+    
+    upload_result = upload_response.json()
+    print(f"Image uploaded: {upload_result['image_url']}")
+    
+    # Step 2: Colorize the uploaded image
+    with open(image_path, "rb") as f:
+        files = {"file": f}
+        colorize_response = requests.post(
+            f"{API_BASE_URL}/colorize",
+            headers=headers,
+            files=files
+        )
+    
+    if colorize_response.status_code == 200:
+        result = colorize_response.json()
+        print(f"Colorized image: {result['download_url']}")
+        return result
+    else:
+        print(f"Colorization failed: {colorize_response.text}")
+        return None
+
+# Usage
+result = upload_and_colorize("my_image.jpg")
+```
+
+### Example 3: Download Result
+
+```python
+import requests
+
+APP_CHECK_TOKEN = "your-app-check-token-here"
+API_BASE_URL = "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space"
+
+def download_colorized_image(result_id, output_path):
+    url = f"{API_BASE_URL}/download/{result_id}"
+    headers = {"X-Firebase-AppCheck": APP_CHECK_TOKEN}
+    
+    response = requests.get(url, headers=headers)
+    
+    if response.status_code == 200:
+        with open(output_path, "wb") as f:
+            f.write(response.content)
+        print(f"Image saved to: {output_path}")
+        return True
+    else:
+        print(f"Download failed: {response.status_code}")
+        return False
+
+# Usage
+result = colorize_image("input.jpg")
+if result:
+    download_colorized_image(result["result_id"], "colorized_output.jpg")
+```
+
+---
+
+## JavaScript/TypeScript Examples
+
+### Example 1: Colorize Image with Fetch
+
+```javascript
+const API_BASE_URL = 'https://logicgoinfotechspaces-text-guided-image-colorization.hf.space';
+
+async function colorizeImage(imageFile, appCheckToken) {
+  const formData = new FormData();
+  formData.append('file', imageFile);
+  
+  try {
+    const response = await fetch(`${API_BASE_URL}/colorize`, {
+      method: 'POST',
+      headers: {
+        'X-Firebase-AppCheck': appCheckToken
+      },
+      body: formData
+    });
+    
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.detail || 'Colorization failed');
+    }
+    
+    const result = await response.json();
+    console.log('Colorized image URL:', result.download_url);
+    return result;
+  } catch (error) {
+    console.error('Error:', error);
+    throw error;
+  }
+}
+
+// Usage
+const fileInput = document.getElementById('image-input');
+const file = fileInput.files[0];
+
+colorizeImage(file, appCheckToken)
+  .then(result => {
+    // Display the image
+    const img = document.createElement('img');
+    img.src = result.download_url;
+    document.body.appendChild(img);
+  })
+  .catch(error => {
+    console.error('Failed to colorize:', error);
+  });
+```
+
+### Example 2: Complete Workflow with Firebase App Check
+
+```javascript
+import { initializeApp } from "firebase/app";
+import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
+
+// Initialize Firebase
+const firebaseConfig = {
+  apiKey: "AIzaSyBIB6rcfyyqy5niERTXWvVD714Ter4Vx68",
+  authDomain: "colorize-662df.firebaseapp.com",
+  projectId: "colorize-662df",
+  storageBucket: "colorize-662df.firebasestorage.app",
+  messagingSenderId: "69166278311",
+  appId: "1:69166278311:web:0e8c50b8dd8627aaeadd82",
+  measurementId: "G-58CC2J8XKX"
+};
+
+const app = initializeApp(firebaseConfig);
+const appCheck = initializeAppCheck(app, {
+  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_SITE_KEY'),
+  isTokenAutoRefreshEnabled: true
+});
+
+// Get App Check token
+async function getAppCheckToken() {
+  const { getToken } = await import('firebase/app-check');
+  try {
+    const token = await getToken(appCheck);
+    return token.token;
+  } catch (error) {
+    console.error('Error getting App Check token:', error);
+    return null;
+  }
+}
+
+// Colorize image function
+async function colorizeImageWithAppCheck(imageFile) {
+  const token = await getAppCheckToken();
+  
+  if (!token) {
+    throw new Error('Failed to get App Check token');
+  }
+  
+  const formData = new FormData();
+  formData.append('file', imageFile);
+  
+  const response = await fetch(
+    'https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize',
+    {
+      method: 'POST',
+      headers: {
+        'X-Firebase-AppCheck': token
+      },
+      body: formData
+    }
+  );
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.detail || 'Colorization failed');
+  }
+  
+  return await response.json();
+}
+
+// Usage in HTML form
+document.getElementById('colorize-form').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  
+  const fileInput = document.getElementById('image-input');
+  const file = fileInput.files[0];
+  
+  if (!file) {
+    alert('Please select an image');
+    return;
+  }
+  
+  try {
+    const result = await colorizeImageWithAppCheck(file);
+    
+    // Display result
+    const resultImg = document.getElementById('result-image');
+    resultImg.src = result.download_url;
+    resultImg.style.display = 'block';
+    
+    console.log('Colorized image:', result.download_url);
+  } catch (error) {
+    console.error('Error:', error);
+    alert('Failed to colorize image: ' + error.message);
+  }
+});
+```
+
+### Example 3: React Component
+
+```jsx
+import React, { useState } from 'react';
+import { getToken } from 'firebase/app-check';
+
+function ColorizeImage() {
+  const [file, setFile] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [result, setResult] = useState(null);
+  const [error, setError] = useState(null);
+
+  const handleFileChange = (e) => {
+    setFile(e.target.files[0]);
+    setResult(null);
+    setError(null);
+  };
+
+  const handleColorize = async () => {
+    if (!file) {
+      setError('Please select an image');
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      // Get App Check token
+      const token = await getToken(appCheck);
+      
+      const formData = new FormData();
+      formData.append('file', file);
+
+      const response = await fetch(
+        'https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize',
+        {
+          method: 'POST',
+          headers: {
+            'X-Firebase-AppCheck': token.token
+          },
+          body: formData
+        }
+      );
+
+      if (!response.ok) {
+        const errorData = await response.json();
+        throw new Error(errorData.detail || 'Colorization failed');
+      }
+
+      const data = await response.json();
+      setResult(data);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div>
+      <input type="file" accept="image/*" onChange={handleFileChange} />
+      <button onClick={handleColorize} disabled={loading || !file}>
+        {loading ? 'Colorizing...' : 'Colorize Image'}
+      </button>
+      
+      {error && <div className="error">{error}</div>}
+      
+      {result && (
+        <div>
+          <h3>Colorized Image:</h3>
+          <img src={result.download_url} alt="Colorized" />
+          <a href={result.download_url} download>Download</a>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default ColorizeImage;
+```
+
+---
+
+## cURL Examples
+
+### Health Check
+
+```bash
+curl https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/health
+```
+
+### Upload Image
+
+```bash
+curl -X POST \
+  https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/upload \
+  -H "X-Firebase-AppCheck: YOUR_TOKEN" \
+  -F "file=@image.jpg"
+```
+
+### Colorize Image
+
+```bash
+curl -X POST \
+  https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize \
+  -H "X-Firebase-AppCheck: YOUR_TOKEN" \
+  -F "file=@grayscale_image.jpg" \
+  -o response.json
+```
+
+### Download Result
+
+```bash
+# Get result ID from colorize response first
+RESULT_ID="550e8400-e29b-41d4-a716-446655440000"
+
+curl -X GET \
+  https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/download/${RESULT_ID} \
+  -H "X-Firebase-AppCheck: YOUR_TOKEN" \
+  -o colorized_image.jpg
+```
+
+---
+
+## Postman Collection
+
+### Collection JSON
+
+```json
+{
+  "info": {
+    "name": "Colorize API",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "item": [
+    {
+      "name": "Health Check",
+      "request": {
+        "method": "GET",
+        "header": [],
+        "url": {
+          "raw": "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/health",
+          "protocol": "https",
+          "host": ["logicgoinfotechspaces-text-guided-image-colorization", "hf", "space"],
+          "path": ["health"]
+        }
+      }
+    },
+    {
+      "name": "Colorize Image",
+      "request": {
+        "method": "POST",
+        "header": [
+          {
+            "key": "X-Firebase-AppCheck",
+            "value": "{{app_check_token}}",
+            "type": "text"
+          }
+        ],
+        "body": {
+          "mode": "formdata",
+          "formdata": [
+            {
+              "key": "file",
+              "type": "file",
+              "src": []
+            }
+          ]
+        },
+        "url": {
+          "raw": "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize",
+          "protocol": "https",
+          "host": ["logicgoinfotechspaces-text-guided-image-colorization", "hf", "space"],
+          "path": ["colorize"]
+        }
+      }
+    }
+  ],
+  "variable": [
+    {
+      "key": "app_check_token",
+      "value": "your-token-here"
+    }
+  ]
+}
+```
+
+---
+
+## Error Handling Examples
+
+### Python
+
+```python
+import requests
+
+def colorize_with_error_handling(image_path, token):
+    url = "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize"
+    headers = {"X-Firebase-AppCheck": token}
+    
+    try:
+        with open(image_path, "rb") as f:
+            files = {"file": f}
+            response = requests.post(url, headers=headers, files=files, timeout=120)
+        
+        if response.status_code == 200:
+            return response.json()
+        elif response.status_code == 401:
+            raise Exception("Invalid or missing App Check token")
+        elif response.status_code == 400:
+            raise Exception("Invalid file or request")
+        elif response.status_code == 503:
+            raise Exception("Model not loaded, please try again later")
+        else:
+            error = response.json()
+            raise Exception(f"Error {response.status_code}: {error.get('detail', 'Unknown error')}")
+            
+    except requests.exceptions.Timeout:
+        raise Exception("Request timed out. Image processing may take 30-60 seconds.")
+    except requests.exceptions.RequestException as e:
+        raise Exception(f"Network error: {str(e)}")
+```
+
+### JavaScript
+
+```javascript
+async function colorizeWithErrorHandling(imageFile, token) {
+  try {
+    const formData = new FormData();
+    formData.append('file', imageFile);
+    
+    const response = await fetch(
+      'https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/colorize',
+      {
+        method: 'POST',
+        headers: {
+          'X-Firebase-AppCheck': token
+        },
+        body: formData,
+        signal: AbortSignal.timeout(120000) // 120 second timeout
+      }
+    );
+    
+    if (!response.ok) {
+      const error = await response.json();
+      
+      switch (response.status) {
+        case 401:
+          throw new Error('Invalid or missing App Check token');
+        case 400:
+          throw new Error('Invalid file or request');
+        case 503:
+          throw new Error('Model not loaded, please try again later');
+        default:
+          throw new Error(error.detail || `Error ${response.status}: ${response.statusText}`);
+      }
+    }
+    
+    return await response.json();
+  } catch (error) {
+    if (error.name === 'AbortError') {
+      throw new Error('Request timed out. Image processing may take 30-60 seconds.');
+    }
+    throw error;
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Always check health endpoint first** before making requests
+2. **Handle timeouts** - Processing can take 30-60 seconds on CPU
+3. **Cache App Check tokens** - They auto-refresh, but cache them to avoid unnecessary requests
+4. **Use public URLs** for displaying images (no auth needed)
+5. **Handle errors gracefully** - Show user-friendly error messages
+6. **Validate file types** before uploading
+7. **Show loading indicators** during processing
+

app/colorize_model.py

@@ -5,24 +5,26 @@ import logging
 import torch
 import numpy as np
 from PIL import Image
-import cv2
 from diffusers import StableDiffusionControlNetPipeline, ControlNetModel, StableDiffusionXLControlNetPipeline
 from diffusers.utils import load_image
 from transformers import pipeline
 from huggingface_hub import hf_hub_download
+from app.config import settings
 
 logger = logging.getLogger(__name__)
 
 class ColorizeModel:
     """Wrapper for ColorizeNet model"""
     
-    def __init__(self, model_id: str = "rsortino/ColorizeNet"):
+    def __init__(self, model_id: str | None = None):
         """
         Initialize the ColorizeNet model
         
         Args:
             model_id: Hugging Face model ID for ColorizeNet
         """
+        if model_id is None:
+            model_id = settings.MODEL_ID
         self.model_id = model_id
         self.device = "cuda" if torch.cuda.is_available() else "cpu"
         logger.info("Using device: %s", self.device)
@@ -30,11 +32,11 @@ class ColorizeModel:
         
         try:
             # Try loading as ControlNet with Stable Diffusion
-            logger.info("Attempting to load ColorizeNet as ControlNet...")
+            logger.info("Attempting to load model as ControlNet: %s", self.model_id)
             try:
                 # Load ControlNet model
                 self.controlnet = ControlNetModel.from_pretrained(
-                    model_id,
+                    self.model_id,
                     torch_dtype=self.dtype
                 )
                 
@@ -77,7 +79,7 @@ class ColorizeModel:
                 logger.info("Trying to load as image-to-image pipeline...")
                 self.pipe = pipeline(
                     "image-to-image",
-                    model=model_id,
+                    model=self.model_id,
                     device=0 if self.device == "cuda" else -1,
                     torch_dtype=self.dtype
                 )

app/config.py

@@ -18,7 +18,7 @@ class Settings(BaseSettings):
     BASE_URL: str = os.getenv("BASE_URL", "http://localhost:8000")
     
     # Model settings
-    MODEL_ID: str = os.getenv("MODEL_ID", "rsortino/ColorizeNet")
+    MODEL_ID: str = os.getenv("MODEL_ID", "lllyasviel/control_v11f1e_sd15_color")
     NUM_INFERENCE_STEPS: int = int(os.getenv("NUM_INFERENCE_STEPS", "20"))
     
     # Storage settings

app/main.py

@@ -12,7 +12,7 @@ from fastapi.responses import FileResponse, JSONResponse
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
 import firebase_admin
-from firebase_admin import credentials, app_check
+from firebase_admin import credentials, app_check, auth as firebase_auth
 import numpy as np
 import torch
 from PIL import Image
@@ -80,7 +80,7 @@ async def startup_event():
     global colorize_model
     try:
         logger.info("Loading ColorizeNet model...")
-        colorize_model = ColorizeModel()
+        colorize_model = ColorizeModel(settings.MODEL_ID)
         logger.info("ColorizeNet model loaded successfully")
     except Exception as e:
         logger.error("Failed to load ColorizeNet model: %s", str(e))
@@ -94,30 +94,48 @@ async def shutdown_event():
         del colorize_model
     logger.info("Application shutdown")
 
-# Firebase App Check verification
-async def verify_app_check(request: Request):
-    """Verify Firebase App Check token"""
-    if not settings.ENABLE_APP_CHECK:
-        return True
-    
-    app_check_token = request.headers.get("X-Firebase-AppCheck")
-    if not app_check_token:
-        raise HTTPException(
-            status_code=401,
-            detail="Missing App Check token"
-        )
-    
-    try:
-        # Verify the App Check token
-        app_check_claims = app_check.verify_token(app_check_token)
-        logger.info("App Check token verified for: %s", app_check_claims.get("app_id"))
-        return True
-    except Exception as e:
-        logger.warning("App Check token verification failed: %s", str(e))
-        raise HTTPException(
-            status_code=401,
-            detail="Invalid App Check token"
-        )
+def _extract_bearer_token(authorization_header: str | None) -> str | None:
+    if not authorization_header:
+        return None
+    parts = authorization_header.split(" ", 1)
+    if len(parts) == 2 and parts[0].lower() == "bearer":
+        return parts[1].strip()
+    return None
+
+
+async def verify_request(request: Request):
+    """
+    Accept either:
+      - Firebase Auth id_token via Authorization: Bearer <id_token>
+      - Firebase App Check token via X-Firebase-AppCheck (when ENABLE_APP_CHECK=true)
+    """
+    # Try Firebase Auth id_token first if present
+    bearer = _extract_bearer_token(request.headers.get("Authorization"))
+    if bearer:
+        try:
+            decoded = firebase_auth.verify_id_token(bearer)
+            request.state.user = decoded  # make claims available if needed
+            logger.info("Firebase Auth id_token verified for uid: %s", decoded.get("uid"))
+            return True
+        except Exception as e:
+            logger.warning("Auth token verification failed: %s", str(e))
+            # fall through to App Check if enabled
+
+    # If App Check is enabled, require valid App Check token
+    if settings.ENABLE_APP_CHECK:
+        app_check_token = request.headers.get("X-Firebase-AppCheck")
+        if not app_check_token:
+            raise HTTPException(status_code=401, detail="Missing App Check token")
+        try:
+            app_check_claims = app_check.verify_token(app_check_token)
+            logger.info("App Check token verified for: %s", app_check_claims.get("app_id"))
+            return True
+        except Exception as e:
+            logger.warning("App Check token verification failed: %s", str(e))
+            raise HTTPException(status_code=401, detail="Invalid App Check token")
+
+    # Neither token required nor provided → allow (App Check disabled)
+    return True
 
 @app.get("/health")
 async def health_check():
@@ -130,7 +148,7 @@ async def health_check():
 @app.post("/upload")
 async def upload_image(
     file: UploadFile = File(...),
-    verified: bool = Depends(verify_app_check)
+    verified: bool = Depends(verify_request)
 ):
     """
     Upload an image and return the uploaded image URL
@@ -168,7 +186,7 @@ async def upload_image(
 @app.post("/colorize")
 async def colorize_image(
     file: UploadFile = File(...),
-    verified: bool = Depends(verify_app_check)
+    verified: bool = Depends(verify_request)
 ):
     """
     Colorize an uploaded grayscale image using ColorizeNet
@@ -220,7 +238,7 @@ async def colorize_image(
 @app.get("/download/{file_id}")
 async def download_result(
     file_id: str,
-    verified: bool = Depends(verify_app_check)
+    verified: bool = Depends(verify_request)
 ):
     """
     Download the colorized image by file ID

colorize-662df-firebase-adminsdk-fbsvc-bfd21c77c6.json

@@ -0,0 +1,13 @@
+{
+  "type": "service_account",
+  "project_id": "colorize-662df",
+  "private_key_id": "bfd21c77c6a80346288f28b68da364de7dbc3dc2",
+  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC5DYGbqOMFKGrO\n1MToTx/5H2mtT1QxPV+tKbcg9hfmwa+HMun6bk4ME1+ZXfrXaWZ6JQ/q6JhX0SqB\nc7H7Bns2kyUNH7E6IiBSa03izNFJiEW9OSCn613cKh/XtKqNFm5GrSBo++o0aSWw\nEWX2ABeJ1vQBOaMbkjktXJP24XThHV9UotwyTmGiVBXld/K084NdCknknUMNuXaN\nEGogcZ+FGoTPenfft81COOIIao1d4Q3PxUCVYqPzRd/PECjhTxbba9qdg6bd2p12\n4PSy4OKUgkeIYutnF/W6BtMszIuNM5F85bttGPUMog4Kr3HAXKk0ZYRXHJtD7EOo\nnG7BTk/5AgMBAAECggEACw5TBYVIFvlMtFHC9+wuSViGnEumiJCVpEdfQRFi6S7+\nOTIiB4vKju8jYYrbXz5VWIvZURwXafu9seFDK2++McsFxix0DriWPMZbb2b0RBPn\nsr/0gwPNZkeAAoexPt+ts/xI+OzAF+SGU2gest1biqk0h9Q1OgL49oxW7MOYk5Bv\nKNwhlfWD00O2IGOSbn+2aPl3qpCC5U9sTd3xHC2yI0MqD5qSvwn/bnrJoahGFS5W\nO3I7chJqcv3UVffvvuFsR0aaAuJagUkhSzlnbEPTCm5DL+oUHkbsP5t1T6jJ0a0P\n6o185AbjjdDE9ckWKCIUT5FXfxuZOnHOgtt9grT49wKBgQDhlQ3QVsQr9qmpcGHG\n3IdNLvJJ+jybV1EW+dQ9DtOt2plPVKRsiVsUPs+BlAB9tpVVI9y0BPe9B3ABFgwz\n6yX/l1OUZ4NomjjjdcVrCk2HB5mtic33M3zfJuZNtqtWwz33Dg95J0jiIqjYGRaS\n/ZfNCMi8SyjPmVHSjoFzuvWLnwKBgQDSAWbsZ0C8PUzFsjR8t5/mwyu8Ty8IjcCh\nZSAQSxEoXDDmUYGloSzM26VCODRVtl8UcrwhMDfe4qnx9T8UhRr9qAFOg+lVmJ5S\nUb4IdEmFtGEGpXuNGts5txK7MnQkxdkfrBr6ava1eIx2u583RccFcu7tvgMB5bSh\nPpaG5Rn9ZwKBgHuC7BRVXYWgwZZnVPHYDzDgcoK0w3heX6TP1zgzJQ18shJwirJu\npnK4TU9qZLZwQOVkBFSAn9BdASNnGflXV+/QwE9yOc4NGvbXpecMthQnwin1WNNv\n2oAoQVLtoHSZ5BSgGzK/orVGOuJPIkALH5GArMAD+u1nyhgaNKDUDduLAoGBAMW6\nwDfSOCeE6CY0VisfkZTrKuDRBY3eOgM8feYZZ/xCYWBaWeGjUdVI8d7ZoJ0ba4aL\nSQtOpSxc6nqA2XXupa0zZJeSqD4JxvfnMzAunZMgdUKWyS/gm41KDH7pUGXXS0oA\n+B3UXJoc+NRKb+zQ7ET7JHAAukAtEdfIYF5+k+v9AoGAQKJuKD9+yEWjHnEgQkjM\nuSQno7dELoZ6zqVjtQIGz167xvlbRxewPREy2U1xWe9OEUu1EqhdDaiKAXJoQVpx\nEa8wDj1B9eLIR2uO29fIUVtwvFPW+zJJnnhP8S5+XDG8ukrP/FkmX3J4Af9i6ENY\nARf26WMuj3nc6Meclk4fbK0=\n-----END PRIVATE KEY-----\n",
+  "client_email": "firebase-adminsdk-fbsvc@colorize-662df.iam.gserviceaccount.com",
+  "client_id": "107752682517402248855",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token",
+  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-fbsvc%40colorize-662df.iam.gserviceaccount.com",
+  "universe_domain": "googleapis.com"
+}

postman_collection.json

@@ -0,0 +1,172 @@
+{
+  "info": {
+    "name": "Colorize API",
+    "_postman_id": "f3f5d3cc-6a2b-4d2e-9b1e-collection-colorize",
+    "description": "Postman collection for the Colorize Image API (FastAPI). Import this file into Postman.",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "item": [
+    {
+      "name": "Health",
+      "request": {
+        "method": "GET",
+        "header": [],
+        "url": {
+          "raw": "{{base_url}}/health",
+          "host": [
+            "{{base_url}}"
+          ],
+          "path": [
+            "health"
+          ]
+        }
+      }
+    },
+    {
+      "name": "Upload Image",
+      "request": {
+        "method": "POST",
+        "header": [
+          {
+            "key": "X-Firebase-AppCheck",
+            "value": "{{app_check_token}}",
+            "type": "text"
+          }
+        ],
+        "body": {
+          "mode": "formdata",
+          "formdata": [
+            {
+              "key": "file",
+              "type": "file",
+              "src": []
+            }
+          ]
+        },
+        "url": {
+          "raw": "{{base_url}}/upload",
+          "host": [
+            "{{base_url}}"
+          ],
+          "path": [
+            "upload"
+          ]
+        },
+        "description": "Choose an image file in form-data 'file'. Returns image_url and filename."
+      }
+    },
+    {
+      "name": "Colorize Image",
+      "request": {
+        "method": "POST",
+        "header": [
+          {
+            "key": "X-Firebase-AppCheck",
+            "value": "{{app_check_token}}",
+            "type": "text"
+          }
+        ],
+        "body": {
+          "mode": "formdata",
+          "formdata": [
+            {
+              "key": "file",
+              "type": "file",
+              "src": []
+            }
+          ]
+        },
+        "url": {
+          "raw": "{{base_url}}/colorize",
+          "host": [
+            "{{base_url}}"
+          ],
+          "path": [
+            "colorize"
+          ]
+        },
+        "description": "Choose a grayscale (or any) image file in form-data 'file'. Returns download_url and result_id."
+      }
+    },
+    {
+      "name": "Download Result (by result_id)",
+      "request": {
+        "method": "GET",
+        "header": [
+          {
+            "key": "X-Firebase-AppCheck",
+            "value": "{{app_check_token}}",
+            "type": "text"
+          }
+        ],
+        "url": {
+          "raw": "{{base_url}}/download/{{result_id}}",
+          "host": [
+            "{{base_url}}"
+          ],
+          "path": [
+            "download",
+            "{{result_id}}"
+          ]
+        },
+        "description": "Uses the result_id returned by the Colorize Image request."
+      }
+    },
+    {
+      "name": "Get Result (public by filename)",
+      "request": {
+        "method": "GET",
+        "header": [],
+        "url": {
+          "raw": "{{base_url}}/results/{{filename}}",
+          "host": [
+            "{{base_url}}"
+          ],
+          "path": [
+            "results",
+            "{{filename}}"
+          ]
+        },
+        "description": "Direct public URL to image file; no auth required."
+      }
+    }
+    ,
+    {
+      "name": "Get Uploaded (public by filename)",
+      "request": {
+        "method": "GET",
+        "header": [],
+        "url": {
+          "raw": "{{base_url}}/uploads/{{filename}}",
+          "host": [
+            "{{base_url}}"
+          ],
+          "path": [
+            "uploads",
+            "{{filename}}"
+          ]
+        },
+        "description": "Direct public URL to uploaded image file; no auth required."
+      }
+    }
+  ],
+  "variable": [
+    {
+      "key": "base_url",
+      "value": "https://logicgoinfotechspaces-text-guided-image-colorization.hf.space"
+    },
+    {
+      "key": "app_check_token",
+      "value": ""
+    },
+    {
+      "key": "result_id",
+      "value": ""
+    },
+    {
+      "key": "filename",
+      "value": ""
+    }
+  ]
+}
+

test.py

@@ -0,0 +1,134 @@
+import os
+import sys
+import argparse
+import logging
+from pathlib import Path
+
+import requests
+
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger("colorize_test")
+
+
+def normalize_space_url(url: str) -> str:
+    """
+    Accept either a runtime URL (https://<owner>-<space>.hf.space)
+    or a repo URL (https://huggingface.co/spaces/<Owner>/<Space>?logs=container)
+    and return a runtime base URL suitable for API calls.
+    """
+    if not url:
+        return url
+    url = url.strip()
+    # Strip query params
+    if "?" in url:
+        url = url.split("?", 1)[0]
+    # Already runtime URL
+    if ".hf.space" in url:
+        return url.rstrip("/")
+    # Convert repo URL to runtime URL
+    marker = "/spaces/"
+    if "huggingface.co" in url and marker in url:
+        try:
+            _, rest = url.split(marker, 1)
+            owner, space = rest.split("/", 1)
+            runtime = f"https://{owner.lower()}-{space.lower()}.hf.space"
+            return runtime.rstrip("/")
+        except Exception:
+            return url.rstrip("/")
+    return url.rstrip("/")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Test Colorize API")
+    parser.add_argument(
+        "--image",
+        "-i",
+        type=str,
+        required=False,
+        default=r"C:\projects\colorize_text\pexels-andrey-grushnikov-223358-707676.jpg",
+        help="Path to input image file",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=180,
+        help="Request timeout in seconds (default: 180)",
+    )
+    args = parser.parse_args()
+
+    base_url = os.getenv(
+        "BASE_URL",
+        os.getenv(
+            "SPACE_HOST",
+            "http://localhost:7860",
+        ),
+    )
+    base_url = normalize_space_url(base_url)
+    app_check_token = os.getenv("APP_CHECK_TOKEN", "").strip()
+
+    image_path = Path(args.image)
+    if not image_path.exists():
+        logger.error("Image file not found at: %s", str(image_path))
+        sys.exit(1)
+
+    # Health check
+    try:
+        logger.info("Using BASE_URL: %s", base_url)
+        health = requests.get(f"{base_url}/health", timeout=15)
+        logger.info("Health check %s: %s", health.status_code, health.text)
+    except Exception as e:
+        logger.warning("Health check failed: %s", str(e))
+
+    headers = {}
+    if app_check_token:
+        headers["X-Firebase-AppCheck"] = app_check_token
+
+    files = {"file": (image_path.name, open(image_path, "rb"), "application/octet-stream")}
+
+    logger.info("Sending request to %s", f"{base_url}/colorize")
+    try:
+        resp = requests.post(
+            f"{base_url}/colorize",
+            headers=headers,
+            files=files,
+            timeout=args.timeout,
+        )
+    finally:
+        files["file"][1].close()
+
+    logger.info("Response status: %s", resp.status_code)
+    if not resp.ok:
+        logger.error("Error response: %s", resp.text)
+        sys.exit(2)
+
+    data = resp.json()
+    download_url = data.get("download_url")
+    api_download_url = data.get("api_download_url")
+    filename = data.get("filename")
+
+    logger.info("Colorization success: %s", data.get("success"))
+    logger.info("Download URL: %s", download_url)
+    logger.info("API Download URL: %s", api_download_url)
+    logger.info("Filename: %s", filename)
+
+    # Optionally download the result locally
+    if download_url:
+        try:
+            out_path = Path("colorized_result.jpg")
+            r = requests.get(download_url, timeout=60)
+            if r.ok:
+                out_path.write_bytes(r.content)
+                logger.info("Saved colorized image to: %s", str(out_path.resolve()))
+            else:
+                logger.warning("Could not download from public URL, status: %s", r.status_code)
+        except Exception as e:
+            logger.warning("Download via public URL failed: %s", str(e))
+
+
+if __name__ == "__main__":
+    main()
+