Owncast 0.3.0 API 使用详解

‍‍‌‍‍‌> 目标：把 Owncast v0.3.0 的两套 API——无需认证的公开 API（状态/配置/聊天）与 Basic 认证的 Admin API（监控/配置管理/聊天管理/直播控制）——逐个端点讲清用法，附 WebSocket 聊天协议实测，并给出可直接落地的集成场景。全部请求与回显均在 Ubuntu 22.04 + Owncast 0.3.0 实测通过（实测日期 2026-10-29）。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Owncast 版本：0.3.0（/api/status 返回 versionNumber: "0.3.0" 实测）
服务端口：Web 8150（示例统一用 http://127.0.0.1:8150）、RTMP 8153
管理凭据：admin / q1w2e3r4（Basic 认证，出厂默认 admin / abc123，改密实测见《Owncast 0.3.0 Docker Compose 部署指南》4.4 节）
API 规范：官方仓库根目录 openapi.yaml（v0.3.0 源码包实测核对）
部署方式：官方发行版部署（Docker Compose，部署过程见《Owncast 0.3.0 Docker Compose 部署指南》）

二、前置条件

Owncast 已部署启动，Web 端口可达（curl -s http://127.0.0.1:8150/api/status 返回 JSON）；
已知管理凭据（Admin API 全部接口需要 Basic 认证）；
本机装有 curl（公开 API 与 Admin API 均为普通 HTTP/JSON）；WebSocket 聊天测试需支持 WS 的客户端；
（可选）推流在线，便于观察监控类接口的实时数据。

三、API 总览与认证

0.3.0 的 HTTP API 统一挂在 Web 端口下，按认证要求分两套：

套件	前缀	认证方式	典型用途
公开 API	`/api/*`	无需认证	状态灯、页面数据、第三方播放器、只读聊天
聊天 WebSocket	`/ws`	URL 参数 `accessToken`	发送聊天消息、实时事件流
Admin API	`/api/admin/*`	HTTP Basic（`admin` + 管理密码）	监控、配置管理、聊天管理、直播控制

三点先说清（均实测核实）：

Admin API 用标准 HTTP Basic。0.3.0 源码（webserver/router/middleware）中鉴权逻辑为：用户名不校验（习惯上写 admin），仅密码参与比较——密码与后台管理密码相同，改密后立即生效（实测旧密码 401、新密码 200）。
公开接口不泄露敏感信息。实测 /api/config 只含页面展示所需字段，推流码与密码哈希不出现在任何公开端点；全量配置（含 bcrypt 哈希）只在 /api/admin/serverconfig。
聊天是「注册令牌」模型。先 POST /api/chat/register 换 accessToken，再凭令牌访问历史或建立 WS 连接——公开聊天接口不带令牌时为只读空集（实测 /api/chat 无参返回 []）。

四、公开 API 实测

4.1 状态类

GET /api/status —— 直播是否在线、当前标题、版本（最常用的状态灯数据源，实测）：

curl -s http://127.0.0.1:8150/api/status

{"serverTime":"2026-10-29T14:35:50.042102067Z","lastConnectTime":"2026-10-29T14:35:36Z","lastDisconnectTime":null,"versionNumber":"0.3.0","streamTitle":"Owncast 0.3.0 推流实测间","online":true}

GET /api/config —— 页面渲染数据（实例名/简介/logo/社交链接等，节选实测）：

curl -s http://127.0.0.1:8150/api/config | python3 -m json.tool

{
    "appearanceVariables": {},
    "offlineMessage": "",
    "logo": "/logo",
    "name": "New Owncast Server",
    "extraPageContent": "...",
    "socialHandles": [],
    "socketHostOverride": null,
    "title": "Owncast 0.3.0 推流实测间",
    "summary": "This is a new live video streaming server powered by Owncast.",
    "tags": [],
    "version": "0.3.0",
    "enableSiteContent": true,
    "hideViewerCount": false,
    "nsfw": false,
    "authentication": { "indieauthEnabled": true },
    "federation": {
        "account": "streamer@owncast.example.com",
        "enabled": false,
        "followerCount": 0,
        "showEngagement": true
    },
    "notifications": {
        "browser": { "enabled": true, "goLiveMessage": "I've gone live!" },
        "discord": { "enabled": false, "goLiveMessage": "" }
    },
    "chatDisabled": false,
    "externalActions": [],
    "online": true,
    "viewerCount": 0,
    "overallPeakViewerCount": 0,
    "maxSessionDurationInSeconds": 0
}

