CURL_EXAMPLES.md

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)

BASE_URL="https://YOUR_SPACE_URL"
# Or for local testing:
# BASE_URL="http://localhost:7860"

1. Health Check

Check if the API is running and models are loaded:

curl -X GET "${BASE_URL}/health"

Response:

{
  "status": "healthy",
  "model_loaded": true,
  "model_type": "hf_inference_api",
  "provider": "fal-ai"
}

2. API Info

Get API information:

curl -X GET "${BASE_URL}/api"

3. Colorize Image (with Firebase Auth)

With Bearer Token (Firebase ID Token):

curl -X POST "${BASE_URL}/colorize" \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
  -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"

With App Check Token:

curl -X POST "${BASE_URL}/colorize" \
  -H "X-Firebase-AppCheck: YOUR_APP_CHECK_TOKEN" \
  -F "file=@path/to/your/image.jpg" \
  -F "positive_prompt=vibrant natural colors, high quality"

Minimal Request (default prompt):

curl -X POST "${BASE_URL}/colorize" \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
  -F "file=@image.jpg"

Response:

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

4. Download Colorized Image

With Authentication:

curl -X GET "${BASE_URL}/download/RESULT_ID" \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
  -o colorized_image.png

Public Access (if available):

curl -X GET "${BASE_URL}/results/FILENAME.png" \
  -o colorized_image.png

5. Complete Workflow Example

# 1. Check health
curl -X GET "${BASE_URL}/health"

# 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:

curl -X POST "${BASE_URL}/colorize" \
  -F "file=@image.jpg" \
  -F "positive_prompt=colorize this image"

7. Using jq for Pretty JSON Output

# 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

8. Error Handling Examples

Check for errors:

curl -X GET "${BASE_URL}/health" | jq '.model_error'

Verbose output for debugging:

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