GET /countdown/{date}

公开缓存 60 秒。仅有日期时按 tz 的当天零点计算。访问类别：匿名 API，可携带 Token 使用独立额度

请求参数

datepath必填: YYYY-MM-DD，或带偏移的 ISO 时间; string · YYYY-MM-DD，或带偏移的 ISO 时间 · 最短：8 字符 · 最长：40 字符
titlequery: 可选标题; string · 可选标题 · 默认值："" · 最长：48 字符
themequery: string · 默认值："dark" · 可选：dark、light
tzquery: string · 默认值："UTC" · 最短：1 字符 · 最长：128 字符
_formatquery: 响应格式为 svg、json 或 text。/color/{hex} 默认 JSON，带 curl* 标记的接口默认 SVG。plain 是 text 的别名。未识别的值继续按 Accept 协商。; string · 可选：svg、json、text
_colorquery: 控制 text 响应的 ANSI 颜色。0、false、off、no 关闭；省略或其他值保留。; string · 可选：0、false、off、no

响应

200 倒计时图。_format=json 时返回剩余时间。

image/svg+xml

{
  "type": "string"
}

application/json

{
  "type": "object",
  "properties": {
    "svg": {
      "type": "string"
    }
  },
  "required": [
    "svg"
  ],
  "additionalProperties": {}
}

400 请求校验或执行失败

application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path",
                  "header"
                ]
              },
              "field": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "location",
              "field",
              "code",
              "message"
            ]
          }
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "required": [
    "error"
  ]
}

401 凭据无效、停用、过期或缺少所需 Token

application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path",
                  "header"
                ]
              },
              "field": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "location",
              "field",
              "code",
              "message"
            ]
          }
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "required": [
    "error"
  ]
}

403 需要管理员 Token

application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path",
                  "header"
                ]
              },
              "field": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "location",
              "field",
              "code",
              "message"
            ]
          }
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "required": [
    "error"
  ]
}

413 请求体过大

application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path",
                  "header"
                ]
              },
              "field": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "location",
              "field",
              "code",
              "message"
            ]
          }
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "required": [
    "error"
  ]
}

415 请求内容类型无效

application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path",
                  "header"
                ]
              },
              "field": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "location",
              "field",
              "code",
              "message"
            ]
          }
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "required": [
    "error"
  ]
}

429 请求过于频繁，Retry-After 为建议等待秒数；匿名额度及认证保护在各 Cloudflare 地点近似计数，Token 业务额度使用 D1 原子计数

application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path",
                  "header"
                ]
              },
              "field": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "location",
              "field",
              "code",
              "message"
            ]
          }
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "required": [
    "error"
  ]
}

500 内部执行失败

application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path",
                  "header"
                ]
              },
              "field": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "location",
              "field",
              "code",
              "message"
            ]
          }
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "required": [
    "error"
  ]
}

响应示例

运行命令前，将环境变量 BASE_URL 设置为站点地址。

默认响应是 SVG。下面另有 _format=json 的 JSON 响应。

成功响应

curl --silent --show-error -H 'User-Agent: simpleWebUtils-example/2.0.1' "$BASE_URL"'/countdown/2026-12-31?title=&theme=dark&tz=Asia%2FShanghai'

HTTP 200
content-type: image/svg+xml; charset=utf-8
content-encoding: gzip
cache-control: public, max-age=60

