text-guided-image-colorization

Running

text-guided-image-colorization / API_DOCUMENTATION.md

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

2ae242d about 1 month ago

preview code

raw

history blame

11.7 kB

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:

{
  "status": "healthy",
  "model_loaded": true
}

Example:

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:

{
  "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:

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:

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:

{
  "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:

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:

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:

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:

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:

# Direct browser access
https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/results/550e8400-e29b-41d4-a716-446655440000.jpg

Example using HTML:

<img src="https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/results/550e8400-e29b-41d4-a716-446655440000.jpg" alt="Colorized Image">

Example using 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:

# 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

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

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:

{
  "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

const token = await getAppCheckToken();

Step 2: Upload and Colorize

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

// 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

curl https://logicgoinfotechspaces-text-guided-image-colorization.hf.space/health

Test Colorize Endpoint (with token)

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:

Check the health endpoint to verify API status
Verify your Firebase App Check token is valid
Check the build logs in Hugging Face Spaces
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