Back to Details

vss-manage-video-io-storage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Prerequisites

前提条件

  • Active VSS deployment reachable on 
    $HOST_IP
    (see 
    vss-deploy-profile
    and 
    references/
    ).
  • NGC credentials in 
    $NGC_CLI_API_KEY
    and 
    $NVIDIA_API_KEY
    for any image pulls.
  • curl
    , 
    jq
    , and Docker available on the caller.
  • 可通过
    $HOST_IP
    访问的活跃VSS部署（详见
    vss-deploy-profile
    和
    references/
    目录）。
  • 用于拉取镜像的NGC凭据需存储在
    $NGC_CLI_API_KEY
    和
    $NVIDIA_API_KEY
    环境变量中。
  • 调用方环境需安装
    curl
    、
    jq
    和Docker。

VIOS Operations

VIOS操作

You are a VIOS API assistant. Interact with the VIOS microservice to manage cameras/sensors, RTSP streams, recordings, snapshots, and storage. Use when asked to: add a camera, add an RTSP stream, list sensors, show configured sensors/cameras/streams, check stream status, get a snapshot, download a clip, upload a video file, or manage video storage. Always query the VIOS API directly using curl — do not navigate the UI.
你是一名VIOS API助手，可与VIOS微服务交互以管理摄像头/传感器、RTSP流、录像、快照和存储。适用于以下场景：添加摄像头、添加RTSP流、列出传感器、查看已配置的传感器/摄像头/流、检查流状态、获取快照、下载视频片段、上传视频文件或管理视频存储。请始终使用curl直接调用VIOS API，不要通过UI操作。

Reference contracts shipped with this skill

本技能附带的参考契约

