PRIVATE_SPACE_GUIDE.md

私有 Hugging Face Spaces 访问指南

🔐 私有 Space 认证说明

当你的 Hugging Face Space 设置为 private 时，可以通过以下方式使用 access token 调用 API：

1. 获取 Hugging Face Access Token

1. 访问 Hugging Face Settings
2. 点击 "New token" 创建新的访问令牌
3. 选择适当的权限（通常选择 "Read" 权限即可）
4. 复制生成的 token（格式为 hf_xxxxxxxxxx）

2. 设置 Space 为私有

1. 进入你的 Space 设置页面
2. 在 "Visibility" 部分选择 Private
3. 保存设置

3. 使用 Access Token 调用 API

方法一：Authorization Bearer Header

curl -X POST https://your-username-space-name.hf.space/screenshot \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hf_your_token_here" \
  -d '{"url": "https://example.com", "width": 1280, "height": 720}' \
  --output screenshot.jpg

方法二：JavaScript 调用

const response = await fetch('https://your-username-space-name.hf.space/screenshot', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer hf_your_token_here'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    width: 1280,
    height: 720,
    quality: 80
  })
});

if (response.ok) {
  const imageBlob = await response.blob();
  // 处理图片数据
} else {
  const error = await response.json();
  console.error('Error:', error);
}

方法三：Python 调用

import requests

url = "https://your-username-space-name.hf.space/screenshot"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer hf_your_token_here"
}
data = {
    "url": "https://example.com",
    "width": 1280,
    "height": 720,
    "quality": 80
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    with open("screenshot.jpg", "wb") as f:
        f.write(response.content)
    print("Screenshot saved successfully")
else:
    print("Error:", response.json())

🔄 认证方式优先级

本 API 支持多种认证方式，按以下优先级处理：

1. Hugging Face Token (Authorization: Bearer hf_xxx) - 最高优先级
2. 自定义 API Key (Authorization: Bearer xxx 或 x-api-key: xxx)

🚨 Token 安全注意事项

✅ 安全实践

• 定期轮换 access token
• 不要在客户端代码中硬编码 token
• 使用环境变量存储 token
• 为不同用途创建不同的 token

❌ 避免的做法

• 不要在 GitHub 等公开仓库中提交 token
• 不要在浏览器控制台中暴露 token
• 不要与他人分享你的 personal access token

📊 私有 Space 的优势

🔒 访问控制

• 只有拥有 token 的用户才能访问
• 可以精确控制 API 使用权限
• 保护敏感的截图服务不被滥用

📈 性能优势

• 更高的速率限制（100 次/15分钟 vs 30 次/15分钟）
• 优先级处理队列
• 更稳定的服务可用性

💰 成本控制

• 避免不必要的 API 调用
• 防止恶意使用导致的资源消耗
• 更好的使用量监控

🛠️ 环境变量配置

如果你想启用自定义 API key 认证，可以在 Space 设置中添加：

# 自定义 API key（可选）
API_KEY=sk-your-secure-api-key-here

注意： 即使没有设置 API_KEY，HF access token 仍然可以正常使用。

🔍 调试和监控

检查认证状态

curl https://your-username-space-name.hf.space/ \
  -H "Authorization: Bearer hf_your_token_here"

响应会显示支持的认证方法：

{
  "message": "Page Screenshot API - Hugging Face Spaces",
  "version": "1.4.0",
  "authentication": {
    "type": "API Key Required",
    "required": true,
    "note": "API key required for screenshot endpoint"
  }
}

服务器状态监控

curl https://your-username-space-name.hf.space/status \
  -H "Authorization: Bearer hf_your_token_here"

🆘 故障排除

401 Unauthorized

• 检查 token 是否正确
• 确认 token 以 hf_ 开头
• 验证 token 长度至少 20 个字符

403 Forbidden

• Token 格式不正确
• Token 可能已过期或被撤销
• 检查 Space 的访问权限设置

示例错误响应

{
  "error": "Unauthorized",
  "message": "Valid API key required. Please provide API key in Authorization header or x-api-key header.",
  "hint": "Use \"Authorization: Bearer YOUR_API_KEY\" or \"x-api-key: YOUR_API_KEY\""
}

📝 最佳实践总结

1. 部署时设置为私有： 在生产环境中始终使用私有 Space
2. 使用环境变量： 通过环境变量管理敏感配置
3. 实施监控： 定期检查 API 使用情况和性能
4. Token 管理： 定期轮换 access token，保持安全性
5. 错误处理： 在客户端代码中正确处理认证错误

通过以上配置，你的私有 Hugging Face Space 将支持安全的 token 认证访问！