跳转到内容

直播列表

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.1
Host: ohmy.xin
Authorization: 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 是一个数组,每个元素代表一场直播。

字段 类型 可为 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。
字段 类型 可为 null 说明
number 字符串 否 圈子编号,可直接用于筛选参数 circle_number。
name 字符串 否 圈子名称。
url 字符串 否 圈子主页地址,直播频道视图。
avatar_url 字符串 是 圈子头像地址。
字段 类型 可为 null 说明
name 字符串 否 主播昵称。
avatar_url 字符串 是 主播头像地址。
字段 类型 可为 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..."

一场直播出现在列表里,需要同时满足:

  1. 直播已被圈主列入直播目录(directory_listed 为真);
  2. 直播状态为 scheduled、live、interrupted 或 ended 之一;
  3. 所属圈子满足:已绑定 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)的含义见接口约定。