首页 / API 参考

API 参考

11 个接口，全部 GET。Base URL https://api.geektb.com/v1， 响应 application/json，版本 2026-10-15。

健康检查

GET/v1/health

返回网关、转码队列、CDN 边缘与鉴权组件的即时状态。适合做存活探针。

{
  "status": "ok",
  "service": "geektb-video-api",
  "version": "2.3.1",
  "region": "us-west-1",
  "checks": {
    "gateway": "ok",
    "transcoder": "ok",
    "cdn": "ok",
    "auth": "ok"
  }
}

版本

GET/v1/version

deprecations 为空表示没有计划移除的字段。

{
  "api_version": "2026-10-15",
  "service_version": "2.3.1",
  "base_url": "https://api.geektb.com/v1",
  "deprecations": [],
  "changelog": "https://api.geektb.com/changelog.html"
}

运行状态

GET/v1/status

与状态页同源。status 取值：operational / degraded / partial_outage / major_outage。

{
  "status": "operational",
  "components": [
    {
      "name": "api-gateway",
      "region": "us-west-1",
      "status": "operational"
    },
    {
      "name": "transcoder",
      "region": "us-west-1",
      "status": "operational",
      "queue_depth": 3,
      "median_job_sec": 86
    },
    {
      "name": "cdn-edge",
      "region": "us-west-1",
      "status": "operational",
      "hit_ratio_24h": 0.973
    },
    {
      "name": "auth-service",
      "region": "us-west-1",
      "status": "operational"
    }
  ],
  "incidents": [],
  "updated": "2026-11-12"
}

限流阈值

GET/v1/rate-limit

各套餐的每分钟与每日上限。免费额度同时适用于未带密钥的匿名请求（按来源 IP 计）。

{
  "data": [
    {
      "plan": "free",
      "requests_per_minute": 60,
      "daily_quota": "600 次/日",
      "scope": "个人项目、试用",
      "billing": "无需付费",
      "headers": [
        "Retry-After"
      ]
    },
    {
      "plan": "basic",
      "requests_per_minute": 600,
      "daily_quota": "30,000 次/日",
      "scope": "小型服务上线",
      "billing": "按月计费",
      "headers": [
        "Retry-After"
      ]
    },
    {
      "plan": "pro",
      "requests_per_minute": 3000,
      "daily_quota": "不限日请求",
      "scope": "生产环境",
      "billing": "按月计费",
      "headers": [
        "Retry-After"
      ]
    }
  ],
  "meta": {
    "window": "60s",
    "counting": "per API key, per endpoint group",
    "note": "视频列表与元数据接口未带 key 时按来源 IP 计，阈值同 free"
  }
}

视频列表

GET/v1/videos

返回完整片库快照，共 12 条。不含 renditions 明细，列表页只需要展示用的字段，减少响应体积。

{
  "data": [
    {
      "id": "v_8f3a1c",
      "title": "海岸线的第七个清晨",
      "category": "documentary",
      "duration_sec": 642,
      "aspect_ratio": "16:9",
      "views": 184320,
      "published_at": "2026-10-18",
      "status": "ready",
      "poster": "https://cdn.geektb.com/posters/v_8f3a1c.jpg",
      "hls_master": "https://cdn.geektb.com/hls/v_8f3a1c/master.m3u8"
    },
    {
      "id": "v_2b7d40",
      "title": "把老式收音机修好需要几步",
      "category": "tech",
      "duration_sec": 918,
      "aspect_ratio": "16:9",
      "views": 96710,
      "published_at": "2026-10-11",
      "status": "ready",
      "poster": "https://cdn.geektb.com/posters/v_2b7d40.jpg",
      "hls_master": "https://cdn.geektb.com/hls/v_2b7d40/master.m3u8"
    }
  ],
  "meta": {
    "total": 12,
    "snapshot": "2026-11-08",
    "note": "示例已截断",
    "returned": 2
  }
}

分类

GET/v1/videos/{id}

六个分类及其视频数。分类是固定的，不做用户自定义。

{
  "data": [
    {
      "slug": "documentary",
      "name": "纪录片",
      "video_count": 2,
      "description": "长镜头、自然环境声，节奏偏慢"
    },
    {
      "slug": "tech",
      "name": "科技",
      "video_count": 2,
      "description": "拆解、修复、硬件评测"
    },
    {
      "slug": "travel",
      "name": "旅行",
      "video_count": 2,
      "description": "目的地记录与路线"
    },
    {
      "slug": "food",
      "name": "美食",
      "video_count": 2,
      "description": "食材、工艺、厨房实验"
    },
    {
      "slug": "music",
      "name": "音乐",
      "video_count": 2,
      "description": "演奏、合成器、电台"
    },
    {
      "slug": "sport",
      "name": "运动",
      "video_count": 2,
      "description": "跑步、攀岩、户外"
    }
  ],
  "meta": {
    "total": 6,
    "snapshot": "2026-11-08"
  }
}

转码档位

GET/v1/categories

固定六档阶梯。源片低于目标档位时不向上转码，因此个别老片没有 2160p。