<svg xmlns="http://www.w3.org/2000/svg" width="480" height="160" viewBox="0 0 480 160" role="img" aria-label="倒计时 49天 7时 31分 37秒"><title>倒计时 49天 7时 31分 37秒</title><rect width="480" height="160" rx="16" fill="#0f172a"/><text x="24" y="36" fill="#e2e8f0" font-size="20" font-family="ui-sans-serif,sans-serif">倒计时</text><rect x="24" y="58" width="102" height="72" rx="12" fill="#1e293b"/><text x="75" y="104" fill="#38bdf8" text-anchor="middle" font-size="32" font-family="ui-monospace,monospace">49</text><text x="75" y="122" fill="#94a3b8" text-anchor="middle" font-size="12" font-family="ui-sans-serif,sans-serif">天</text><rect x="138" y="58" width="102" height="72" rx="12" fill="#1e293b"/><text x="189" y="104" fill="#38bdf8" text-anchor="middle" font-size="32" font-family="ui-monospace,monospace">07</text><text x="189" y="122" fill="#94a3b8" text-anchor="middle" font-size="12" font-family="ui-sans-serif,sans-serif">时</text><rect x="252" y="58" width="102" height="72" rx="12" fill="#1e293b"/><text x="303" y="104" fill="#38bdf8" text-anchor="middle" font-size="32" font-family="ui-monospace,monospace">31</text><text x="303" y="122" fill="#94a3b8" text-anchor="middle" font-size="12" font-family="ui-sans-serif,sans-serif">分</text><rect x="366" y="58" width="102" height="72" rx="12" fill="#1e293b"/><text x="417" y="104" fill="#38bdf8" text-anchor="middle" font-size="32" font-family="ui-monospace,monospace">37</text><text x="417" y="122" fill="#94a3b8" text-anchor="middle" font-size="12" font-family="ui-sans-serif,sans-serif">秒</text></svg>

JSON 响应

curl --silent --show-error -H 'User-Agent: simpleWebUtils-example/2.0.1' -H 'Accept: application/json' "$BASE_URL"'/countdown/2026-12-31?title=&theme=dark&tz=Asia%2FShanghai&_format=json'

HTTP 200
content-type: application/json
content-encoding: gzip
cache-control: public, max-age=60

{
  "title": "",
  "timezone": "Asia/Shanghai",
  "target": "2026-12-30T16:00:00.000Z",
  "finished": false,
  "remainingSeconds": 4260696,
  "parts": {
    "days": 49,
    "hours": 7,
    "minutes": 31,
    "seconds": 36
  },
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"480\" height=\"160\" viewBox=\"0 0 480 160\" role=\"img\" aria-label=\"倒计时 49天 7时 31分 36秒\"><title>倒计时 49天 7时 31分 36秒</title><rect width=\"480\" height=\"160\" rx=\"16\" fill=\"#0f172a\"/><text x=\"24\" y=\"36\" fill=\"#e2e8f0\" font-size=\"20\" font-family=\"ui-sans-serif,sans-serif\">倒计时</text><rect x=\"24\" y=\"58\" width=\"102\" height=\"72\" rx=\"12\" fill=\"#1e293b\"/><text x=\"75\" y=\"104\" fill=\"#38bdf8\" text-anchor=\"middle\" font-size=\"32\" font-family=\"ui-monospace,monospace\">49</text><text x=\"75\" y=\"122\" fill=\"#94a3b8\" text-anchor=\"middle\" font-size=\"12\" font-family=\"ui-sans-serif,sans-serif\">天</text><rect x=\"138\" y=\"58\" width=\"102\" height=\"72\" rx=\"12\" fill=\"#1e293b\"/><text x=\"189\" y=\"104\" fill=\"#38bdf8\" text-anchor=\"middle\" font-size=\"32\" font-family=\"ui-monospace,monospace\">07</text><text x=\"189\" y=\"122\" fill=\"#94a3b8\" text-anchor=\"middle\" font-size=\"12\" font-family=\"ui-sans-serif,sans-serif\">时</text><rect x=\"252\" y=\"58\" width=\"102\" height=\"72\" rx=\"12\" fill=\"#1e293b\"/><text x=\"303\" y=\"104\" fill=\"#38bdf8\" text-anchor=\"middle\" font-size=\"32\" font-family=\"ui-monospace,monospace\">31</text><text x=\"303\" y=\"122\" fill=\"#94a3b8\" text-anchor=\"middle\" font-size=\"12\" font-family=\"ui-sans-serif,sans-serif\">分</text><rect x=\"366\" y=\"58\" width=\"102\" height=\"72\" rx=\"12\" fill=\"#1e293b\"/><text x=\"417\" y=\"104\" fill=\"#38bdf8\" text-anchor=\"middle\" font-size=\"32\" font-family=\"ui-monospace,monospace\">36</text><text x=\"417\" y=\"122\" fill=\"#94a3b8\" text-anchor=\"middle\" font-size=\"12\" font-family=\"ui-sans-serif,sans-serif\">秒</text></svg>"
}

