直播列表
GET /api/v1/lives 返回平台上公开可见的圈子直播列表 —— 即将开始、正在直播、中断与已结束(含回放)的直播。
| 项 | 值 |
|---|---|
| 方法与路径 | GET /api/v1/lives |
| 完整地址 | https://ohmy.xin/api/v1/lives |
| 鉴权 | 需要 Bearer 密钥 |
| 请求体 | 无 |
| 响应 | data 为直播对象数组,meta.pagination 为分页信息 |
| 分页 | 游标(cursor)分页,默认每页 20 条,上限 100 条 |
| 可见性 | 仅返回已列入目录、且圈子公开的直播 |
GET /api/v1/lives HTTP/1.1Host: ohmy.xinAuthorization: Bearer omx_live_xxxxxxxx_yyyyyyyy...Accept: application/json鉴权、限流与错误信封遵循统一的接口约定,本页只描述该接口特有的部分。
全部参数都是可选的;不传任何参数时返回默认排序下的第一页。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
limit |
整数 | 20 |
每页条数,取值范围 1–100。超出范围返回 400。 |
cursor |
字符串 | — | 上一页返回的 meta.pagination.next_cursor。不透明字符串,请原样回传。 |
sort |
字符串 | created_at:desc |
排序方式,可选 created_at:desc(按创建时间倒序)或 updated_at:desc(按更新时间倒序)。 |
circle_number |
字符串 | — | 按圈子筛选,填写圈子的 number(最长 32 字符)。 |
state |
字符串 | scheduled,live,interrupted |
按状态筛选,逗号分隔多个值。可选值:scheduled、live、interrupted、ended。 |
scheduled_after |
ISO 8601 时间 | — | 计划开播时间的下界(含)。 |
scheduled_before |
ISO 8601 时间 | — | 计划开播时间的上界(含)。 |
updated_after |
ISO 8601 时间 | — | 更新时间下界(含)。 |
curl -s "https://ohmy.xin/api/v1/lives?limit=2&state=scheduled,live&circle_number=7000101526" \ -H "Authorization: Bearer omx_live_xxxxxxxx_yyyyyyyy..."data[] 字段
Section titled “data[] 字段”data 是一个数组,每个元素代表一场直播。
| 字段 | 类型 | 可为 null | 说明 |
|---|---|---|---|
number |
字符串 | 否 | 直播编号(公开标识)。不返回内部 id。 |
title |
字符串 | 否 | 直播标题。 |
description |
字符串 | 是 | 直播简介;没有时为 null。 |
kind |
字符串 | 否 | 直播类型,当前恒为 video。 |
state |
字符串 | 否 | 状态:scheduled(已排期)、live(直播中)、interrupted(中断)、ended(已结束)。 |
url |
字符串 | 否 | 直播间地址,可直接分享给用户。 |
cover_url |
字符串 | 是 | 封面图地址;没有时为 null。 |
viewer_count |
整数 | 是 | 当前观众数。仅在直播中(live / interrupted)有值,其余状态恒为 null。 |
scheduled_at |
ISO 8601 时间 | 是 | 计划开播时间。 |
started_at |
ISO 8601 时间 | 是 | 实际开播时间。 |
ended_at |
ISO 8601 时间 | 是 | 结束时间。 |
duration_seconds |
整数 | 否 | 直播时长(秒)。未开播或未结束时为 0。 |
replay_available |
布尔 | 否 | 回放是否可用:已结束、回放可见且录制已就绪时为 true。 |
comments_count |
整数 | 否 | 评论数。 |
reminders_count |
整数 | 否 | 提醒预约数。 |
updated_at |
ISO 8601 时间 | 否 | 最近一次更新时间。 |
circle |
对象 | 否 | 直播所属圈子,见下表。 |
host |
对象 | 是 | 主播;无法取得时为 null。 |
circle 字段
Section titled “circle 字段”| 字段 | 类型 | 可为 null | 说明 |
|---|---|---|---|
number |
字符串 | 否 | 圈子编号,可直接用于筛选参数 circle_number。 |
name |
字符串 | 否 | 圈子名称。 |
url |
字符串 | 否 | 圈子主页地址,直播频道视图。 |
avatar_url |
字符串 | 是 | 圈子头像地址。 |
host 字段
Section titled “host 字段”| 字段 | 类型 | 可为 null | 说明 |
|---|---|---|---|
name |
字符串 | 否 | 主播昵称。 |
avatar_url |
字符串 | 是 | 主播头像地址。 |
meta.pagination 字段
Section titled “meta.pagination 字段”| 字段 | 类型 | 可为 null | 说明 |
|---|---|---|---|
limit |
整数 | 否 | 本次实际生效的每页条数。 |
has_more |
布尔 | 否 | 是否还有下一页。 |
next_cursor |
字符串 | 是 | 下一页游标;has_more 为 false 时为 null。 |
{ "data": [ { "number": "9100004", "title": "On air now", "description": "Weekly market outlook", "kind": "video", "state": "live", "url": "https://ohmy.xin/circles/7000101526/lives/9100004", "cover_url": "https://ohmy.xin/circles/7000101526/lives/9100004/card_cover.png?v=1a2b3c4d", "viewer_count": 42, "scheduled_at": null, "started_at": "2024-01-16T10:00:00+08:00", "ended_at": null, "duration_seconds": 0, "replay_available": false, "comments_count": 12, "reminders_count": 7, "updated_at": "2024-01-16T10:30:00+08:00", "circle": { "number": "7000101526", "name": "Crypto Lab", "url": "https://ohmy.xin/circles/7000101526?channel=live", "avatar_url": "https://cdn.ohmy.xin/circles/7000101526/avatar.webp" }, "host": { "name": "Alice", "avatar_url": "https://cdn.ohmy.xin/users/a1b2c3/avatar.webp" } } ], "meta": { "pagination": { "limit": 20, "has_more": false, "next_cursor": null }, "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f" }}游标分页:先取第一页,拿到 meta.pagination.next_cursor,把它原样作为下一页的 cursor 参数,直到 has_more 为 false。
# 第一页curl -s "https://ohmy.xin/api/v1/lives?limit=2" \ -H "Authorization: Bearer omx_live_xxxxxxxx_yyyyyyyy..."
# 下一页 —— 把上一步返回的 next_cursor 原样带上curl -s "https://ohmy.xin/api/v1/lives?limit=2&cursor=eyJzIjoidHJlYXRlZF9hdDpkZXNjIiwiYyI6WyIyMDI0LTAxLTE2VDAyOjAwOjAwWiIsOTEwMDAwNF19" \ -H "Authorization: Bearer omx_live_xxxxxxxx_yyyyyyyy..."一场直播出现在列表里,需要同时满足:
- 直播已被圈主列入直播目录(
directory_listed为真); - 直播状态为
scheduled、live、interrupted或ended之一; - 所属圈子满足:已绑定 Mixin、未休眠、圈子状态为公开。
该接口在统一的错误信封之外,只多一种情况:
| HTTP 状态 | error.code |
触发条件 |
|---|---|---|
400 |
invalid_parameter |
查询参数不合法:limit 越界、sort/state 取值非法、时间格式错误、时间窗口颠倒,或游标无效。 |
400 的 error.details 会逐条列出出错的参数:
{ "error": { "code": "invalid_parameter", "message": "Invalid query parameter: state must contain only: scheduled, live, interrupted, ended.", "details": [ { "param": "state", "reason": "must contain only: scheduled, live, interrupted, ended" } ] }, "meta": { "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f" }}其余状态码(401、429、503、500)的含义见接口约定。
- 接口约定 —— 鉴权、限流、响应信封与错误码
- 快速开始 —— 创建账号、生成密钥、完成第一次调用
- 策略列表 —— 另一个列表接口
- OpenAPI 规范 —— 本接口的机器可读描述(OpenAPI 3.1)