{
  "data": [
    {
      "quality": "360p",
      "width": 640,
      "height": 360,
      "video_codec": "h264",
      "profile": "baseline",
      "video_bitrate_kbps": 700,
      "audio": "aac-lc 64k"
    },
    {
      "quality": "540p",
      "width": 960,
      "height": 540,
      "video_codec": "h264",
      "profile": "main",
      "video_bitrate_kbps": 1400,
      "audio": "aac-lc 96k"
    },
    {
      "quality": "720p",
      "width": 1280,
      "height": 720,
      "video_codec": "h264",
      "profile": "high",
      "video_bitrate_kbps": 2800,
      "audio": "aac-lc 128k"
    },
    {
      "quality": "1080p",
      "width": 1920,
      "height": 1080,
      "video_codec": "h264",
      "profile": "high",
      "video_bitrate_kbps": 4800,
      "audio": "aac-lc 128k"
    },
    {
      "quality": "1080p50",
      "width": 1920,
      "height": 1080,
      "video_codec": "hevc",
      "profile": "main10",
      "video_bitrate_kbps": 3600,
      "audio": "aac-lc 128k"
    },
    {
      "quality": "2160p",
      "width": 3840,
      "height": 2160,
      "video_codec": "hevc",
      "profile": "main10",
      "video_bitrate_kbps": 12000,
      "audio": "aac-lc 192k"
    }
  ],
  "meta": {
    "ladder": "固定六档，源片低于目标档位时不向上转码",
    "container": "HLS (fMP4 segments, 6s)",
    "encryption": "AES-128，key 由 /v1/streams 签发",
    "snapshot": "2026-11-08"
  }
}

合集

GET/v1/renditions

items 的顺序即播放顺序。

{
  "data": [
    {
      "id": "pl_coast",
      "name": "海岸线系列",
      "items": [
        {
          "id": "v_8f3a1c",
          "title": "海岸线的第七个清晨"
        },
        {
          "id": "v_63d0fa",
          "title": "江南小镇的一场雨"
        }
      ],
      "description": "纪录片合集，按拍摄时间排序"
    },
    {
      "id": "pl_fix",
      "name": "修复现场",
      "items": [
        {
          "id": "v_2b7d40",
          "title": "把老式收音机修好需要几步"
        },
        {
          "id": "v_b9427e",
          "title": "拆解一台 1998 年的笔记本"
        }
      ],
      "description": "拆解与修复"
    },
    {
      "id": "pl_kitchen",
      "name": "厨房实验室",
      "items": [
        {
          "id": "v_c41e07",
          "title": "v_c41e07"
        },
        {
          "id": "v_1f8a63",
          "title": "手冲咖啡的水温实验"
        }
      ],
      "description": null
    },
    {
      "id": "pl_night",
      "name": "夜间频道",
      "items": [
        {
          "id": "v_a1b8c4",
          "title": "深夜电台：关于失眠的三十分钟"
        },
        {
          "id": "v_7e6c15",
          "title": "城市夜跑的十公里"
        }
      ],
      "description": "适合睡前播放"
    }
  ],
  "meta": {
    "total": 4,
    "note": "顺序即播放顺序"
  }
}

单个视频

GET/v1/playlists

含 renditions 明细、所属合集、音轨与字幕。ID 不存在时返回 404 video_not_found。

{
  "data": [
    {
      "id": "v_8f3a1c",
      "title": "海岸线的第七个清晨",
      "category": "documentary",
      "duration_sec": 642,
      "aspect_ratio": "16:9",
      "views": 184320,
      "published_at": "2026-10-18",
      "status": "ready",
      "poster": "https://cdn.geektb.com/posters/v_8f3a1c.jpg",
      "hls_master": "https://cdn.geektb.com/hls/v_8f3a1c/master.m3u8",
      "renditions": [
        {
          "quality": "1080p",
          "width": 1920,
          "height": 1080,
          "codec": "h264",
          "bitrate_kbps": 4800,
          "url": "https://cdn.geektb.com/hls/v_8f3a1c/1080p/index.m3u8"
        },
        {
          "quality": "720p",
          "width": 1280,
          "height": 720,
          "codec": "h264",
          "bitrate_kbps": 2800,
          "url": "https://cdn.geektb.com/hls/v_8f3a1c/720p/index.m3u8"
        },
        {
          "quality": "360p",
          "width": 640,
          "height": 360,
          "codec": "h264",
          "bitrate_kbps": 700,
          "url": "https://cdn.geektb.com/hls/v_8f3a1c/360p/index.m3u8"
        }
      ],
      "playlists": [
        "pl_coast"
      ],
      "audio_tracks": [
        {
          "language": "zh-CN",
          "codec": "aac-lc",
          "channels": 2
        }
      ],
      "subtitles": [
        {
          "language": "zh-CN",
          "format": "webvtt"
        }
      ]
    }
  ]
}

签发播放地址

GET/v1/streams

需要 Authorization: Bearer <token>。未携带返回 401 missing_api_key，携带但无效返回 401 invalid_api_key。

返回带签名的 manifest_url、过期时间与当前会话的档位上限。

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Missing Authorization header."
  }
}

带宽与用量

GET/v1/usage

需要 Authorization: Bearer <token>。

近 24 小时的请求数、出流量、边缘命中率与按视频的 TOP 分布。

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Missing Authorization header."
  }
}