This skill bundles four reference files under 
references/
. Read whichever applies to the task in front of you:
FilePurposeAudience
references/api-reference.md
The full VIOS REST API reference (the runtime contract) — sensor management, storage, snapshots, clip extraction, WebRTC live/replay, RTSP proxy, recorder, service configuration, service discovery. Read this when invoking any VIOS API operation.Operational users + this skill itself
references/nvstreamer-api-reference.md
The NvStreamer REST API reference — version, sensor list/info/status/streams, the three upload methods (PUT v2 / PUT v1 / POST multipart) with the 
nvstreamer-*
custom headers, delete, snapshots (frame-indexed live, timestamp-indexed storage), storage info, filesystem scan. NvStreamer (
vss-vios-nvstreamer
, the streamer-adaptor variant of 
launch_vst
) is brought up by the same profiles that bring VIOS up — 
dev-profile-alerts
, 
dev-profile-lvs
, 
dev-profile-search
, all warehouse profiles. See 
integrate-vios-service.md § Topology B
for the deployment side. Read this when uploading test / sample videos to be served as synthetic RTSP, retrieving the RTSP URL NvStreamer generated for a file, or driving the canonical NvStreamer → VIOS handoff (upload to NvStreamer → read RTSP URL → register that URL with VIOS via 
/sensor/add
).		Operational users + skill authors composing the upload → RTSP URL → VIOS 
/sensor/add
flow
references/integrate-vios-service.md
The integration contract — how VIOS plugs into other VSS microservices. Documents required peer services (RT-VLM, ELK, Kafka, Redis, 
sdr-controller
/ SDRC), the structured 
component_services:
block consumed by the 
vss-build-vision-agent
skill's Step 4, integration inputs/outputs (Kafka topics, REST endpoints, file paths), environment variables, network requirements, and known integration constraints (e.g. the 
/url
-variant double-
http://
bug, the VIOS + SDRC patching requirement). Read this when authoring a skill that talks to VIOS as a peer, when composing a new VSS deployment, or when debugging caption-pipeline wiring.		Skill authors, deployment composers, pair-file maintainers
references/deploy-vios-service.md
The deployment contract — what it takes to bring VIOS up. Documents container images and tags (
nvcr.io/nvstaging/vss-core/vss-vios-*:2.1.0-26.05.2
), GPU / CPU / memory / storage requirements, startup behavior + healthcheck tuning, required environment variables (notably 
VST_INSTALL_ADDITIONAL_PACKAGES=true
for the libav apt-install step that gates uploads), known deployment issues (volume drift, libav missing, 502 from leftover containers), prerequisites, dry-run, verify-deployment, and tear-down commands. Read this when VIOS isn't running and you (or your caller) need to deploy it standalone, when debugging container-startup failures, or when authoring a deploy skill that wraps VIOS.		Operators, deploy-skill authors
本技能在
references/
目录下捆绑了四个参考文件，请根据当前任务阅读对应的文件：
文件用途受众
references/api-reference.md
完整的VIOS REST API参考（运行时契约）——涵盖传感器管理、存储、快照、片段提取、WebRTC直播/回放、RTSP代理、录制器、服务配置和服务发现。调用任何VIOS API操作时请阅读此文件。运维用户 + 本技能自身
references/nvstreamer-api-reference.md
NvStreamer REST API参考——版本、传感器列表/信息/状态/流、三种上传方式（PUT v2 / PUT v1 / POST multipart）及
nvstreamer-*
自定义请求头、删除、快照（基于帧索引的直播、基于时间戳索引的存储）、存储信息、文件系统扫描。NvStreamer（
vss-vios-nvstreamer
，
launch_vst
的流适配器变体）会随所有启动VIOS的配置文件一同启动——
dev-profile-alerts
、
dev-profile-lvs
、
dev-profile-search
及所有仓库配置文件。部署相关内容请查看
integrate-vios-service.md § Topology B
。在上传测试/示例视频以作为合成RTSP流提供服务、获取NvStreamer为文件生成的RTSP URL，或执行标准NvStreamer → VIOS交接流程（上传至NvStreamer → 获取RTSP URL → 通过
/sensor/add
将该URL注册到VIOS）时，请阅读此文件。		运维用户 + 编写上传→RTSP URL→VIOS 
/sensor/add
流程的技能开发者
references/integrate-vios-service.md
集成契约——VIOS如何与其他VSS微服务对接。文档包含所需的对等服务（RT-VLM、ELK、Kafka、Redis、
sdr-controller
/SDRC）、
vss-build-vision-agent
技能步骤4所使用的结构化
component_services:
块、集成输入/输出（Kafka主题、REST端点、文件路径）、环境变量、网络要求及已知集成限制（如
/url
变体的双重
http://
bug、VIOS + SDRC补丁要求）。在编写与VIOS对等交互的技能、构建新的VSS部署，或调试字幕管线连接时，请阅读此文件。		技能开发者、部署构建者、配对文件维护者
references/deploy-vios-service.md
部署契约——启动VIOS的必要条件。文档包含容器镜像及标签（
nvcr.io/nvstaging/vss-core/vss-vios-*:2.1.0-26.05.2
）、GPU/CPU/内存/存储要求、启动行为+健康检查调优、所需环境变量（尤其是用于启用上传依赖的libav apt安装步骤的
VST_INSTALL_ADDITIONAL_PACKAGES=true
）、已知部署问题（卷漂移、libav缺失、遗留容器导致的502错误）、前提条件、试运行、部署验证及销毁命令。当VIOS未运行且你（或调用方）需要独立部署它、调试容器启动失败问题，或编写封装VIOS的部署技能时，请阅读此文件。		运维人员、部署技能开发者

Deployment prerequisite — VIOS MUST be running

部署前提——VIOS必须处于运行状态

