# Qwen Image Generation API - Hugging Face Deployment

Deploy the Qwen Image Generation API to Hugging Face Spaces with Docker.

## 🚀 Quick Deploy to Hugging Face Spaces

### Step 1: Create New Space
1. Go to [Hugging Face Spaces](https://huggingface.co/spaces)
2. Click "Create new Space"
3. Choose:
   - **Space name**: `qwen-image-api` (or your preferred name)
   - **License**: MIT
   - **SDK**: Docker
   - **Hardware**: CPU Basic (free tier)

### Step 2: Upload Files
Upload these files to your Space:

**Required Files:**
- `image_server.py` → Main application
- `requirements_image.txt` → Python dependencies  
- `Dockerfile_image_hf` → Rename to `Dockerfile`

**Optional Files:**
- `README_HF_DEPLOY.md` → This documentation
- `test_both_formats.py` → Test script

### Step 3: Rename Dockerfile
In your Space, rename `Dockerfile_image_hf` to `Dockerfile`

### Step 4: Deploy
Hugging Face will automatically build and deploy your Space!

## 📋 File Structure for Hugging Face

```
your-space/
├── Dockerfile              # (renamed from Dockerfile_image_hf)
├── image_server.py          # Main application
├── requirements_image.txt   # Dependencies (renamed to requirements.txt)
└── README.md               # Space documentation
```

## 🔧 Configuration

### Environment Variables
The app automatically configures for Hugging Face:
- **Port**: 7860 (Hugging Face standard)
- **Host**: 0.0.0.0 (accepts all connections)

### API Token
The Hugging Face API token is embedded in the code. For production, consider:
1. Using Hugging Face Secrets for the token
2. Setting environment variable `HF_TOKEN`

## 🎯 API Endpoints

Once deployed, your Space will provide:

### Raw Hugging Face Format
```bash
POST https://your-username-qwen-image-api.hf.space/v1/images/generations
```

**Example:**
```bash
curl -X POST https://your-username-qwen-image-api.hf.space/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over mountains",
    "model": "qwen-image",
    "size": "1024x1024",
    "quality": "standard"
  }'
```

**Response** (Raw Hugging Face format):
```json
{
  "id": "prediction-id",
  "model": "qwen/qwen-image",
  "status": "starting",
  "input": {
    "prompt": "A beautiful sunset over mountains",
    "aspect_ratio": "1:1",
    "output_format": "webp"
  },
  "urls": {
    "stream": "https://stream.replicate.com/...",
    "get": "https://api.replicate.com/...",
    "cancel": "https://api.replicate.com/...",
    "web": "https://replicate.com/..."
  }
}
```

### OpenAI Compatible Format
```bash
POST https://your-username-qwen-image-api.hf.space/v1/images/generations/openai
```

**Example:**
```bash
curl -X POST https://your-username-qwen-image-api.hf.space/v1/images/generations/openai \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A red apple",
    "model": "qwen-image",
    "size": "512x512",
    "response_format": "b64_json"
  }'
```

**Response** (OpenAI format):
```json
{
  "created": 1703123456,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "A red apple"
    }
  ]
}
```

## 🔍 Health & Monitoring

### Health Check
```bash
GET https://your-username-qwen-image-api.hf.space/health
```

### Available Models
```bash
GET https://your-username-qwen-image-api.hf.space/v1/models
```

## 🎨 Supported Parameters

### Image Sizes
- `256x256` - Small images
- `512x512` - Medium images  
- `1024x1024` - Large images (default)
- `1792x1024` - Wide images
- `1024x1792` - Tall images

### Quality Modes
- `standard` - Fast generation (~30 steps)
- `hd` - High quality (~50 steps, slower)

### Response Formats
- `url` - Data URL with base64 image
- `b64_json` - Raw base64 image data

### Styles
- `natural` - More realistic
- `vivid` - More stylized (default)

## 🧪 Testing Your Deployment

After deployment, test with:

```python
import requests

# Test health
response = requests.get("https://your-username-qwen-image-api.hf.space/health")
print(f"Health: {response.json()}")

# Test image generation
response = requests.post(
    "https://your-username-qwen-image-api.hf.space/v1/images/generations/openai",
    json={
        "prompt": "A cute cat",
        "model": "qwen-image",
        "size": "512x512",
        "response_format": "b64_json"
    }
)

if response.status_code == 200:
    data = response.json()
    print("✅ Image generation working!")
    print(f"Base64 length: {len(data['data'][0]['b64_json'])}")
else:
    print(f"❌ Error: {response.text}")
```

## 🔒 Security Notes

- The API doesn't require authentication (public access)
- Rate limiting is handled by Hugging Face Spaces
- For production use, consider adding API key authentication

## 📊 Performance

- **CPU Basic**: Good for testing and light usage
- **CPU Upgrade**: Better for production workloads
- **GPU**: Faster generation (if available)

## 🆘 Troubleshooting

### Build Fails
- Check Dockerfile syntax
- Verify all files are uploaded
- Check requirements_image.txt dependencies

### App Won't Start
- Check logs in Hugging Face Space
- Verify port 7860 is used
- Check environment variables

### API Errors
- Test health endpoint first
- Check request format
- Verify model parameter is "qwen-image"

## 📞 Support

For issues:
1. Check Hugging Face Space logs
2. Test locally first: `python image_server.py`
3. Verify API format matches examples

## 🎉 Success!

Once deployed, you'll have a production-ready image generation API that:
- ✅ Uses only Qwen Image model
- ✅ Provides both raw and OpenAI formats
- ✅ Handles multiple image sizes and qualities
- ✅ Includes health monitoring
- ✅ Ready for integration with any application

Your API will be available at:
`https://your-username-qwen-image-api.hf.space`