Spaces:
Runtime error
Runtime error
File size: 6,294 Bytes
4c1a7a7 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 | # 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. 实现错误恢复和日志记录 |