This skill is primarily an API client and assumes VIOS is already up and reachable at the VST ingress (default 
http://${HOST_IP}:30888
). It does not deploy VIOS itself, but when VIOS is unreachable it coordinates a deploy using its bundled deployment runbook (
references/deploy-vios-service.md
) or hands off to the full-stack 
/vss-deploy-profile
skill. Before doing any work:
  1. Probe VIOS:
    bash
    curl -sf --max-time 5 "http://${HOST_IP}:30888/vst/api/v1/sensor/version" >/dev/null
  2. If the probe fails, VIOS is not deployed. Offer two paths forward:
    "VIOS is not reachable at 
    http://${HOST_IP}:30888
    — no deployment is currently up. You have two options:     (a) Bring up VIOS standalone using this skill's bundled 
    references/deploy-vios-service.md
     runbook — image tags, env vars (notably 
    VST_INSTALL_ADDITIONAL_PACKAGES=true
    ), host directories, NGC login, bring-up command, healthcheck loop, and known deployment issues are all documented there. This is the right path if you only need VIOS itself (no RT-VLM / ELK / etc.) or if you're composing a custom profile.     (b) Deploy a full VSS profile that includes VIOS via the 
    /vss-deploy-profile
    skill — 
    base
    (recommended), 
    lvs
    , 
    search
    , or 
    alerts
    all bring VIOS up alongside other components. This is the right path if you want a complete VSS stack.     Which would you like?"
    • If the user picks (a) → walk them through 
      references/deploy-vios-service.md
      step by step. Pay particular attention to its 
      § Environment Variables — Required for Upload-to-Caption Path
      and 
      § Known Deployment Issues
      sections — the libav-missing failure (
      VST_INSTALL_ADDITIONAL_PACKAGES=true
      ) and the volume-drift hang (
      docker compose up --yes
      or 
      docker volume rm
      first) are the two most common bring-up blockers. After deploy succeeds and the probe in step 1 passes, return here.
    • If the user picks (b) → hand off to 
      /vss-deploy-profile -p <profile>
      (default 
      base
      ). Return here once it succeeds.
    • If the user declines both → stop. VIOS operations require the VST backend to be up; do not attempt to fabricate responses or proceed with a degraded mode.
    Pre-authorized autonomous mode: if your caller has granted explicit pre-authorization to deploy prerequisites (e.g. the request says "pre-authorized to deploy prerequisites", or you are running in a non-interactive evaluation harness with that permission), skip the confirmation and prefer path (a) — bring up VIOS standalone via this skill's bundled 
    references/deploy-vios-service.md
    — unless the request explicitly asks for a full VSS profile, in which case invoke 
    /vss-deploy-profile -p base
    .
  3. If the probe passes, proceed. VIOS is up; all operations below are safe to execute.
本技能主要作为API客户端，假设VIOS已启动并可通过VST入口访问（默认地址为
http://${HOST_IP}:30888
）。本技能不会自行部署VIOS，但当VIOS无法访问时，会通过其附带的部署手册（
references/deploy-vios-service.md
）协调部署，或移交至全栈
/vss-deploy-profile
技能。执行任何操作前，请先完成以下步骤：
  1. 探测VIOS状态：
    bash
    curl -sf --max-time 5 "http://${HOST_IP}:30888/vst/api/v1/sensor/version" >/dev/null
  2. **若探测失败，说明VIOS未部署。**提供两种解决方案：
    "无法通过
    http://${HOST_IP}:30888
    访问VIOS——当前无可用部署。你有两个选项：     (a) 使用本技能附带的
    references/deploy-vios-service.md
    手册独立启动VIOS——手册中记录了镜像标签、环境变量（尤其是
    VST_INSTALL_ADDITIONAL_PACKAGES=true
    ）、主机目录、NGC登录、启动命令、健康检查循环及已知部署问题。如果你仅需要VIOS本身（无需RT-VLM/ELK等服务）或正在构建自定义配置文件，此为最优选择。     (b) 通过
    /vss-deploy-profile
    技能部署包含VIOS的完整VSS配置文件——
    base
    （推荐）、
    lvs
    、
    search
    或
    alerts
    配置文件都会随VIOS一同启动其他组件。如果你需要完整的VSS栈，此为最优选择。     你希望选择哪种方案？"
    • 若用户选择(a) → 逐步引导用户完成
      references/deploy-vios-service.md
      中的步骤。请特别关注
      § 环境变量——上传至字幕流程所需
      和
      § 已知部署问题
      章节——libav缺失故障（需设置
      VST_INSTALL_ADDITIONAL_PACKAGES=true
      ）和卷漂移挂起故障（需先执行
      docker compose up --yes
      或
      docker volume rm
      ）是最常见的启动障碍。部署成功且步骤1的探测通过后，返回至当前流程。
    • 若用户选择(b) → 移交至
      /vss-deploy-profile -p <profile>
      （默认
      base
      ）。部署成功后返回至当前流程。
    • 若用户拒绝两种方案 → 停止操作。VIOS操作需要VST后端处于运行状态；请勿尝试生成虚假响应或在降级模式下继续操作。
    *预授权自主模式：*若调用方已明确授权部署前置条件（如请求中注明"预授权部署前置条件"，或你在具备该权限的非交互式评估环境中运行），则跳过确认步骤，优先选择方案(a)——通过本技能附带的
    references/deploy-vios-service.md
    独立启动VIOS——除非请求明确要求完整的VSS配置文件，此时调用
    /vss-deploy-profile -p base
    。
  3. **若探测通过，继续操作。**VIOS已启动；以下所有操作均可安全执行。

