Spaces:
Runtime error
Runtime error
|
Download API_GUIDE.md from opclown1/stable-diffusion-img2img: direct link, hf CLI and curl.
- Browser
- Download file 6.29 kB
-
https://huggingface.co/spaces/opclown1/stable-diffusion-img2img/resolve/main/API_GUIDE.md
- Command line
-
hf download hf://spaces/opclown1/stable-diffusion-img2img/API_GUIDE.md
-
curl -L -o API_GUIDE.md https://huggingface.co/spaces/opclown1/stable-diffusion-img2img/resolve/main/API_GUIDE.md
6.29 kB
| # 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. 实现错误恢复和日志记录 |