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`)

```bash
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:

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

**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 "${BASE_URL}/api"
```

## 3. Colorize Image (with Firebase Auth)

### With Bearer Token (Firebase ID Token):
```bash
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:
```bash
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):
```bash
curl -X POST "${BASE_URL}/colorize" \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
  -F "file=@image.jpg"
```

**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"
}
```

## 4. Download Colorized Image

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

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

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