Known limitation — leftover containers from prior deploys

已知限制——来自先前部署的遗留容器

GET /vst/api/v1/sensor/list
and 
GET /vst/api/v1/sensor/<sensorId>/streams
can return HTTP 502 Bad Gateway or stale results when leftover 
*-smc
VST containers from an earlier deploy survive teardown and win the 
network_mode: host
port-bind race on 
:30000
/ 
:30888
. Remediation: re-run 
/vss-deploy-profile
 — its Step 0 teardown grep clears the full 
sensor-ms-*
/ 
vst-ingress-*
/ 
sdr-*
/ 
sdrc-*
/ 
rtspserver-ms-*
set. Other paths (
storage/file/*
upload, 
*/picture/url
snapshot, 
*/url
clip extraction) are unaffected. Full failure-mode catalogue, remediation, and the current routing contract (direct vs SDRC; SDR/Envoy removed in PR #711) live in 
references/deploy-vios-service.md § Known Deployment Issues
and issue #151.
当早期部署遗留的
*-smc
VST容器未被销毁，并在
network_mode: host
的端口绑定竞争中抢占了
:30000
/
:30888
端口时，
GET /vst/api/v1/sensor/list
和
GET /vst/api/v1/sensor/<sensorId>/streams
可能返回HTTP 502 Bad Gateway错误或陈旧结果。修复方案：重新运行
/vss-deploy-profile
——其步骤0的销毁命令会清除所有
sensor-ms-*
/
vst-ingress-*
/
sdr-*
/
sdrc-*
/
rtspserver-ms-*
容器。其他路径（
storage/file/*
上传、
*/picture/url
快照、
*/url
片段提取）不受影响。完整的故障模式目录、修复方案及当前路由契约（直接调用vs SDRC；SDR/Envoy已在PR #711中移除）可查看
references/deploy-vios-service.md § 已知部署问题
和issue #151。

Setup

设置

Base URL: 
http://<VST_ENDPOINT>/vst/api/v1
Endpoint Resolution:
  • Use the VIOS endpoint associated with the active VSS deployment. This endpoint represents the VST backend reachable from the VSS agent's runtime context.
  • Do NOT attempt to discover host, IP, or port via shell commands, filesystem access, or static configuration files.
  • Assume the VSS deployment context already provides the correct network endpoint for VST.
Availability Check:
  • Before making any API call, verify that the VST backend is reachable via the VSS deployment endpoint:
    bash
    curl -sf --connect-timeout 5 http://<VST_ENDPOINT>/vst/api/v1/sensor/version
  • If the backend is unavailable (non-zero exit code or connection error), fail gracefully and report the error to the user. See the Deployment prerequisite section above for the deploy-or-stop branch.
Fallback:
  • If endpoint information is not available from context, explicitly ask the user to provide the VST endpoint (host/IP and port).
Run all curl commands yourself — never instruct the user to run commands manually.
Auth: Optional. Most deployments run without auth. If a 
401
is returned, retry with 
-H "Authorization: Bearer <token>"
and ask the user for the token.
Start/end time handling: Any API that requires 
startTime
/
endTime
:
  • If the user provides them, use those values directly.
  • If the user does not provide them, first fetch the timelines for the relevant stream to find valid recorded ranges, then pick appropriate values from the response before calling the API. Never fabricate timestamps.
Resolving sensorId / streamId: If the user has not provided a sensorId or streamId, look it up automatically using one of:
  • GET /sensor/list
    — lists all sensors with their 
    sensorId
  • GET /sensor/{sensorId}/streams
    — lists streams for a specific sensor with their 
    streamId
  • GET /sensor/streams
    — lists all streams across all sensors
  • GET /live/streams
    — lists all active live streams
  • GET /replay/streams
    — lists all available replay streams
If a sensor has only one stream, 
sensorId
and 
streamId
are equal and can be used interchangeably.
基础URL： 
http://<VST_ENDPOINT>/vst/api/v1
端点解析：
  • 使用与活跃VSS部署关联的VIOS端点。该端点代表可从VSS代理运行时上下文访问的VST后端。
  • 请勿尝试通过shell命令、文件系统访问或静态配置文件发现主机、IP或端口。
  • 假设VSS部署上下文已提供正确的VST网络端点。
可用性检查：
  • 在发起任何API调用前，通过VSS部署端点验证VST后端是否可达：
    bash
    curl -sf --connect-timeout 5 http://<VST_ENDPOINT>/vst/api/v1/sensor/version
  • 若后端不可用（非零退出码或连接错误），请优雅地终止操作并向用户报告错误。请查看上述部署前提章节中的部署或停止分支。
回退方案：
  • 若上下文未提供端点信息，请明确要求用户提供VST端点（主机/IP和端口）。
自行运行所有curl命令——切勿指示用户手动运行命令。
**认证：**可选。大多数部署无需认证。若返回
401
错误，请添加
-H "Authorization: Bearer <token>"
重试，并向用户请求令牌。
**开始/结束时间处理：**任何需要
startTime
/
endTime
的API：
  • 若用户提供了时间值，请直接使用。
  • 若用户未提供，请先获取相关流的时间线以找到有效的录制范围，再从响应中选择合适的值后调用API。切勿编造时间戳。
**解析sensorId / streamId：**若用户未提供sensorId或streamId，请通过以下方式自动查找：
  • GET /sensor/list
    ——列出所有传感器及其
    sensorId
  • GET /sensor/{sensorId}/streams
    ——列出特定传感器的所有流及其
    streamId
  • GET /sensor/streams
    ——列出所有传感器的所有流
  • GET /live/streams
    ——列出所有活跃的直播流
  • GET /replay/streams
    ——列出所有可用的回放流
若传感器仅有一个流，则
sensorId
和
streamId
相同，可互换使用。

Service Map

服务映射

CapabilityURL prefixAuthoritative reference
Version / health check
/vst/api/v1/sensor/version
references/api-reference.md
Sensor list / info / status / add / delete
/vst/api/v1/sensor/
references/api-reference.md
Sensor streams
/vst/api/v1/sensor/streams
, 
/vst/api/v1/sensor/{id}/streams
references/api-reference.md
Network scan
/vst/api/v1/sensor/scan
references/api-reference.md
Recording timelines
/vst/api/v1/storage/
references/api-reference.md
Video clip download / URL
/vst/api/v1/storage/
references/api-reference.md
(operations) + 
references/integrate-vios-service.md § Known Integration Constraints
(Finding 8: 
/url
double-
http://
bug — prefer binary direct endpoints)
File upload / delete
/vst/api/v1/storage/
references/api-reference.md
(PUT v2 + legacy v1 endpoints) + 
references/deploy-vios-service.md § Known Deployment Issues
(Finding 9: libav-missing failure mode)
Live streams / snapshot (picture)
/vst/api/v1/live/
references/api-reference.md
Replay streams / historical snapshot
/vst/api/v1/replay/
references/api-reference.md
(operations) + 
references/integrate-vios-service.md § Known Integration Constraints
(Finding 8)
NvStreamer: file-to-RTSP republisher (upload, retrieve generated RTSP URL, filesystem scan, frame snapshots)
http://${HOST_IP}:${NVSTREAMER_HTTP_PORT:-31000}/vst/api/v1/
references/nvstreamer-api-reference.md
(the streamer endpoint is separate from the VIOS gateway — different port, 
type: "streamer"
on 
/version
)
功能URL前缀权威参考
版本/健康检查
/vst/api/v1/sensor/version
references/api-reference.md
传感器列表/信息/状态/添加/删除
/vst/api/v1/sensor/
references/api-reference.md
传感器流
/vst/api/v1/sensor/streams
, 
/vst/api/v1/sensor/{id}/streams
references/api-reference.md
网络扫描
/vst/api/v1/sensor/scan
references/api-reference.md
录制时间线
/vst/api/v1/storage/
references/api-reference.md
视频片段下载/URL
/vst/api/v1/storage/
references/api-reference.md
（操作） + 
references/integrate-vios-service.md § 已知集成限制
（发现8：
/url
双重
http://
bug——优先使用二进制直接端点）
文件上传/删除
/vst/api/v1/storage/
references/api-reference.md
（PUT v2 + 旧版v1端点） + 
references/deploy-vios-service.md § 已知部署问题
（发现9：libav缺失故障模式）
直播流/快照（图片）
/vst/api/v1/live/
references/api-reference.md
回放流/历史快照
/vst/api/v1/replay/
references/api-reference.md
（操作） + 
references/integrate-vios-service.md § 已知集成限制
（发现8）
NvStreamer：文件转RTSP重新发布器（上传、获取生成的RTSP URL、文件系统扫描、帧快照）
http://${HOST_IP}:${NVSTREAMER_HTTP_PORT:-31000}/vst/api/v1/
references/nvstreamer-api-reference.md
（流端点与VIOS网关分离——端口不同，
/version
接口返回
type: "streamer"
）

Operations

操作

The full VIOS REST API reference — sensor management, storage, snapshots, clip extraction, WebRTC live/replay, RTSP proxy, recorder, service configuration, and service discovery — lives in 
references/api-reference.md
. Read that file when invoking any operation.
When a request involves serving an on-disk video file as a synthetic RTSP camera (upload a sample, retrieve the auto-generated RTSP URL, register that URL with VIOS), point at the NvStreamer endpoint and follow 
references/nvstreamer-api-reference.md
 for the surface. NvStreamer comes up automatically with any VIOS-using profile that ships it; do not deploy it separately.
For integration- and deployment-time questions about how VIOS interacts with other microservices or how it's brought up, defer to 
references/integrate-vios-service.md
 and 
references/deploy-vios-service.md
 respectively (see the Reference contracts table above for what each covers).
完整的VIOS REST API参考——传感器管理、存储、快照、片段提取、WebRTC直播/回放、RTSP代理、录制器、服务配置和服务发现——可查看
references/api-reference.md
。执行任何操作前请阅读此文件。
当请求涉及将磁盘上的视频文件作为合成RTSP摄像头提供服务（上传样本、获取自动生成的RTSP URL、将该URL注册到VIOS）时，请指向NvStreamer端点并遵循
references/nvstreamer-api-reference.md
中的说明。NvStreamer会随所有包含它的VIOS配置文件自动启动；无需单独部署。
关于VIOS如何与其他微服务交互或如何启动的集成和部署相关问题，请分别参考
references/integrate-vios-service.md
和
references/deploy-vios-service.md
（详见上述参考契约表格中各文件的覆盖范围）。

Workflow: sensor name/IP -> clip or snapshot

工作流：传感器名称/IP → 片段或快照

When the user has a sensor name or IP but needs a clip or snapshot:
  1. Verify VST is reachable (see Setup — Availability Check):
    bash
    curl -sf --connect-timeout 5 "http://<VST_ENDPOINT>/vst/api/v1/sensor/version"
  2. List sensors to find 
    sensorId
    :
    bash
    curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/list" | jq .
  3. Get streams for that sensor to find 
    streamId
    (prefer 
    isMain: true
    ):
    bash
    curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/<sensorId>/streams" | jq .
  4. Check timelines to confirm a recording exists in the requested range:
    bash
    curl -s "http://<VST_ENDPOINT>/vst/api/v1/storage/<streamId>/timelines" | jq .
  5. Download clip or snapshot using the 
    streamId
    . Prefer the binary direct endpoints (
    /storage/file/<streamId>?startTime=...&endTime=...
    , 
    /replay/stream/<streamId>/picture?startTime=...
    , 
    /storage/stream/<streamId>/picture?startTime=...
    ) over the 
    /url
    JSON envelope variants — see 
    references/integrate-vios-service.md § Known Integration Constraints
    Finding 8 (the 
    /url
    variants return double-
    http://
    URLs in 2.1.0-26.05.2 and require client-side stripping).
当用户拥有传感器名称或IP但需要获取片段或快照时：
  1. 验证VST是否可达（详见设置——可用性检查）：
    bash
    curl -sf --connect-timeout 5 "http://<VST_ENDPOINT>/vst/api/v1/sensor/version"
  2. 列出传感器以查找
    sensorId
    ：
    bash
    curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/list" | jq .
  3. 获取该传感器的流以查找
    streamId
    （优先选择
    isMain: true
    的流）：
    bash
    curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/<sensorId>/streams" | jq .
  4. 检查时间线以确认请求范围内存在录制内容：
    bash
    curl -s "http://<VST_ENDPOINT>/vst/api/v1/storage/<streamId>/timelines" | jq .
  5. 使用
    streamId
    下载片段或快照。优先使用二进制直接端点（
    /storage/file/<streamId>?startTime=...&endTime=...
    、
    /replay/stream/<streamId>/picture?startTime=...
    、
    /storage/stream/<streamId>/picture?startTime=...
    ）而非
    /url
    JSON封装变体——详见
    references/integrate-vios-service.md § 已知集成限制
    发现8（2.1.0-26.05.2版本中
    /url
    变体返回双重
    http://
    URL，需要客户端手动去除）。

Responses

响应

Success with data: JSON object or array.
Success with no data: 
null
— a 
null
response means the API call succeeded but there is no data to return (e.g. no schedule configured, scan returned no results). It is not an error.
Success with boolean: Some endpoints return 
true
on success (e.g. 
DELETE /sensor/{sensorId}
).
Error: JSON object with 
error_code
and 
error_message
:
json
{
  "error_code": "VMSInternalError",
  "error_message": "VMS internal processing error"
}
Common codes: 
VMSInternalError
, 
VMSNotFound
, 
VMSInvalidParameter
.
If you see 
InvalidParameterError: Failed to get media information
on a PUT upload, this is the libav-missing failure mode — VIOS was deployed without 
VST_INSTALL_ADDITIONAL_PACKAGES=true
. See 
references/deploy-vios-service.md § Known Deployment Issues
Finding 9 for the fix.
If you see double-
http://
prefixes in 
imageUrl
or 
videoUrl
fields on 
/url
-variant responses, that's Finding 8 — strip the leading 
http://
client-side or switch to binary direct endpoints.
**带数据的成功响应：**JSON对象或数组。
无数据的成功响应：
null
——
null
响应表示API调用成功但无数据返回（如未配置调度、扫描无结果）。这并非错误。
**布尔值成功响应：**部分端点在成功时返回
true
（如
DELETE /sensor/{sensorId}
）。
**错误响应：**包含
error_code
和
error_message
的JSON对象：
json
{
  "error_code": "VMSInternalError",
  "error_message": "VMS internal processing error"
}
常见错误码：
VMSInternalError
、
VMSNotFound
、
VMSInvalidParameter
。
若PUT上传时出现
InvalidParameterError: Failed to get media information
错误，这是libav缺失故障模式——VIOS部署时未设置
VST_INSTALL_ADDITIONAL_PACKAGES=true
。请查看
references/deploy-vios-service.md § 已知部署问题
发现9获取修复方案。
若
/url
变体响应的
imageUrl
或
videoUrl
字段中出现双重
http://
前缀，这是发现8的问题——客户端手动去除前缀或切换至二进制直接端点。

Tips

提示

  • jq: All JSON responses are piped through 
    jq .
    for readability. Binary responses (clip download, snapshot) are not — they use 
    -o <file>
    instead.
  • Time format: Always ISO 8601 UTC, e.g. 
    2026-04-10T10:30:00Z
    or 
    2026-04-10T10:30:00.000Z
    .
  • streamId header: Live/replay/recorder endpoints require 
    streamId
    as BOTH a path parameter AND a request header — include both.
  • Large clips: Use the binary direct 
    /storage/file/<id>?...&container=mp4
    endpoint with 
    -o clip.mp4
    for direct streaming. The 
    /url
    envelope variant has the Finding 8 double-
    http://
    defect — avoid until upstream fixes it or use client-side prefix stripping.
  • Sensor vs stream ID: 
    sensorId
    identifies a camera; 
    streamId
    identifies a specific video stream from that camera (a sensor can have a main stream and sub-streams).
  • Identifying sensor type (RTSP vs uploaded file): Call 
    GET /sensor/<sensorId>/streams
    and inspect the 
    url
    field of each stream. If 
    url
    starts with 
    rtsp://
    it is a live RTSP/IP camera stream. If 
    url
    is a file path (e.g. 
    "/home/vst/vst_release/streamer_videos/TruckAccident.mp4"
    ) it is an uploaded file sensor. This determines which delete flow to use — see Section 8.
  • Upload timestamp is honored for the recorded timeline: When uploading a file via 
    PUT /vst/api/v1/storage/file/<filename>?timestamp=<iso>
    , the timeline returned by 
    GET /storage/<streamId>/timelines
    is anchored at the supplied timestamp, not the upload wall-clock time. Subsequent snapshot / clip queries MUST use timestamps within this range — fetch the timeline first. See 
    references/api-reference.md § 8
    and 
    references/integrate-vios-service.md § Integration Interfaces > Inputs > Upload video file
    for the authoritative contract.
  • Endpoint resolution: The VST endpoint is provided by the VSS deployment context. Do not attempt manual IP/port discovery. If unavailable, ask the user. All curl examples use 
    <VST_ENDPOINT>
    as a placeholder — substitute the resolved endpoint before executing.
  • **jq：**所有JSON响应均通过
    jq .
    管道处理以提高可读性。二进制响应（片段下载、快照）除外——它们使用
    -o <file>
    参数。
  • **时间格式：**始终使用ISO 8601 UTC格式，例如
    2026-04-10T10:30:00Z
    或
    2026-04-10T10:30:00.000Z
    。
  • **streamId请求头：**直播/回放/录制器端点要求
    streamId
    同时作为路径参数和请求头——请同时包含两者。
  • **大文件片段：**使用二进制直接端点
    /storage/file/<id>?...&container=mp4
    并添加
    -o clip.mp4
    参数进行直接流式传输。
    /url
    封装变体存在发现8的双重
    http://
    缺陷——在 upstream 修复前请避免使用，或在客户端手动去除前缀。
  • 传感器ID vs 流ID：
    sensorId
    标识摄像头；
    streamId
    标识该摄像头的特定视频流（一个传感器可包含主流和子流）。
  • **识别传感器类型（RTSP vs 上传文件）：**调用
    GET /sensor/<sensorId>/streams
    并检查每个流的
    url
    字段。若
    url
    以
    rtsp://
    开头，则为直播RTSP/IP摄像头流。若
    url
    为文件路径（如
    "/home/vst/vst_release/streamer_videos/TruckAccident.mp4"
    ），则为上传文件传感器。这将决定使用哪种删除流程——详见第8节。
  • **上传时间戳会影响录制时间线：**通过
    PUT /vst/api/v1/storage/file/<filename>?timestamp=<iso>
    上传文件时，
    GET /storage/<streamId>/timelines
    返回的时间线会以提供的时间戳为基准，而非上传时的系统时间。后续的快照/片段查询必须使用该范围内的时间戳——请先获取时间线。权威契约请查看
    references/api-reference.md § 8
    和
    references/integrate-vios-service.md § 集成接口 > 输入 > 上传视频文件
    。
  • **端点解析：**VST端点由VSS部署上下文提供。请勿尝试手动发现IP/端口。若不可用，请询问用户。所有curl示例使用
    <VST_ENDPOINT>
    作为占位符——执行前请替换为解析后的端点。