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

A newer version of the Gradio SDK is available: 6.32.0

Upgrade

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请求

批量处理多个图片

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

响应示例:

{
  "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
}

单张图片处理

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库

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

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调用

// 使用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: 服务器内部错误

错误响应示例:

{
  "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. 实现错误恢复和日志记录