stable-diffusion-img2img / API_GUIDE.md
opclown1's picture
Upload API_GUIDE.md with huggingface_hub
4c1a7a7 verified
|
Raw History Blame Contribute Delete
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. 实现错误恢复和日志记录