API_DOCUMENTATION.md

# 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