4.2 内容类

GET /api/emoji —— 自定义表情包（未上传时实测返回空数组）：

curl -s http://127.0.0.1:8150/api/emoji

[]

GET /api/video/variants —— 当前生效的输出档位（观众端清晰度候选，实测）：

curl -s http://127.0.0.1:8150/api/video/variants

[{"name":"1.2Mbps@24fps","index":0}]

GET /api/socialplatforms —— 支持的社交平台类型（配置社交链接时前端可选值）：

curl -s http://127.0.0.1:8150/api/socialplatforms

{"platforms":["Bluesky","Discord","Facebook","GitHub","GitLab","Instagram","Keybase","LinkedIn","Mastodon","Matrix","Owncast","PixelFed","Twitch","Website","X","YouTube"]}

GET /api/followers —— 联邦关注者（未启用联邦时实测为空集）：

curl -s http://127.0.0.1:8150/api/followers

{"actions":"","followers":[],"total":0}

4.3 播放与杂项

GET /hls/0/stream.m3u8 —— 直播播放列表（观众端拉流入口；未推流时返回空/404，推流中实测输出 3 秒分片 m3u8）；
GET /api/ping —— 健康探针，实测返回 200（无响应体）；
GET /api/yp —— 官方目录登记状态，实测 {"enabled":false}；
GET /api/chat?accessToken=... —— 聊天历史（带注册令牌才有数据，见第五章）。

五、聊天 API 与 WebSocket 实测

聊天分两条路：REST 拿历史（/api/chat）与 WebSocket 收发实时消息（/ws）。两者共用注册令牌。

5.1 注册聊天用户

curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"displayName":"probe01"}' http://127.0.0.1:8150/api/chat/register

实测回显（节选）：

{
    "accessToken": "tEsI8O7WgSdKzRhS4v0U3GQzDE7Zctz3g0IlDEoQhQY=",
    "user": {
        "id": "mbcPp7En7R",
        "displayName": "probe01",
        "displayColor": 3,
        "isBot": false,
        "authenticated": false,
        "previousActiveAt": null,
        "nameChanged": false,
        "scopes": []
    }
}

5.2 WebSocket 连接与发消息

连接地址 /ws?accessToken=<令牌>，握手成功（HTTP 101）后收发 JSON 帧。入站消息格式为 {"type":"CHAT","body":"文本","empty":false}（type 取值 CHAT / NAME_CHANGED，大小写敏感——v0.3.0 源码 services/chat/events.go 中定义为字符串枚举，实测按此格式发送成功、按数字 1 发送无效）。用 Python 原生 socket 的实测过程（关键输出逐行）：

# 1) 注册（同 5.1）拿到 accessToken
# 2) 握手：GET /ws?accessToken=<注册返回的令牌> HTTP/1.1 + Upgrade: websocket
handshake: HTTP/1.1 101 Switching Protocols
# 3) 发送：{"type": "CHAT", "body": "大家好，这是一条通过 WebSocket API 发送的实测消息", "empty": false}
# 4) 立即收到广播帧（节选，含消息 ID 与完整 user 对象）：
recv bytes: 338
chat event found at: 297
excerpt: ...,"id":"q3J1bd3N4R","timestamp":"2026-10-29T14:37:35Z","body":"大家好，这是一条通过 WebSocket API 发送的实测消息","type":"CHAT"

5.3 读回历史验证

带令牌读 REST 历史，刚发的那条已在（实测）：

curl -s "http://127.0.0.1:8150/api/chat?accessToken=<令牌>" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); [print(m['id'],'|',m['author']['displayName'],'|',m['body'][:40]) for m in d]"

q3J1bd3N4R | probe01 | 大家好，这是一条通过 WebSocket API 发送的实测消息

💡 说明：匿名注册的用户 scopes 为空，经联邦认证的用户带 FEDIVERSE scope；管理员在后台授予 MODERATOR scope 后用户可执行删消息等管理动作。服务端事件流还包括 USER_JOINED（进房通知）与 NAME_CHANGED（改名广播），浏览器端聊天室即基于同一 /ws 端点工作。

六、Admin API 实测

统一认证格式 -u admin:q1w2e3r4（Basic）；全部实测于直播进行中。

6.1 直播与监控