错误示例

curl --silent --show-error -H 'User-Agent: simpleWebUtils-example/2.0.1' -H 'Accept: application/json' "$BASE_URL"'/countdown/invalid%20value?title=&theme=dark&tz=Asia%2FShanghai'

HTTP 400
content-type: application/json
content-encoding: gzip
cache-control: no-store

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "时间格式无效",
    "issues": [
      {
        "location": "path",
        "field": "date",
        "code": "invalid_value",
        "message": "时间格式无效"
      }
    ]
  }
}

curl 访问示例

命令行默认返回 SVG，_format=text 得到纯文本。示例展示纯文本输出。

命令与输出

curl --silent --show-error -H 'User-Agent: curl/8.7.1' "$BASE_URL"'/countdown/2026-12-31?title=&theme=dark&tz=Asia%2FShanghai&_color=0&_format=text'

HTTP 200
content-type: text/plain; charset=utf-8
content-encoding: gzip
cache-control: public, max-age=60

title: 
timezone: Asia/Shanghai
target: 2026-12-30T16:00:00.000Z
finished: false
remainingSeconds: 4260695
parts:
  days: 49
  hours: 7
  minutes: 31
  seconds: 35
svg: <svg xmlns="http://www.w3.org/2000/svg" width="480" height="160" viewBox="0 0 480 160" role="img" aria-label="倒计时 49天 7时 31分 35秒"><title>倒计时 49天 7时 31分 35秒</title><rect width="480" height="160" rx="16" fill="#0f172a"/><text x="24" y="36" fill="#e2e8f0" font-size="20" font-family="ui-sans-serif,sans-serif">倒计时</text><rect x="24" y="58" width="102" height="72" rx="12" fill="#1e293b"/><text x="75" y="104" fill="#38bdf8" text-anchor="middle" font-size="32" font-family="ui-monospace,monospace">49</text><text x="75" y="122" fill="#94a3b8" text-anchor="middle" font-size="12" font-family="ui-sans-serif,sans-serif">天</text><rect x="138" y="58" width="102" height="72" rx="12" fill="#1e293b"/><text x="189" y="104" fill="#38bdf8" text-anchor="middle" font-size="32" font-family="ui-monospace,monospace">07</text><text x="189" y="122" fill="#94a3b8" text-anchor="middle" font-size="12" font-family="ui-sans-serif,sans-serif">时</text><rect x="252" y="58" width="102" height="72" rx="12" fill="#1e293b"/><text x="303" y="104" fill="#38bdf8" text-anchor="middle" font-size="32" font-family="ui-monospace,monospace">31</text><text x="303" y="122" fill="#94a3b8" text-anchor="middle" font-size="12" font-family="ui-sans-serif,sans-serif">分</text><rect x="366" y="58" width="102" height="72" rx="12" fill="#1e293b"/><text x="417" y="104" fill="#38bdf8" text-anchor="middle" font-size="32" font-family="ui-monospace,monospace">35</text><text x="417" y="122" fill="#94a3b8" text-anchor="middle" font-size="12" font-family="ui-sans-serif,sans-serif">秒</text></svg>

生成可嵌入的倒计时 SVG

请求参数

响应

响应示例

成功响应

JSON 响应

错误示例

curl 访问示例

命令与输出

在线调试

响应