# HF Space API使用指南 ## 1. 激活ZeroGPU 在Space设置中: 1. 进入你的Space: `https://huggingface.co/spaces/YOUR_USERNAME/stable-diffusion-pipeline/settings` 2. 在"Settings"页面找到"ZeroGPU" 3. 点击激活免费ZeroGPU访问 4. 重启Space使其生效 ## 2. 设置Secrets 必需的Secrets: | Key | 值 | 是否必需 | |-----|-----|---------| | `HUGGINGFACE_TOKEN` | 你的HF访问令号 | 必需(对于私有模型) | 添加方法: 1. 进入Space设置页面 2. 点击"Settings" -> "Variables and Secrets" 3. 点击"New secret" 4. 输入键名和值 5. 点击"Save" ## 3. API调用示例 ### HTTP POST请求 #### 批量处理多个图片 ```bash curl -X POST \ -F "prompt=transform to anime style" \ -F "negative_prompt=blurry, bad quality" \ -F "strength=0.6" \ -F "guidance_scale=7.5" \ -F "num_inference_steps=20" \ -F "seed=42" \ -F "max_images=10" \ -F "images=@/path/to/image1.jpg" \ -F "images=@/path/to/image2.png" \ -F "images=@/path/to/image3.png" \ https://YOUR_USERNAME-stable-diffusion-pipeline.hf.space/api/batch ``` 响应示例: ```json { "status": "success", "message": "Processed 3 images successfully", "outputs": [ { "input": "image1.jpg", "output": "/tmp/generated_output_0.png", "download_url": "https://...", "generation_time": 5.23 }, { "input": "image2.png", "output": "/tmp/generated_output_1.png", "download_url": "https://...", "generation_time": 5.18 }, { "input": "image3.png", "output": "/tmp/generated_output_2.png", "download_url": "https://...", "generation_time": 5.31 } ], "total_time": 15.72 } ``` #### 单张图片处理 ```bash curl -X POST \ -F "prompt=add snow to the scene" \ -F "strength=0.5" \ -F "num_inference_steps=25" \ -F "images=@/path/to/image.jpg" \ https://YOUR_USERNAME-stable-diffusion-pipeline.hf.space/api/single ``` ### Python调用 #### 使用requests库 ```python import requests # API基础URL API_URL = "https://YOUR_USERNAME-stable-diffusion-pipeline.hf.space" # 批量处理 def batch_process images(image_paths, prompt, **kwargs): files = [('images', open(path, 'rb')) for path in image_paths] data = {'prompt': prompt, **kwargs} try: response = requests.post( f"{API_URL}/api/batch", files=files, data=data ) response.raise_for_status() return response.json() finally: for _, file in files: file.close() # 使用示例 result = batch_process([ 'input1.jpg', 'input2.png' ], prompt="transform to watercolor painting", strength=0.6, num_inference_steps=20) print(result) ``` #### 使用huggingface_hub ```python from huggingface_hub import InferenceClient client = InferenceClient( model="YOUR_USERNAME/stable-diffusion-pipeline", token="YOUR_HF_TOKEN" ) # 单张图片处理 from PIL import Image input_image = Image.open("input.jpg") output = client.img2img( prompt="transform to anime style", image=input_image, strength=0.6 ) output.save("output.png") ``` ### JavaScript调用 ```javascript // 使用Fetch API async function batchProcessImages(imageFiles, prompt) { const formData = new FormData(); imageFiles.forEach(file => { formData.append('images', file); }); formData.append('prompt', prompt); formData.append('strength', '0.6'); formData.append('num_inference_steps', '20'); const response = await fetch( 'https://YOUR_USERNAME-stable-diffusion-pipeline.hf.space/api/batch', { method: 'POST', body: formData } ); const result = await response.json(); return result; } // 使用示例 const inputFiles = [file1, file2, file3]; const result = await batchProcessImages(inputFiles, 'apply vintage filter'); console.log(result); ``` ## 4. 参数说明 | 参数 | 类型 | 默认值 | 说明 | |-----|------|--------|------| | `prompt` | string | 必需 | 正向提示词,描述想要的图像效果 | | `negative_prompt` | string | "blurry, bad quality" | 负向提示词,不想要的元素 | | `strength` | float | 0.6 | 0-1之间,值越大变化越大 | | `guidance_scale` | float | 7.5 | 提示词对图像的影响程度 | | `num_inference_steps` | int | 20 | 去噪步数,越多质量越好但越慢 | | `seed` | int | None | 随机种子,None则随机 | | `max_images` | int | 10 | 批量处理的最大图片数 | | `images` | files | 必需 | 要处理的图片文件 | | `model_id` | string | "stabilityai/sd-turbo" | 使用的模型ID | ## 5. 错误处理 常见的HTTP状态码: - `200`: 成功 - `400`: 请求参数错误 - `413`: 图片过大或图片数量过多 - `429`: 请求过于频繁 - `500`: 服务器内部错误 错误响应示例: ```json { "status": "error", "message": "No images provided or format not supported" } ``` ## 6. 性能优化建议 1. **批量处理**: 一次发送多张图片而不是多次单张请求 2. **合理设置参数**: - `num_inference_steps`: 20-50步之间平衡质量和速度 - `strength`: 0.5-0.7适用于大多数场景 3. **图片大小**: 建议输入图片不超过1024x1024 4. **使用SD-Turbo**: 比标准SD-1.5快5-10倍 ## 7. 限制和配额 ZeroGPU的限制: - 单个请求最大: ~10秒GPU时间 - 每小时最大: ~100张图片(根据模型和参数) - 超过后会排队或返回错误 解决方案: - 分批处理大任务 - 使用更快的模型(sd-turbo) - 优化参数减少计算量 ## 8. 监控和日志 查看Space日志: 1. 访问Space页面 2. 点击"Logs"标签 3. 查看实时日志输出 ## 9. 常见问题 **Q: 请求超时怎么办?** A: 减少图片数量或使用更快的模型(sd-turbo) **Q: 如何处理私有模型?** A: 在Secrets中添加HUGGINGFACE_TOKEN并确保已接受模型许可 **Q: ZeroGPU额度用完了怎么办?** A: ZeroGPU是免费的,额度会自动恢复。可以等待或使用标准GPU(需付费) **Q: 如何自定义模型?** A: 修改app.py中的`DEFAULT_MODEL`变量或通过`model_id`参数指定 ## 10. 最佳实践 1. 添加适当的超时处理 2. 实现重试机制(指数退避) 3. 缓存结果避免重复处理 4. 使用进度反馈提升用户体验 5. 实现错误恢复和日志记录