GET /api/admin/status —— 推流者详情（比公开 status 多编码器/分辨率/帧率，实测节选）：

{
    "broadcaster": {
        "time": "2026-10-29T14:21:36.624986595Z",
        "remoteAddr": "10.89.61.3:32944",
        "streamDetails": {
            "videoCodec": "H.264",
            "audioCodec": "AAC",
            "encoder": "Lavf63.1.102",
            "width": 1280,
            "height": 720,
            "videoBitrate": 0,
            "audioBitrate": 125,
            "framerate": 30
        }
    },
    "currentBroadcast": {
        "latencyLevel": { "index": 2, "name": "default" },
        "outputSettings": { "videoBitrate": 1200, "framerate": 24, "videoPassthrough": false, "audioPassthrough": true, "cpuUsageLevel": 2 }
    },
    "versionNumber": "0.3.0",
    "online": true
}

GET /api/admin/hardwarestats —— 服务器资源水位（实测，数值为采样时点）：

curl -s -u admin:q1w2e3r4 http://127.0.0.1:8150/api/admin/hardwarestats

{
    "CPU": 3.6,
    "usedMemory": 18.47,
    "memory": 3.88,
    "disk": 60.6
}

（CPU 为百分比，usedMemory/memory 为 GB，disk 为已用百分比。）

GET /api/admin/viewersOverTime?windowStart=...&windowEnd=... —— 观众曲线（注意参数是 epoch 秒时间戳，实测）：

WS=$(date -u -d '30 minutes ago' +%s); WE=$(date -u +%s)
curl -s -u admin:q1w2e3r4 "http://127.0.0.1:8150/api/admin/viewersOverTime?windowStart=$WS&windowEnd=$WE"

{"viewers":[{"time":"2026-10-29T14:32:03+08:00","value":0},{"time":"2026-10-29T14:32:08+08:00","value":0},{"time":"2026-10-29T14:32:13+08:00","value":0}],"currentTick":6}

（按 5 秒采样点返回；currentTick 为当前时间刻度。）

6.2 配置管理

GET /api/admin/serverconfig —— 全量配置 JSON（约 106 行，《Owncast 0.3.0 配置参数详解》已逐类拆解，此处不赘）。

POST /api/admin/config/<key> —— 修改单个配置，统一格式 {"value": ...}。三个代表性实测（更多键位见《Owncast 0.3.0 配置参数详解》第四章参数总览）：

B="http://127.0.0.1:8150/api/admin/config"
curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' -d '{"value":"Owncast 0.3.0 推流实测间"}' $B/streamtitle
curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' -d '{"value":1}'     $B/video/streamlatencylevel
curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' -d '{"value":true}'  $B/chat/disable

{"message":"changed","success":true}
{"message":"set stream latency","success":true}
{"message":"chat disabled status updated","success":true}

6.3 聊天管理

GET /api/admin/chat/users —— 已注册聊天用户（实测，注册过 probe01/probe02 两个探针账号后）：

{"users":[{"id":"mbcPp7En7R","displayName":"probe01","displayColor":3,"createdAt":"2026-10-29T14:36:47Z","disabledAt":null,"disabledReason":"","previousActiveAt":"2026-10-29T14:36:47Z","nameChanged":false,"scopes":[],"authenticated":false}],"totalCount":1}

GET /api/admin/chat/clients —— 当前在线连接（无观众连接时实测）：

{"connectedClients":[]}

GET /api/admin/chat/messages —— 聊天记录（含完整 user 对象，用于审计，实测与公开历史内容一致）。

6.4 直播控制

POST /api/admin/disconnect —— 断开当前推流（管理端「停止直播」按钮的 API 形态，实测）：

curl -s -X POST -u admin:q1w2e3r4 http://127.0.0.1:8150/api/admin/disconnect

（返回 200，空响应体；推流端随即被断开）

服务端日志同步出现：

time="2026-10-29T14:34:15Z" level=info msg="Inbound stream has disconnected"

公开状态立即转为下线（实测）：{"online":false,"lastConnectTime":"2026-10-29T14:33:26Z","lastDisconnectTime":"2026-10-29T14:34:15Z",...}。推流端不需要重启，重连推流即可再次开播（实测重推后 online: true）。

6.5 推流码管理

GET /api/admin/streamkeys —— 当前列表（实测改码后）：

[{"comment":"demo","key":"q1w2e3r4","usedAt":null}]

