开发者中心
专业版

REST API

以编程方式创建和控制计时器。可与您的应用、仪表板或自动化工具集成。

身份验证

除 GET /events 外，所有 API 请求都需要通过 Authorization 请求头中的 Bearer 令牌进行身份验证。

您可以从仪表板获取 API 密钥：castimer.com/dashboard/api-keys。 API 密钥适用于专业版和企业版计划。

Authorization: Bearer YOUR_API_KEY

请妥善保管您的 API 密钥，切勿将其暴露在前端 JavaScript 代码或公开仓库中。

基础 URL

https://castimer.com/api/v1

必需请求头

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

API 端点

GET/events

返回即将到期的公共假日和活动列表及其倒计时数据。无需身份验证。

查询参数

参数类型必需描述
yearinteger否按年份筛选。默认：当前年份
regionstring否按区域代码筛选（US, CN, TW, UK, JP, AU）
tzstring否倒计时计算的时区。默认：UTC

请求示例

curl 'https://castimer.com/api/v1/events?region=US&year=2026&tz=America/New_York'

响应示例

{
  "events": [
    {
      "name": "Independence Day",
      "slug": "independence-day",
      "date": "2026-07-04",
      "remaining": {
        "days": 55,
        "hours": 14,
        "minutes": 32,
        "seconds": 18,
        "total_seconds": 4807938
      },
      "passed": false
    },
    {
      "name": "Thanksgiving",
      "slug": "thanksgiving",
      "date": "2026-11-26",
      "remaining": {
        "days": 200,
        "hours": 3,
        "minutes": 12,
        "seconds": 44,
        "total_seconds": 17284364
      },
      "passed": false
    }
  ],
  "timezone": "America/New_York",
  "region": "US"
}
POST/timers

创建新计时器。返回查看器 URL、嵌入 URL 和控制 URL。

请求体

字段类型必需描述
titlestring否显示标题。最多 100 个字符
typeenum是countdown, event, interval
durationinteger条件秒数。type=countdown 时必需
target_datestring条件ISO8601 格式。type=event 时必需
workinteger条件工作秒数。type=interval 时必需
restinteger条件休息秒数。type=interval 时必需
roundsinteger否循环次数。默认：无限
themeenum否light, dark, auto。默认：light
colorstring否十六进制颜色值，不含 #。默认：6C63FF
webhook_urlstring否计时器完成时通知的 URL

请求

curl -X POST 'https://castimer.com/api/v1/timers' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "产品发布倒计时",
    "type": "countdown",
    "duration": 1800,
    "theme": "dark",
    "color": "6C63FF",
    "webhook_url": "https://yourapp.com/webhooks/castimer"
  }'

响应

{
  "timer_id": "tmr_abc123xyz",
  "title": "产品发布倒计时",
  "type": "countdown",
  "duration": 1800,
  "state": "idle",
  "theme": "dark",
  "viewer_url": "https://castimer.com/v/tmr_abc123xyz",
  "embed_url": "https://castimer.com/widget?id=tmr_abc123xyz",
  "control_url": "https://castimer.com/c/tmr_abc123xyz",
  "created_at": "2026-05-10T09:00:00Z",
  "expires_at": "2026-06-09T09:00:00Z"
}
GET/timers/:id

获取计时器的当前状态和详细信息。

请求

curl 'https://castimer.com/api/v1/timers/tmr_abc123xyz' \
  -H "Authorization: Bearer YOUR_API_KEY"

响应

{
  "timer_id": "tmr_abc123xyz",
  "title": "产品发布倒计时",
  "type": "countdown",
  "duration": 1800,
  "remaining_seconds": 1654,
  "state": "running",
  "started_at": "2026-05-10T09:03:00Z",
  "viewer_url": "https://castimer.com/v/tmr_abc123xyz",
  "embed_url": "https://castimer.com/widget?id=tmr_abc123xyz"
}
PATCH/timers/:id/state

控制计时器的播放状态。

请求体

字段类型必需描述
actionenum是start, pause, resume, reset, stop

请求

curl -X PATCH 'https://castimer.com/api/v1/timers/tmr_abc123xyz/state' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "start"}'

响应

{
  "timer_id": "tmr_abc123xyz",
  "state": "running",
  "remaining_seconds": 1800,
  "started_at": "2026-05-10T09:05:00Z"
}
DELETE/timers/:id

永久删除计时器及其所有关联数据。

请求

curl -X DELETE 'https://castimer.com/api/v1/timers/tmr_abc123xyz' \
  -H "Authorization: Bearer YOUR_API_KEY"

响应

{
  "deleted": true,
  "timer_id": "tmr_abc123xyz"
}

错误代码

代码HTTP 状态描述
401UnauthorizedAPI 密钥缺失或无效
403Forbidden当前计划不包含 API 访问权限
404Not Found计时器不存在或已过期
422Unprocessable缺少必需字段或值无效
429Too Many Requests超出速率限制
500Server Error意外错误。请联系支持

错误响应格式

{
  "error": {
    "code": 422,
    "message": "duration is required when type is countdown",
    "field": "duration"
  }
}

速率限制

计划请求/分钟存储计时器
Free—仅公共活动
Pro6050 个活跃计时器
Enterprise600无限制

每个响应中都包含速率限制请求头：X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset

SDK 与库

官方 SDK 正在开发中。在此期间，请直接使用 REST API 或参考以下社区示例。

JavaScript / Node.js

const response = await fetch('https://castimer.com/api/v1/timers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: '团队会议',
    type: 'countdown',
    duration: 900
  })
});
const timer = await response.json();
console.log(timer.viewer_url);

Python

import requests

response = requests.post(
    'https://castimer.com/api/v1/timers',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'title': '团队会议',
        'type': 'countdown',
        'duration': 900
    }
)
timer = response.json()
print(timer['viewer_url'])