调用 API 前必须先获取 API Key

所有 API 请求均需通过 X-API-Key 请求头进行身份认证。没有有效的 API Key，任何端点都无法调用。

概述

为保障服务稳定性和公平性，ImgRoute API 对不同端点设置了独立的 QPS（每秒请求数）限制。超出限制时，API 会返回 429 Too Many Requests 错误。

限制一览

端点限制说明
上传图片 (POST /upload)10 次/秒获取预签名和实际上传分开计数
列表查询 (GET /list)10 次/秒专业版及以上可用
删除资源 (DELETE /delete)2 次/秒专业版及以上可用
创建相册 (POST /create_album)5 次/秒专业版及以上可用

日配额限制

除了 QPS 限制，还有每日上传配额限制：

  • 免费用户：每日 50 张
  • 专业版：每日 5000 张
  • 旗舰版：每日 50000 张

超出日配额会返回 429 DAILY_LIMIT_REACHED 错误。

处理限流

当遇到限流错误时，建议采取以下策略：

1. 指数退避重试

import time
import requests

def upload_with_retry(file_path, max_retries=5):
    for attempt in range(max_retries):
        try:
            response = upload_file(file_path)
            return response
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:
                wait_time = 2 ** attempt
                time.sleep(wait_time)
            else:
                raise
    raise Exception("Max retries exceeded")

2. 请求排队

import time
import threading

class RequestQueue:
    def __init__(self, qps_limit=10):
        self.qps_limit = qps_limit
        self.interval = 1.0 / qps_limit
        self.last_request = 0
        self.lock = threading.Lock()

    def execute(self, func):
        with self.lock:
            now = time.time()
            elapsed = now - self.last_request
            if elapsed < self.interval:
                time.sleep(self.interval - elapsed)
            self.last_request = time.time()
        return func()

响应头信息

当请求被限流时，响应会包含以下头信息：

头信息说明
Retry-After距离可以重试的秒数
X-RateLimit-Limit当前端点的 QPS 限制
X-RateLimit-Remaining当前窗口剩余请求数

最佳实践

  • 批量操作时使用队列控制请求频率
  • 对非实时性操作使用延迟重试
  • 监控你的请求量，避免达到限制
  • 考虑升级到更高套餐以获得更宽松的限制