修改经 POST /api/admin/config/streamkeys（数组整体替换，实测回显 {"message":"changed","success":true}，换码后旧码立即失效的排障实录见《Owncast 0.3.0 Docker Compose 部署指南》4.4/第十章）。

6.6 日志

GET /api/admin/logs —— 运行日志 API（供外部日志面板轮询，实测返回与服务运行日志一致的结构化条目）：

[{"time":"2026-10-29T14:20:40Z","level":"info","message":"Owncast v0.3.0-linux-64bit (4b09a1b11693977400fb6f6cb06a7b9891bdca6d)"},...]

（输出节选，实测首条。）

七、集成实践场景

7.1 「直播中」状态灯（公开 API）

给论坛/主页挂一个直播状态角标，核心就一个请求：

curl -s http://127.0.0.1:8150/api/status | python3 -c \
  "import json,sys;d=json.load(sys.stdin);print('LIVE:' + d['streamTitle'] if d['online'] else 'OFFLINE')"

LIVE:Owncast 0.3.0 推流实测间

7.2 欢迎机器人（WebSocket）

「注册 → 连 WS → 收到开播事件后发欢迎语」是官方第三方客户端的标准形态；本机实测发送消息的最小骨架（完整握手/组帧见 5.2 实测，略去 Web 帧细节）：

import json, urllib.request
TOKEN = "<注册接口返回的 accessToken>"
# 建立连 ws://<host>:8150/ws?accessToken=TOKEN 后，向服务端发：
send(json.dumps({"type": "CHAT", "body": "开播了！欢迎进直播间", "empty": False}))

实测该帧被服务端广播给全部连接，并落进 REST 历史（5.2/5.3 验证一致）。

7.3 监控看板（Admin API 轮询）

hardwarestats（CPU/内存/磁盘）+ viewersOverTime（观众曲线）+ status（在线态）三个接口即可拼出直播服务器看板；轮询间隔建议 30 秒，viewersOverTime 窗口取整小时。

7.4 嘉宾临时推流码

活动场景给嘉宾发独立推流码：POST /api/admin/config/streamkeys 追加带 comment 标记的临时码（如 guest-1029），活动结束替换数组收回该码；配合 6.1 的 remoteAddr 与 6.6 的日志可审计谁在推流。多码管理与失效实测见《Owncast 0.3.0 配置参数详解》5.2 节。

八、常见问题

Q1：Admin API 返回 401？

Basic 认证三查：密码是否是管理密码（不是推流码；出厂两者相同，改密后就分开了——本服务器管理密码 q1w2e3r4）；curl 是否带 -u；改过密码后旧密码立即失效（实测 401）。忘记密码用 -adminpassword 启动参数重置（《Owncast 0.3.0 Docker Compose 部署指南》第六章）。

Q2：/api/chat 返回空数组，但聊天室明明有消息？

/api/chat 必须带注册令牌（?accessToken=）；且它返回的是历史消息，实时消息要走 /ws。实测无令牌请求返回 []。

Q3：WebSocket 发了消息但没人收到？

按序排查（均实测踩点）：type 是否为字符串 "CHAT"（发数字 1 无效）；连接 URL 是否带了 accessToken；消息是否被管理端按「垃圾消息」拦截（chatSpamProtectionEnabled 默认开启，同一连接高频发言会被静默丢弃）。

Q4：viewersOverTime 传时间参数为什么一直空？

参数必须是 epoch 秒（date +%s 生成），不是 ISO 字符串——实测 ISO 格式返回空集、epoch 秒正常返回采样点（见 6.1）。

Q5：哪里有完整的端点清单？

官方仓库根目录 openapi.yaml（v0.3.0）覆盖全部 HTTP 端点及请求/响应结构，本文所有端点均与该规范逐一对核；WebSocket 协议不在 OpenAPI 内，以 5.2 实测为准。

九、参考链接

Owncast 官方文档：第三方 API（查询日期 2026-10-29）
v0.3.0 openapi.yaml（仓库根目录）（查询日期 2026-10-29）
Owncast 官方文档：SSL 反向代理（生产 HTTPS 部署前置，查询日期 2026-10-29）
本专栏姊妹篇：《Owncast 0.3.0 介绍与选型指南》、《Owncast 0.3.0 Docker Compose 部署指南》、《Owncast 0.3.0 配置参数详解》