T Tenstos API
Python SDK · v0.3.1
OpenAPI JSON HTTP API Reference Advanced

TENSTOS EXTERNAL API

Python SDK

다중 카메라 연습 영상을 실시간에 가깝게 확인하고, 캡처 종료 후 다시 탐색하며, 선택한 기록을 회원별 라이브러리에 보관하는 방법을 설명합니다.

처음 사용하는 개발자는 개념을 확인한 뒤 설치와 첫 조회 테스트를 진행하세요. 이후 녹화·다시보기, 웹 화면 연동, 회원별 보관, 고급 재생·분석 순서로 기능을 확장할 수 있습니다.

보안 원칙

Tenstos API Key는 개발자 Backend에만 저장합니다. 브라우저 코드, HTML, 모바일 앱 번들에 장기 API Key를 포함하지 마세요.

01

OVERVIEW

API 연동 흐름

서비스 Backend에서 SDK로 API를 호출하고, 반환된 상태와 재생 URL을 화면에 전달합니다. 브라우저는 재생 URL을 HLS 플레이어에 연결합니다.

사용자 화면Browser UI상태 표시 · HLS 재생
서비스 요청→
개발자 서비스Backend + SDK로그인 · 권한 확인 · API 호출
인증된 API 호출→
TenstosAPI캡처 · 보관 · 재생

캡처와 보관

start()와 stop()으로 사용할 캡처 구간을 지정합니다. 상태 응답에 재생 URL이 제공되면 영상을 표시하고, 완료 후 필요한 기록을 보관할 수 있습니다.

애플리케이션에는 group_id 또는 media_archive_id를 저장하세요. 재생 URL은 만료될 수 있으므로 다시 볼 때 재생 준비 API로 갱신합니다.

02

CAPTURE

핵심 개념과 식별자

API의 start와 stop은 애플리케이션에서 사용할 캡처 구간의 시작과 종료를 지정합니다. 실제 사용 가능한 영상 범위는 상태·재생 응답에서 확인합니다.

영상 시간축
start사용자가 보는 캡처 구간stop
node_id

실제 Recorder 장비 식별자입니다. 장비가 바뀌면 애플리케이션 설정도 새 ID로 갱신합니다.

camera_id

Recorder가 제공하는 카메라 ID입니다. 예: CamA, CamB.

group_id

동시에 시작·종료되는 다중 카메라 캡처 한 건의 ID입니다.

application_id

API Key에 연결된 애플리케이션 경계입니다. 자동 발급 시 Key 또는 소유 사용자 기준으로 생성되며, 같은 ID를 명시한 Key만 Capture Group과 멱등성 상태를 공유합니다.

client_reference_id

애플리케이션이 생성한 요청 ID입니다. 멱등성과 애플리케이션 DB 연결에 사용합니다.

subject_id

애플리케이션의 로그인 사용자를 나타내는 불투명한 ID입니다.

media_archive_id

장기 보관을 선택한 영상 묶음의 영구 식별자입니다.

03

INTEGRATION

공식 연동 방식

REFERENCE

JavaScript SDK

Node.js Backend를 위한 동등한 비동기 SDK입니다. 기존 JavaScript 코드와 새 Node.js 연동에서 사용할 수 있습니다.

FRONTEND

Browser JavaScript

화면과 HLS Player에는 계속 필요합니다. 단, 브라우저는 Tenstos API가 아니라 개발자 Backend의 안전한 route를 호출합니다.

04

SECURITY

API Key Scope

기능필요한 Scope
Recorder와 상태 조회nodes:read
Capture Group 조회sessions:read
Capture Group 생성·시작·종료sessions:write
완료된 Capture Group Playback 준비sessions:write
Media Archive 조회archives:read
Media Archive 생성·수정archives:write
보관 영상 Playback 준비archives:playback
실시간·저장 Inference 조회inference:read
Inference event 구간 영상 Replay·frame 정렬recordings:read

실제 발급 가능한 Scope와 Node 접근 범위는 Tenstos 관리자에게 요청하세요. API Key별로 최소 권한을 사용하는 것이 원칙입니다.

05

DOWNLOAD

SDK·재생 예제 다운로드 · 0.3.1

전체 SDK + 세그먼트 재생 예제 다운로드 · SHA-256

처음 사용하는 경우 다음 설치 단계의 명령으로 필요한 SDK를 바로 설치할 수 있습니다. 전체 묶음은 패키지와 재생 제어 예제를 함께 내려받을 때 선택하세요.

전체 묶음을 내려받은 경우

다운로드한 파일이 있는 폴더에서 압축을 풉니다. 압축 해제 프로그램을 사용해도 됩니다.

tar -xzf tenstos-sdk-0.3.1.tar.gz
cd tenstos-sdk-0.3.1
경로내용과 사용 위치
packages/tenstos-external-api-client-0.3.1.tar.gzPython Backend SDK. 가상환경에서 pip로 설치합니다.
packages/tenstos-external-api-0.3.1.tgz
packages/tenstos-external-api-server-0.3.1.tgz
Node.js core SDK와 Backend wrapper. 두 패키지를 같은 Backend 프로젝트에 설치합니다.
packages/tenstos-external-api-browser-0.3.1.tgzFrontend용 helper. 화면 프로젝트에 설치합니다.
examples/README.md
examples/*.mjs
재생 제어 모듈과 적용 방법입니다. 완성된 웹앱이나 HLS 플레이어는 포함되지 않습니다.

다운로드 무결성을 확인하려면 파일의 SHA-256을 위 체크섬 목록의 같은 파일명과 비교합니다. Linux에서는 sha256sum tenstos-sdk-0.3.1.tar.gz, macOS에서는 shasum -a 256 tenstos-sdk-0.3.1.tar.gz를 사용할 수 있습니다. 이 묶음이 있어도 Python 빌드 도구와 선택적 FastAPI 의존성은 추가 다운로드가 필요할 수 있습니다.

기존 프로젝트의 SDK 업데이트

이미 설치한 프로젝트에서 SDK를 업데이트할 때 사용합니다. Python은 기존 가상환경을 활성화한 뒤 실행하세요.

묶음에는 Python, Node.js, Browser SDK와 재생 제어 예제가 있습니다. 기존 서비스는 SDK를 재설치하고 Backend 재시작·Frontend 재빌드 후 적용하세요. 문서 열람만으로 설치된 SDK가 바뀌지는 않습니다. HTTP API를 직접 호출한다면 SDK 업데이트 없이 아래 계약을 적용할 수 있습니다.

python -m pip install --upgrade "tenstos-external-api-client[fastapi] @ https://api.tenstos.com/docs-assets/downloads/tenstos-external-api-client-0.3.1.tar.gz"

0.3.1은 0.3.0의 세그먼트 재생 지원에 Ball Activity 조회, JavaScript 요청 취소, Retry-After 전달과 재시도·짧은 리플레이 예제를 보충합니다. 기존 wait_for_playback / waitForPlayback은 ready 대기를 유지합니다. 즉시 재생에는 새 wait_until_playable / waitUntilPlayable을 사용하세요.

06

QUICKSTART

개발환경 설치와 설정

선택한 Python 또는 JavaScript SDK로 새 프로젝트를 준비합니다. 아래 명령은 공개 배포 URL에서 SDK를 직접 설치하므로 소스 저장소나 압축 파일을 미리 받을 필요가 없습니다.

시작 전 준비

1. 빈 프로젝트에 SDK 설치

python3 --version
mkdir tenstos-python-demo
cd tenstos-python-demo
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "tenstos-external-api-client @ https://api.tenstos.com/docs-assets/downloads/tenstos-external-api-client-0.3.1.tar.gz"
python -c 'from importlib.metadata import version; print(version("tenstos-external-api-client"))'

마지막 출력은 0.3.1입니다. 이후 명령도 이 폴더와 가상환경에서 실행합니다. 새 터미널에서는 프로젝트 폴더로 이동한 뒤 source .venv/bin/activate를 다시 실행하세요. 기본 SDK에는 FastAPI와 서버 실행기가 포함되지 않으며 Backend 연동 단계에서 추가합니다.

2. 환경변수를 파일에 저장하고 적용

프로젝트 폴더에 .env 파일을 만들고 아래 내용을 저장합니다. API Key를 발급받은 실제 값으로 바꾸세요. TENSTOS_NODE_ID는 첫 목록 조회 후 선택한 값으로 채웁니다. API 주소에는 /v1이나 /docs를 붙이지 않습니다.

TENSTOS_API_BASE='https://api.tenstos.com'
TENSTOS_API_KEY='replace-with-developer-key'
TENSTOS_NODE_ID=''

같은 폴더의 .gitignore에 아래 항목을 추가하세요. 실제 Key는 Backend 환경에만 둡니다.

.env
.venv/
node_modules/
__pycache__/

SDK는 .env를 자동으로 읽지 않습니다. 파일을 만든 뒤 아래 명령으로 현재 터미널의 환경변수로 내보내세요. 새 터미널을 열거나 파일을 수정한 뒤에도 다시 적용합니다.

set -a
source ./.env
set +a

설치 버전이 확인되고 환경변수를 적용했다면, 다음 간단 예제 테스트에서 노드 목록을 조회합니다.

07

FIRST REQUEST

간단 예제 테스트: 노드 목록 조회

앞 단계에서 만든 프로젝트 폴더와 환경변수를 그대로 사용합니다. 이 예제는 접근 가능한 노드를 조회하며 녹화·보관 작업을 시작하지 않습니다.

1. 예제 파일 저장과 실행

프로젝트 폴더에 smoke.py로 저장합니다.

import os
from tenstos_external_api_client import TenstosApiError, TenstosClient

api_key = os.environ.get("TENSTOS_API_KEY", "")
if not api_key or api_key == "replace-with-developer-key":
    raise SystemExit(".env에 실제 API Key를 입력하고 환경변수를 적용하세요.")

tenstos = TenstosClient(
    api_key=api_key,
    base_url=os.environ.get("TENSTOS_API_BASE", "https://api.tenstos.com"),
    timeout=10.0,
)

try:
    nodes = tenstos.recorder_nodes.list()
except TenstosApiError as exc:
    raise SystemExit(f"조회 실패: HTTP {exc.status_code or 'network'}") from None

items = nodes.get("items", [])
print(f"연결 성공: 접근 가능한 노드 {len(items)}개")
for node in items:
    print(node["node_id"], node.get("status"))
    for camera in node.get("cameras", []):
        print("  camera:", camera["camera_id"])
python smoke.py

2. 성공 확인과 다음 단계

연결 성공: 접근 가능한 노드 N개와 노드·카메라 ID가 출력되면 SDK 설치·환경변수·인증·목록 조회가 완료된 것입니다. 0개라도 조회는 성공한 상태이며, 사용할 노드의 등록·접근 권한은 관리자에게 확인하세요. 목록에 노드가 있다고 영상이나 Pose 결과가 현재 제공된다는 뜻은 아닙니다.

사용할 node_id를 .env의 TENSTOS_NODE_ID에 넣고 환경변수를 다시 적용합니다. CamA 등 문서의 카메라 ID도 실제 조회 결과로 바꾸세요.

기본 흐름은 노드 선택 → 용량 확인 → 녹화 시작 → 종료 → 다시보기입니다. 녹화 시작부터 실제 캡처 구간이 생성됩니다.

기본 흐름을 확인한 뒤 웹 화면 연동, 회원별 영상 보관, 세밀한 재생 제어로 확장하세요. 자세 좌표만 필요한 경우에는 inference:read 권한을 준비하고 Pose API 사용법으로 이동할 수 있습니다.

이후 기능별 코드는 기존 서비스에 붙이는 발췌 예제입니다. 위와 같이 생성한 tenstos 클라이언트를 사용하며 node_id/nodeId, 선택한 카메라 목록, 이전 응답의 group_id/groupId 등은 해당 흐름에서 준비해야 합니다. ...나 처리 함수 이름이 있는 예제는 완성된 실행 파일이 아닙니다.

08

SETUP CHECK

설치·첫 연결 문제 해결

증상확인할 내용
python3 / node / npm 명령을 찾을 수 없음해당 런타임을 설치하고 새 Bash 터미널을 엽니다. Python과 Node.js 중 선택한 경로의 도구만 필요합니다.
venv 생성 시 ensurepip 오류OS의 Python venv 구성요소를 설치합니다. Ubuntu/Debian에서는 사용 중인 Python 버전에 맞는 python3-venv 패키지를 확인한 뒤 가상환경 생성을 다시 실행합니다.
externally-managed-environment / ModuleNotFoundError가상환경을 활성화하고 같은 python -m pip로 설치·실행합니다. 시스템 Python에 전역 설치할 필요는 없습니다.
ERR_MODULE_NOT_FOUND / import 구문 오류설치한 프로젝트 폴더에서 node smoke.mjs를 실행하세요. Server wrapper는 core SDK와 함께 설치하며, Browser helper를 Backend SDK 대신 사용하지 않습니다.
API Key 누락 / 환경변수 KeyError.env만 생성해서는 적용되지 않습니다. 실행할 터미널에서 set -a → source ./.env → set +a를 실행하세요.
HTTP 401 / 403401은 Key 유효성, 403은 요청 기능의 Scope와 노드 접근 권한을 확인합니다. 첫 조회에는 nodes:read가 필요합니다.
HTTP 404 / JSON 대신 HTML 응답TENSTOS_API_BASE=https://api.tenstos.com인지 확인하세요. 문서 주소나 /v1을 base URL에 넣지 않습니다.
다운로드·설치의 DNS / TLS / timeout 오류외부 HTTPS 접근, 프록시, 시스템 시각·인증서를 확인합니다. pip/npm 의존성 저장소 접근도 필요합니다. 인증서 검증을 끄는 방식으로 해결하지 마세요.
Backend /health 성공, /bootstrap 실패/health는 로컬 설정 확인입니다. 실제 Key·외부 API 연결은 /bootstrap으로 확인합니다.
로컬 서버 접속 실패 / address already in use서버 터미널이 실행 중인지 확인하세요. 8080 포트를 사용 중이면 서버와 확인 URL의 포트를 함께 바꿉니다.
09

CAPTURE

Recorder와 카메라 조회

캡처 전에 접근 가능한 Recorder와 카메라 목록을 조회합니다. 카메라 ID를 화면에 하드코딩하지 말고 조회 결과를 기준으로 선택합니다. 장비가 변경되면 목록을 다시 조회하고 요청마다 사용할 node_id를 지정하세요.

nodes = tenstos.recorder_nodes.list()

for node in nodes.get("items", []):
    print(node["node_id"], node.get("status"))
    for camera in node.get("cameras", []):
        print(" -", camera["camera_id"])

health = tenstos.recorder_nodes.health("recorder-node-001")
10

CAPTURE

Node별 캡처 용량 조회

Capture Group 시작 전에 선택한 Recorder에서 현재 API Key의 애플리케이션이 사용할 수 있는 카메라 슬롯을 조회합니다. 다른 API Key의 개별 식별자는 반환하지 않으며 전체·Node·현재 애플리케이션 집계만 제공합니다.

capacity = tenstos.capture_groups.capacity("recorder-node-001")
available = capacity["application"]["available"]

if len(selected_camera_ids) > available:
    raise RuntimeError("선택한 카메라 수가 현재 가용 슬롯보다 큽니다.")
필드의미
application현재 API Key의 running, reserved, used, available, max_slots, active_groups
node선택한 NODE_ID에서 실행 중인 Group·카메라 슬롯·애플리케이션 수
global전체 캡처 용량과 사용량
policy애플리케이션별 슬롯 및 Node별 동시 Group 제한
11

CAPTURE

연습 녹화 시작

coaching.start_practice()는 Capture Group 생성과 시작을 하나의 기능으로 묶습니다.

practice = tenstos.coaching.start_practice(
    node_id="recorder-node-001",
    camera_ids=["CamA", "CamB", "CamC", "CamD"],
    client_reference_id="practice-20260831-0001",
    title="포핸드 자세 교정",
    duration_sec=600,
    metadata={"lesson_id": "lesson-1042"},
    wait_until_streaming=False,
)

group_id = practice["group_id"]
멱등성

네트워크 오류로 시작 요청을 다시 보내도 같은 client_reference_id를 사용하세요. Coaching helper는 이를 기반으로 생성 요청의 멱등성 Key를 구성합니다. 동일한 문자열을 다른 API Key가 사용해도 애플리케이션별 namespace가 분리됩니다.

12

CAPTURE

사용자에게 진행 상태 표시

웹 요청을 오랫동안 열어 두기보다 짧은 Polling으로 Capture Group을 조회하고 UI에 현재 단계를 보여주세요.

created요청 생성
→
starting시작 지시
→
preparing영상 준비
→
streaming재생 가능
→
draining잔여 영상 수신
→
ready최종 준비
group = tenstos.capture_groups.get(group_id)
status = group["status"]

for camera in group.get("cameras", []):
    delivery = camera.get("delivery", {})
    print(
        camera["camera_id"],
        delivery.get("status"),
        delivery.get("playlist_url"),
    )
상태화면에 권장하는 설명UI 동작
created / starting연습 기록을 시작하고 있습니다.시작 버튼 잠금
preparing카메라 영상을 준비하고 있습니다.카메라별 준비 상태 표시
streaming실시간에 가까운 영상이 들어오고 있습니다.준비된 화면부터 재생
draining마지막 영상을 정리하고 있습니다.기존 영상 재생 유지
ready전체 연습 영상이 준비되었습니다.전체 Seek 활성화
partial / failed일부 또는 전체 영상을 준비하지 못했습니다.재시도·운영 문의 안내
13

CAPTURE

연습 녹화 종료

종료 요청 직후에는 마지막 segment가 도착하는 draining 단계가 존재할 수 있습니다. ready가 될 때까지 상태를 조회합니다.

duration_sec에 도달하면 API가 같은 stop 절차를 자동 실행하며 응답의 auto_stopped가 true가 됩니다. 수동 stop과 자동 stop이 겹쳐도 하나의 상태 전이만 수행됩니다.

stopped = tenstos.coaching.stop_practice(
    group_id,
    note="연습 종료",
    wait_until_ready=False,
)

# Worker, CLI 또는 테스트에서만 blocking helper 사용을 권장합니다.
ready = tenstos.capture_groups.wait_until_ready(
    group_id,
    timeout_sec=180,
)
14

PLAYBACK

보관하지 않은 연습 다시보기

완료된 Capture Group의 group_id를 저장하면, 재생 URL이 만료된 뒤에도 영상이 제공되는 동안 같은 캡처 구간의 Playback을 다시 요청할 수 있습니다.

import time

playback = tenstos.capture_groups.prepare_playback(
    group_id,
    ttl_seconds=3600,
)

while playback["status"] == "preparing":
    time.sleep(1)
    playback = tenstos.capture_groups.prepare_playback(
        group_id,
        ttl_seconds=3600,
    )

for camera in playback.get("cameras", []):
    print(camera["camera_id"], camera["playlist_url"])
수명관리 위치만료 후 처리
연습 목록개발자 애플리케이션 DB서비스 정책에 따라 며칠간 group_id 유지
임시 Playback유효 기간이 있는 재생 URLprepare_playback() 재호출
장기 보관Media Archive별도 보관본에서 Playback 준비
예제 기본값

multi-camera-coaching-review-session-python은 미보관 연습 메타데이터를 7일간 유지하고, 임시 Playback URL은 1시간으로 준비합니다. HLS network error가 발생하면 선택한 Group의 Playback을 자동으로 다시 확인합니다.

15

SECURITY

회원 식별과 책임 경계

애플리케이션이 담당

  • 사용자 등록과 로그인
  • 애플리케이션 Session과 권한
  • subject_id 결정
  • 캡처 목록과 메타데이터
  • UI 상태와 Player

Tenstos가 담당

  • Recorder와 카메라 조회
  • 캡처 구간 생성·시작·종료
  • 영상 준비 상태
  • 회원 식별자별 Media Archive
  • 재생 URL 준비
16

BACKEND

로컬 Backend 실행과 Browser 연결

첫 API 조회를 마친 프로젝트에서 이어서 실행합니다. Python 또는 Node.js 중 하나를 선택하세요. 아래는 로그인 기능을 연결하기 전의 로컬 개발 예제로 127.0.0.1:8080에서만 실행합니다. 외부 공개 전에는 전체 /api/tenstos 경로에 서비스의 인증·접근 제어를 연결하세요.

1. 의존성 설치와 server.py 작성

활성화한 가상환경에서 실행합니다. FastAPI extra와 서버 실행기 Uvicorn을 함께 설치합니다.

python -m pip install "tenstos-external-api-client[fastapi] @ https://api.tenstos.com/docs-assets/downloads/tenstos-external-api-client-0.3.1.tar.gz" uvicorn

프로젝트 폴더에 server.py로 저장합니다.

import os
from fastapi import FastAPI
from tenstos_external_api_client import TenstosClient
from tenstos_external_api_client.fastapi import create_tenstos_router

app = FastAPI()
tenstos = TenstosClient(
    api_key=os.environ["TENSTOS_API_KEY"],
    base_url=os.environ.get("TENSTOS_API_BASE", "https://api.tenstos.com"),
    timeout=10.0,
)
app.include_router(create_tenstos_router(
    tenstos,
    prefix="/api/tenstos",
    service_name="tenstos-local-demo",
    default_node_id=os.environ.get("TENSTOS_NODE_ID", ""),
))

2. 로컬 서버 실행

python -m uvicorn server:app --host 127.0.0.1 --port 8080

이 터미널은 열어 둡니다. 종료는 Ctrl+C입니다. Python SDK는 동기식이므로 직접 작성한 async def route에서는 run_in_threadpool()로 호출을 분리하세요. 제공된 wrapper는 일반 def route를 사용합니다.

3. 로컬 설정과 실제 API 연결을 각각 확인

다른 터미널에서 다음 GET 요청을 실행하거나 브라우저에서 각 주소를 엽니다. curl이 없다면 브라우저로 확인해도 됩니다.

curl --fail-with-body http://127.0.0.1:8080/api/tenstos/health
curl --fail-with-body http://127.0.0.1:8080/api/tenstos/bootstrap

/health의 ok: true와 api_key_configured: true는 로컬 서버와 Key 설정 여부를 뜻합니다. Key의 유효성까지 확인한 것은 아닙니다. /bootstrap이 HTTP 200으로 ok: true, nodes, capabilities를 반환해야 외부 API 연결까지 확인한 것입니다. 이 조회에는 nodes:read가 필요합니다.

4. Browser helper 연결 (선택)

화면 개발 시 사용하는 npm 기반 Frontend 프로젝트에서 설치합니다. Python Backend를 선택했더라도 Browser helper는 JavaScript 패키지입니다.

npm install https://api.tenstos.com/docs-assets/downloads/tenstos-external-api-browser-0.3.1.tgz
import { TenstosBrowserClient } from "@tenstos/external-api-browser";

const api = new TenstosBrowserClient({ basePath: "/api/tenstos" });
const bootstrap = await api.bootstrap();
console.log(bootstrap.nodes);

이 코드는 Frontend 빌드 도구에서 가져오는 모듈 예제입니다. HTML에 패키지 이름을 그대로 import하거나 file://로 열면 실행되지 않습니다. Frontend 개발 서버의 /api/tenstos를 위 Backend로 프록시하거나, 페이지와 Backend를 같은 origin으로 제공하세요. API Key는 Frontend 환경변수나 코드에 넣지 않습니다. 이 SDK는 화면·로그인·HLS 플레이어를 포함하지 않습니다.

5. 회원별 보관 기능 연결

위 로컬 예제는 회원 보관 경로를 활성화하지 않으므로 /media-archives 요청은 404입니다. 실제 서비스에서는 로그인 세션에서 회원 식별자를 반환하는 Python subject_resolver(request) 또는 JavaScript subjectResolver(request)를 구현하고 router/handler 생성 옵션에 전달하세요. 브라우저가 보낸 임의의 회원 ID를 그대로 사용하지 않습니다. 세션 인증 자체는 SDK가 제공하지 않으며, 보관 기능에는 해당 archives Scope도 필요합니다.

17

PLAYBACK

다중 카메라 동기화

같은 Capture Group의 카메라는 공통 source segment index 경계를 기준으로 구성됩니다. Backend는 API가 반환한 카메라별 playlist를 그대로 전달하고, Browser Player는 같은 Group의 재생 위치와 재생 속도를 함께 제어합니다.

18

ARCHIVE

선택한 연습을 회원별로 보관

Capture Group이 ready가 된 후, 사용자가 보관을 선택한 영상만 별도 장기 보관 영역의 Media Archive로 생성합니다. 일반 캡처 재생과 장기 보관은 서로 다른 상태로 관리됩니다.

archive = tenstos.coaching.retain_practice(
    subject_id="member_8f2a1c",
    capture_group_id=group_id,
    client_reference_id="practice-20260831-0001",
    title="포핸드 자세 교정",
    metadata={"lesson_id": "lesson-1042"},
    wait_until_ready=False,
)

media_archive_id = archive["media_archive_id"]

애플리케이션 DB에는 group_id, media_archive_id, 제목, 사용자 ID, 생성 시각 등 필요한 참조 정보를 저장합니다.

19

ARCHIVE

회원의 보관 목록 조회

library = tenstos.archives.list(
    subject_id="member_8f2a1c",
    collection_id="coaching-practices",
    limit=100,
)

for item in library.get("items", []):
    print(item["media_archive_id"], item["status"], item.get("title"))

Backend는 로그인한 사용자의 subject_id만 사용해야 합니다. Browser 요청에서 임의의 사용자 ID를 받아 그대로 SDK에 넘기지 마세요.

20

ARCHIVE

보관 영상 다시보기

재생할 때마다 짧게 유효한 Playback URL을 준비합니다. URL 자체를 영구 저장하지 말고 media_archive_id를 저장하세요.

playback = tenstos.archives.wait_until_playable(
    media_archive_id,
    camera_ids=["CamA", "CamB", "CamC", "CamD"],
    ttl_seconds=3600,
)

for camera in playback.get("cameras", []):
    print(camera["camera_id"], camera["playlist_url"])
21

SEGMENT PLAYBACK

전체 다운로드 없이 재생·seek하기

API의 playlist_url을 HLS 플레이어에 연결하고 현재 위치 주변만 버퍼링합니다. 전체 TS 다운로드나 Blob 병합, 추론 결과 전체 로딩을 재생 시작 조건으로 두지 않습니다. playlist 메타데이터 전체 조회와 영상 전체 다운로드는 다릅니다.

1. 영상 준비와 재생 시작

대상재생 준비아직 playlist에 없는 위치로 seek
일반 녹화POST /v1/recording-nodes/{node_id}/recording-vod-jobsPOST /v1/recording-vod-jobs/{job_id}/playback-views
보관 영상POST /v1/media-archives/{media_archive_id}/playbackPOST /v1/media-archives/{media_archive_id}/playback-views

일반 녹화 요청에는 camera_id, start_unix, end_unix, 선택적 session_id를 보냅니다. 구간은 최대 1시간·1,000개 완료 세그먼트입니다. 응답 또는 GET /v1/recording-vod-jobs/{job_id}에서 URL이 생기면 uploading이어도 재생합니다. 전체 타임라인 길이는 duration_sec, 현재 공개 구간은 available_duration_sec입니다.

보관 영상은 Archive 자체가 ready인 뒤 재생을 요청합니다. cameras[]의 URL을 사용하며 재생 준비의 전체 진행률 100%를 기다릴 필요는 없습니다. HTTP 202는 전체 다운로드를 기다리라는 의미가 아닙니다.

playback = tenstos.archives.wait_until_playable(
    media_archive_id, camera_ids=["CamA"], timeout_sec=180,
)
# Backend는 이 descriptor를 Browser로 전달합니다.
# Browser는 cameras[0].playlist_url을 HLS player에 연결합니다.

2. seek 위치의 세그먼트부터 준비

현재 playlist의 video.seekable 안에서는 일반 seek를 사용합니다. 그 밖의 위치는 playback view를 요청합니다. 일반 녹화는 job 기준 position_sec를 보내고, 반환된 view_id로 GET /v1/recording-vod-jobs/{job_id}/playback-views/{view_id}를 조회합니다. 같은 화면에서 view_id를 재사용하고 새 seek마다 generation을 증가시킵니다.

보관 영상은 position_sec 또는 timestamp_unix 중 하나와 안정적인 view_key, 증가하는 generation을 보냅니다. URL 준비 중에는 같은 요청을 poll_after_sec 간격으로 반복합니다. 선택적 window_sec는 재생 구간을 제한하며, 끝까지 이어 재생하려면 생략합니다.

view = tenstos.archives.prepare_playback_views(
    media_archive_id, camera_ids=["CamA"], position_sec=125.4,
    view_key="review-main", generation=2,
)

새 URL 연결 후 실제 seek 값은 position_in_view_sec입니다. 일반 녹화의 화면 시각은 timeline_offset_sec + video.currentTime, 보관 영상 view는 requested_position_sec - position_in_view_sec + video.currentTime으로 복원합니다. 늦게 도착한 이전 seek 응답과 이전 player 이벤트를 무시하고, 카메라마다 반환된 보정값을 적용하세요.

3. 추론 결과를 현재 세그먼트만 조회

GET /v1/recording-nodes/{node_id}/aligned-segments?start_unix=...&end_unix=...&include_signed_urls=true는 (session_id, segment_index)별 영상·추론 파일 descriptor를 반환합니다. camera, artifact_kind는 반복 필터입니다. 공통 fusion 결과가 필요하면 camera 필터에 shared도 포함합니다.

has_more가 있으면 next_cursor를 그대로 전달하고, 페이지 경계의 같은 세그먼트를 합칩니다. 현재 세그먼트의 필요한 결과 파일만 signed URL로 읽으며, 프레임 위치는 segment_start_in_vod + frame_times[i]입니다. 선택한 카메라의 실제 영상 길이로 세그먼트 시작점을 계산하고 녹화 공백·세션 전환을 고려하세요. 요청 시작 Unix 시각에 currentTime을 더하는 방식은 공백이 있는 녹화에서 맞지 않습니다.

추론 파일 누락은 빈 overlay로 처리하고 영상은 계속 재생합니다. signed URL은 만료 시 재발급하며 영구 저장하지 않습니다. 조회에는 recordings:read, 보관 영상 재생에는 archives:playback이 필요합니다. 별도 /v1/inference-results를 사용하면 inference:read가 필요합니다.

4. SDK·Wrapper 지원 범위

기능Python / Node.js SDKBrowser helper + Backend wrapper
일반 녹화 재생·seekrecording_node_vod_job / recordingNodeVodJob, recording_vod_job / recordingVodJob, recording_vod_view / recordingVodView, recording_vod_view_status / recordingVodViewStatusBrowser의 camelCase 메서드. 양쪽 wrapper 모두 /recording-nodes/{node_id}/vod-jobs, /recording-vod-jobs/{job_id}, view POST/GET 지원
세그먼트 + 추론 조회inference.aligned_segments / inference.alignedSegmentsrecordingNodeAlignedSegments → /recording-nodes/{node_id}/aligned-segments
보관 영상 seekarchives.prepare_playback_views / archives.preparePlaybackViewsarchives.preparePlaybackViews → /media-archives/{id}/playback-views
재생 가능 시점 대기archives.wait_until_playable / archives.waitUntilPlayable첨부 예제에서 URL 기준 폴링·취소·시간 보정 처리

Wrapper URL의 기본 prefix는 /api/tenstos입니다. 보관 영상 wrapper 응답은 {ok, playback}, 녹화 job/view와 aligned 응답은 최상위 descriptor입니다. 회원 보관 영상은 인증 Session의 소유권을 확인합니다. Ball Activity 조회는 아래 보충 안내를 참고하세요. 별도 inference result/live 호출 등 모든 REST 기능을 Browser wrapper가 감싸는 것은 아니며, 위 표는 이번 재생 흐름의 지원 범위입니다.

다운로드 예제의 segment-playback.mjs를 기존 HLS player에 연결하세요. 예제는 API 호출과 재생 제어를 제공하며 player UI·라이브러리는 포함하지 않습니다. 첫 URL로 재생, 먼 위치 seek, 연속 seek 응답 역전, 타임라인·추론 정렬을 검수하세요.

22

PLAYBACK DETAILS · SDK 0.3.1

버퍼링·카메라 전환·짧은 리플레이

실제 재생 화면에서 검증한 흐름을 공개 API 기준으로 정리했습니다. 아래 버퍼 길이와 UI 동작은 구현 예시이며 API의 고정 제약이 아닙니다. SDK 0.3.1과 보충 예제를 함께 사용하세요.

준비 완료와 화면 재생을 구분

Archive 자체의 ready, 재생 URL 제공, 브라우저의 영상 디코딩은 서로 다른 단계입니다. URL이 나온 뒤에도 첫 세그먼트 수신이 늦으면 버퍼링 상태를 표시합니다. loadedmetadata만으로 프레임이 표시됐다고 판단하지 말고, 실제 canplay·seeked와 준비 상태를 확인하세요. 프레임 관측이 필요하면 지원 브라우저의 requestVideoFrameCallback이 전달하는 mediaTime을 사용합니다.

준비 중에는 seek·프레임 이동·장면 저장을 잠시 제한하되 닫기·다른 장면 선택·카메라 전환은 가능하게 합니다. 닫기나 대기만으로 장면을 저장하지 않습니다. 이미 삭제된 영상이나 충돌한 세션을 다른 시각의 영상으로 대체하지 않습니다.

한 번에 하나씩 재조회하고 이전 요청 취소

첨부 playback-wait.mjs는 준비 중 응답을 처음 10회 1초 간격, 이후 2·4·5초 간격으로 확인합니다. 네트워크 오류와 HTTP 429·502·503·504는 2·4·8·10초 간격으로 재시도하며, Retry-After 또는 응답 대기 시간이 더 길면 이를 따릅니다. 한 요청은 기본 20초, 전체 대기는 기본 180초로 제한합니다. 이 값들은 조정 가능한 예제 정책입니다.

401·403·404·409·422 등은 자동 대기로 감추지 않습니다. 특히 Archive가 아직 준비되지 않은 409는 Archive 상태 흐름에서 처리한 뒤 재생을 요청하세요. 브라우저의 HTTP 요청에는 AbortSignal을 전달하고, 장면 변경·닫기·페이지 종료 시 요청과 타이머를 취소합니다. generation 확인은 취소와 함께 유지합니다. 브라우저 요청 취소가 이미 시작된 서버 작업의 취소를 의미하지는 않습니다.

JavaScript SDK/Browser helper의 재생·세그먼트·Ball Activity 메서드는 signal 옵션을 받습니다. 상태 조회는 recordingVodJob(jobId, {signal}), recordingVodViewStatus(jobId, viewId, {signal}) 형태입니다. 취소 가능한 재시도는 첨부 예제의 기능이며 기존 SDK의 모든 요청이 자동으로 재시도되는 것은 아닙니다.

짧은 이벤트 리플레이와 시간 보정

전체 영상을 다시 준비하지 말고 보관 영상의 playback-views에 요청 시작 timestamp_unix와 window_sec를 전달합니다. 예를 들어 이벤트 전후 2.2초는 시작 시각을 이벤트 − 2.2초, 길이를 4.4초로 지정합니다. 이 수치는 UI 선택이며 장면의 실제 범위에 맞게 조정합니다. 현재 배포 방식에서 반환된 playlist와 가용 범위를 확인하세요.

requested_start = event_unix - 2.2
view = tenstos.archives.prepare_playback_views(
    media_archive_id, camera_ids=["CamA"], timestamp_unix=requested_start,
    window_sec=4.4, view_key="review-main", generation=3,
)
# cameras[]에 URL이 있으면 player에 연결합니다.
# 연속된 짧은 구간에서 이벤트의 view 내 위치:
# camera["position_in_view_sec"] + event_unix - requested_start

재생 목록은 세그먼트 경계에서 시작하므로 요청 시각보다 앞선 프레임을 포함할 수 있습니다. window_sec는 프레임 단위 재인코딩·정확한 클리핑 보장이 아닙니다. 필요한 표시 시작·종료는 UI에서도 제한합니다. position_in_view_sec에는 경계 보정이 이미 반영되어 있으므로 같은 보정을 두 번 더하지 않습니다. 저장된 프레임·클립의 시간 원점을 보존하고, 보관 구간 경계로 앞부분을 줄였다면 이벤트 표시와 추론 시간축도 한 번만 함께 이동합니다. 시간 중간에 공백이 있으면 위 선형식 대신 세그먼트별 매핑을 사용합니다.

카메라 전환은 같은 촬영 시각으로

전환 직전의 원본 시각, 세션, 일시정지 여부와 재생 속도를 유지합니다. 새 카메라에는 같은 절대 timestamp_unix를 요청하고 그 카메라의 position_in_view_sec를 적용합니다. playlist마다 원점이 다를 수 있어 이전 video.currentTime을 그대로 복사하면 안 됩니다. 원본 시각은 세그먼트 metadata로 매핑하고, playlist에 Program Date Time이 제공되는 경우에만 이를 사용할 수 있습니다. 모든 공개 playlist가 이 태그를 제공한다고 가정하지 마세요.

새 카메라가 같은 시각을 표시할 수 있을 때 전환하고 실패하면 기존 카메라를 유지합니다. 끊김 없는 전환이 필요하면 별도 staging video에서 준비한 뒤 교체합니다. 첨부 제어 예제는 paused·playbackRate를 player adapter에 전달하며, staging과 실제 화면 전환은 UI에서 구현합니다. 이전 player, 이벤트 listener, 프레임 callback은 전환 완료 또는 화면 종료 시 해제합니다.

목록·가용 구간·버퍼를 구분

전체 playlist가 있어도 영상 전체를 받을 필요는 없습니다. video.seekable은 탐색 가능한 범위, video.buffered는 현재 브라우저에 받은 범위입니다. 뒤쪽 버퍼가 정리됐다는 이유로 원본 영상이 사라졌다고 표시하지 않습니다. 반대로 metadata에 존재한다는 이유만으로 최신 영상이 이미 표시 가능하다고 판단하지 않습니다.

검증 예제의 연속 재생은 약 두 세그먼트의 여유와 6초 목표·8초 상한·4초 과거 버퍼를 사용했고, 전체 경기 VOD 화면은 20초 목표 버퍼를 사용했습니다. 이는 시작점이며 세그먼트 길이·네트워크·동시 카메라 수에 맞게 조정합니다. 수십 초 목록을 유지하는 것과 수십 초 영상 전체를 선다운로드하는 것은 다릅니다.

추론 파일과 프레임 축은 필요한 것만

공 추적 확대뷰에는 우선 선택 카메라의 ball 결과를 조회합니다. 필요한 프레임 축이 그 파일에 있으면 fusion·player를 추가로 받지 않습니다. 예제의 loadCurrentSidecars는 기본 artifactKinds: ["ball"]이며 필요한 종류를 명시해서 확장할 수 있습니다. live semantic event 수신과 영상·저장 추론 데이터 준비는 서로 막지 않게 구성합니다.

프레임 이동과 overlay는 실제 frame_times를 사용합니다. 추론 샘플 수나 고정 30fps를 영상 프레임으로 단정하지 않습니다. 배열이 없거나 유효하지 않으면 프레임 정밀 기능을 비활성화하고 추정치를 실제 측정값으로 저장하지 마세요. 공개 API의 세그먼트 식별자와 결과 파일의 실제 필드를 사용하며 특정 예제의 보정된 frame 필드를 API 공통 필드로 가정하지 않습니다.

Ball Activity는 영상과 독립적으로 조회

GET /v1/media-archives/{media_archive_id}/ball-activity는 전체 ball 파일을 브라우저로 받지 않고 경기 활동의 요약 bins를 조회합니다. Python은 archives.ball_activity(id), Node/Browser는 archives.ballActivity(id)를 사용합니다. 회원 wrapper는 /api/tenstos/media-archives/{id}/ball-activity이며 응답은 {ok, activity}입니다. API key에는 archives:playback이 필요하고 회원 소유권 확인이 적용됩니다.

preparing은 HTTP 202로 진행률과 다음 조회 시간을 표시하고 재조회합니다. ready의 bins[].start_sec/end_sec는 보관 영상 기준입니다. view 재생 중에는 앞서 설명한 timeline offset으로 현재 위치를 복원합니다. unavailable 또는 failed이면 활동 표시만 비활성화하고 영상은 계속 재생합니다. 히트맵 클릭은 같은 seek 흐름을 사용하며, 이 요약은 프레임 단위 추론 overlay를 대신하지 않습니다.

23

REALTIME

범용 Inference stream

Ball, pose와 이후 모델 결과를 같은 API로 소비합니다. 기본 요청은 프레임별 관측치를 제외하고 bounce 등의 이벤트를 전달합니다. 좌표가 필요한 경우 관측치 포함 옵션을 사용하세요.

snapshot = tenstos.inference.snapshot(
    node_id,
    kinds=["object.track.3d"],
    include_observations=False,
)

for event in tenstos.inference.events(
    node_id,
    kinds=["object.track.3d"],
    include_observations=False,
):
    if event["event"] == "inference.packet":
        handle_semantic_events(event["data"].get("e", []))

영상과 저장 inference를 frame 단위로 맞추기

Replay seekbar, 확대뷰처럼 영상과 여러 결과 파일을 함께 탐색할 때는 응답의 (session_id, segment_index) 묶음을 사용합니다. 같은 묶음의 결과 파일 frame_times는 해당 영상 segment 시작에 상대적인 시간이므로 packet 도착 시각을 다시 환산하지 않습니다.

aligned = tenstos.inference.aligned_segments(
    node_id,
    start_unix=start_unix,
    end_unix=end_unix,
    cameras=["CamA", "shared"],
    artifact_kinds=["video", "ball", "fusion"],
    include_signed_urls=True,
)
↓
필요한 데이터만 요청

궤적을 매 frame 표시할 때만 include_observations를 켜고 max_hz를 제한하세요. Replay에서는 aligned descriptor의 signed URL 중 필요한 결과 파일만 읽습니다. 반환된 URL로 필요한 파일을 읽으세요.

24

POSE

Pose API 사용법

사람의 2D 관절 좌표를 조회해 자세 표시, 동작 구간 탐색, 영상 비교에 사용할 수 있습니다. API Key는 서비스 Backend에만 두고, 브라우저에는 서비스에서 허용한 결과만 전달하세요. 아래 SDK 예제는 첫 API 호출에서 만든 Backend용 tenstos 클라이언트를 사용합니다.

목적에 맞는 조회 방식

목적API선택 기준
최신 자세를 작은 창에 표시GET /v1/inference-streams/poses카메라별 최신 프레임만 반환합니다. 과거 프레임 목록은 포함하지 않습니다.
실시간 관절 좌표를 연속 수신GET /v1/inference-streams/snapshot
GET /v1/inference-streams/events
Pose 종류로 필터하고 관측치 포함을 켭니다. 재연결과 누락 처리가 필요합니다.
스윙 구간 분석·영상과 프레임 맞추기GET /v1/recording-nodes/{node_id}/aligned-segments같은 구간의 영상과 저장된 자세 결과를 조회합니다. 자세 결과가 제공되는 구간에 사용할 수 있습니다.
!
최신 자세 조회와 전체 프레임 수집은 다릅니다

/poses를 자주 호출해도 모든 프레임을 수집한다는 보장은 없습니다. 손목 속도 피크나 정확한 동작 시점을 찾을 때는 프레임 간격과 누락을 확인할 수 있는 연속 관측 또는 저장 결과를 사용하세요. 조회 요청은 새 분석 작업을 시작하지 않으며, 데이터 제공 여부와 관절 검출 품질은 노드·카메라·구간에 따라 다릅니다.

1. 최신 자세 요청

필요 권한은 inference:read와 요청한 노드의 접근 권한입니다. REST 인증은 Authorization: Bearer <API_KEY>입니다.

GET /v1/inference-streams/poses?node_id=example-node&camera=CamA&camera=CamB&max_age_sec=3
Query필수 / 기본값설명
node_id필수접근 가능한 노드 식별자입니다.
camera선택카메라 식별자입니다. 여러 카메라는 같은 파라미터를 반복하며 최대 16개입니다. 생략하면 결과가 있는 카메라 중 최대 16개를 반환합니다.
max_age_sec선택 / 3API 수신 시각 기준 최신 자세의 유효 시간(초)입니다. 범위는 0.5~10입니다. 과거 조회 범위나 FPS 설정이 아닙니다.
from urllib.parse import urlencode

query = urlencode({
    "node_id": "example-node",
    "camera": ["CamA", "CamB"],
    "max_age_sec": 3,
}, doseq=True)
poses = tenstos.request(f"/v1/inference-streams/poses?{query}")
names = poses["keypoint_names"]
for item in poses["items"]:
    if item["status"] != "ready":
        continue
    for person in item["people"]:
        joints = dict(zip(names, person["keypoints"]))
        x, y, confidence = joints["left_wrist"]
        if confidence >= 0.3:  # 표시용 예시 기준. 서비스에 맞게 조정합니다.
            print(item["camera_id"], item["frame_number"], x, y)

다운로드 SDK 0.3.1에는 최신 자세 전용 메서드가 없으므로 위 예제는 공통 request()를 사용합니다. 인증 헤더는 클라이언트가 설정합니다. HTTP Query 이름은 camera이며 여러 값을 반복해서 보냅니다. Browser helper가 모든 inference 호출을 대신 제공하는 것은 아니므로, 서비스 Backend에서 인증·노드 접근을 확인하는 조회 경로를 구성하세요.

2. 응답과 관절 순서

아래는 카메라 1대에서 사람 1명이 관측된 예시입니다. 식별자와 시각·좌표는 설명용 값입니다.

{
  "schema_version": "1.0",
  "node_id": "example-node",
  "checked_at_unix": 1800000000.2,
  "coordinate_space": "stored_video_normalized",
  "keypoint_names": [
    "nose", "left_eye", "right_eye", "left_ear", "right_ear",
    "left_shoulder", "right_shoulder", "left_elbow", "right_elbow",
    "left_wrist", "right_wrist", "left_hip", "right_hip",
    "left_knee", "right_knee", "left_ankle", "right_ankle"
  ],
  "items": [{
    "camera_id": "CamA",
    "stream_id": "example-pose-stream",
    "session_id": "example-session",
    "status": "ready",
    "received_at_unix": 1800000000.0,
    "frame_number": 120,
    "people": [{
      "keypoints": [
        [0.50, 0.18, 0.95], [0.51, 0.17, 0.90], [0.49, 0.17, 0.90],
        [0.53, 0.18, 0.85], [0.47, 0.18, 0.85],
        [0.58, 0.30, 0.95], [0.42, 0.30, 0.95],
        [0.64, 0.43, 0.92], [0.36, 0.43, 0.92],
        [0.66, 0.56, 0.88], [0.34, 0.56, 0.88],
        [0.55, 0.56, 0.95], [0.45, 0.56, 0.95],
        [0.56, 0.73, 0.91], [0.44, 0.73, 0.91],
        [0.57, 0.91, 0.87], [0.43, 0.91, 0.87]
      ]
    }]
  }]
}
필드설명
schema_version응답 형식 버전입니다.
checked_at_unix응답의 유효 상태를 확인한 UTC Unix 시각(초)입니다.
coordinate_spacestored_video_normalized: 저장 영상 기준 정규화 좌표입니다.
keypoint_names각 keypoints 배열의 이름·순서입니다. 응답의 이름으로 관절을 매핑하세요.
items카메라별 결과입니다. 요청한 카메라라도 자세 결과가 없으면 항목이 생략될 수 있습니다.
camera_id / stream_id / session_id관측을 구분하는 식별자입니다. 세션·스트림이 바뀌면 이전 자세와 궤적을 초기화하세요.
statusready: 표시 가능한 자세 있음. waiting: 현재 유효한 자세 없음.
received_at_unixAPI가 결과를 받은 시각입니다. 촬영 시각이나 영상 재생 위치가 아닙니다.
frame_number결과의 프레임 번호입니다. 대기 상태에서는 null입니다. 단독으로 영상의 재생 초를 의미하지 않습니다.
people해당 프레임의 최대 4명입니다. 배열 순서는 고정된 사람 ID나 회원 ID가 아닙니다.
people[].keypoints17개의 [x, y, confidence]입니다. 각 값은 0~1이며 confidence는 관절별 신뢰도입니다.
인덱스관절 이름부위
0nose코
1 / 2left_eye / right_eye왼쪽 / 오른쪽 눈
3 / 4left_ear / right_ear왼쪽 / 오른쪽 귀
5 / 6left_shoulder / right_shoulder왼쪽 / 오른쪽 어깨
7 / 8left_elbow / right_elbow왼쪽 / 오른쪽 팔꿈치
9 / 10left_wrist / right_wrist왼쪽 / 오른쪽 손목
11 / 12left_hip / right_hip왼쪽 / 오른쪽 골반
13 / 14left_knee / right_knee왼쪽 / 오른쪽 무릎
15 / 16left_ankle / right_ankle왼쪽 / 오른쪽 발목

left/right는 화면의 좌우가 아니라 사람의 신체 기준입니다. 이 응답은 2D 좌표이며 높이·거리·실제 속도 단위를 제공하지 않습니다. 여러 사람이 있으면 서비스에서 인물을 연결하는 기준이 필요하며, people[0]을 특정 회원으로 고정하면 안 됩니다.

3. 좌표 표시와 갱신

원점은 영상 왼쪽 위이며 x는 오른쪽, y는 아래로 증가합니다. 영상이 표시되는 실제 영역의 크기를 W × H라고 하면 pixel_x = x × W, pixel_y = y × H입니다. 여백이 있는 플레이어에서는 영상 영역의 위치도 더하세요. 확대·잘라내기·좌우 반전을 적용했다면 자세에도 동일한 화면 변환을 적용합니다.

최신 자세 창과 실시간 영상은 시간차가 있을 수 있습니다. received_at_unix로 영상을 seek하거나 손목 속도를 계산하지 마세요. 영상 위에 정확히 겹쳐 그릴 때는 아래의 프레임 정렬 경로를 사용합니다.

4. 실시간 pose 관측 수신

kind=pose.keypoints.2d, include_observations=true로 요청합니다. 기본값은 관절 관측치를 제외하므로 이 옵션을 생략하면 pose 좌표를 얻을 수 없습니다. 아래 예제는 최근 관측을 읽은 뒤 이어서 이벤트를 받는 Backend 흐름입니다. handle_pose_packet/handlePosePacket은 서비스에서 구현하는 결과 처리 함수입니다.

snapshot = tenstos.inference.snapshot(
    "example-node", kinds=["pose.keypoints.2d"],
    camera_ids=["CamA"], include_observations=True, window_sec=10,
)
for packet in snapshot["packets"]:
    handle_pose_packet(packet)

for event in tenstos.inference.events(
    "example-node", cursor=snapshot["cursor"],
    kinds=["pose.keypoints.2d"], camera_ids=["CamA"],
    include_observations=True, max_hz=30,
):
    if event["event"] in ("inference.reset", "inference.gap"):
        break  # snapshot을 다시 읽어 복구하고 누락 구간을 기록합니다.
    if event["event"] == "inference.packet":
        handle_pose_packet(event["data"])

이 응답은 /poses의 items/people 형식과 다릅니다. inference.capabilities의 sample_layouts와 스트림의 좌표계를 확인하세요. 2D pose의 s 샘플은 [frame_number, subject_id, keypoints], 각 관절은 [name, x, y, confidence]입니다. subject_id를 로그인 회원과 자동으로 연결하지 마세요. 좌표계가 다른 결과에 최신 자세 창의 정규화 좌표 변환을 그대로 적용하면 안 됩니다.

max_hz(0.5~60, 기본 30)는 전송 빈도의 상한이며 영상 FPS나 모든 프레임의 전달을 보장하지 않습니다. 이벤트 하나에 여러 프레임이 포함될 수 있습니다. 연결 종료 시 마지막 처리 이벤트의 id를 cursor로 넘겨 재연결하고, reset/gap 이후 복원되지 않은 구간은 저장 결과로 확인합니다. 완전한 기록이 필요한 분석은 실시간 수신만으로 완료했다고 판단하지 마세요.

5. 저장된 자세와 영상 정렬

aligned-segments는 recordings:read와 노드 접근 권한이 필요합니다. 영상과 2D 자세 결과를 함께 선택하려면 artifact_kind=video, artifact_kind=player를 요청하세요. 다음 예제의 start_unix/end_unix는 조회할 구간의 UTC Unix 시각(초)입니다.

aligned = tenstos.inference.aligned_segments(
    "example-node", start_unix=start_unix, end_unix=end_unix,
    cameras=["CamA"], artifact_kinds=["video", "player"],
    include_signed_urls=True,
)
  1. segments[].artifacts에서 같은 session_id·segment_index·camera_id의 영상과 자세 결과를 선택합니다. player는 결과 종류를 지정하는 공개 필터 값입니다.
  2. 결과의 signed_url로 필요한 파일을 읽습니다. URL은 영구 저장하지 말고 만료되면 재발급하세요. has_more가 참이면 next_cursor를 다음 요청의 cursor로 전달합니다.
  3. 자세 샘플의 frame_times[i]를 해당 영상 구간의 재생 시작 위치에 더합니다. 프레임 번호를 무조건 30 또는 60으로 나누거나 API 수신 시각으로 대체하지 마세요.
  4. 자세 파일이나 샘플이 없는 구간은 누락으로 처리합니다. 영상은 계속 재생하고, 동작 속도 계산에서는 누락 구간을 건너뛴 좌표 차이를 정상적인 한 프레임 이동으로 계산하지 않습니다.

구간별 결과 파일의 필드와 좌표계를 확인한 뒤 읽으세요. 저장 결과는 /poses의 응답 JSON과 동일한 형식이라고 가정하지 않습니다. 영상의 view offset과 seek 처리는 세그먼트 재생·seek를 참고하세요. 별도 /v1/inference-results로 결과 목록을 조회하는 경우에는 inference:read가 필요합니다.

6. 오류와 자주 만나는 상황

응답 / 상황사용자 서비스의 처리
200, 빈 결과 또는 waiting자세 수신 대기로 표시합니다. 사람의 부재·관측 불가·결과 지연을 이 상태만으로 구분하지 않습니다.
401Backend의 API Key 설정과 유효성을 확인합니다.
403사용한 endpoint의 Scope와 해당 노드 접근 권한을 확인합니다.
404노드 식별자와 사용 가능한 API 경로를 확인합니다.
400/poses의 카메라 식별자 형식 또는 카메라 선택 수(최대 16개)를 확인합니다.
422필수 파라미터, 자료형, max_age_sec 등의 허용 범위를 확인합니다.
연결 실패·시간 초과·5xx이전 자세를 지우거나 지연 상태로 표시하고 간격을 늘려 재시도합니다. 인증·입력 오류를 그대로 반복 요청하지 않습니다.
스윙 피크 누락 또는 영상과 어긋남최신 자세 조회를 전체 프레임 분석에 사용했는지, 실제 샘플 간격·누락·세션 전환·영상 표시 영역·재생 offset을 확인합니다.
25

OPERATIONS

오류와 재시도

from tenstos_external_api_client import TenstosApiError
from tenstos_external_api_client.resources import TenstosWorkflowError

try:
    group = tenstos.coaching.start_practice(...)
except TenstosWorkflowError as exc:
    # 생성 후 시작만 실패했을 수 있으므로 partial_result를 보존합니다.
    group = exc.partial_result
    save_for_recovery(group)
except TenstosApiError as exc:
    if exc.code in {"active_capture_capacity_exceeded", "application_capture_capacity_exceeded"}:
        show_capacity(exc.capacity, exc.retry_after_sec)
    elif exc.retryable:
        schedule_retry()
    else:
        show_request_error(exc.status_code, exc.detail)
분류대표 상황권장 처리
4xx인증, 권한, 잘못된 입력자동 반복보다 입력·권한 확인
408 / 425 / 429시간 초과, 처리 중, 요청 제한간격을 늘려 제한적으로 재시도
409 + capacity code애플리케이션 또는 전체 캡처 용량 부족capacity와 retry_after_sec를 표시하고 재조회
502 / 503 / 504일시적인 API 연결 문제지수 Backoff와 멱등성 ID 사용
partial일부 카메라만 준비됨카메라별 상태 표시 후 운영 판단
26

PRODUCTION

API 연동 체크리스트

  1. 01
    Secret 분리

    API Key를 코드와 Browser bundle에서 제거하고 운영 Secret으로 주입합니다.

  2. 02
    최소 권한

    필요한 Scope와 Recorder Node만 허용된 Key를 발급받습니다.

  3. 03
    식별자 저장

    client_reference_id, group_id, media_archive_id를 애플리케이션 DB에 연결합니다.

  4. 04
    상태 UI

    preparing, streaming, draining, ready, partial, failed 상태를 사용자에게 설명합니다.

  5. 05
    Timeout과 재시도

    무한 Polling을 피하고 멱등성 ID와 제한된 Backoff 정책을 적용합니다.

  6. 06
    회원 격리

    보관 목록과 재생 요청의 subject를 로그인 Session에서만 결정합니다.

  7. 07
    실패 복구

    Workflow 오류의 partial_result를 보존하여 중복 캡처 생성을 방지합니다.

  8. 08
    다중 Node

    Node 목록을 동적으로 표시하고 Capture Group마다 선택한 node_id와 용량 조회 결과를 저장합니다.

27

REFERENCE

Python SDK 주요 메서드

Resource를 선택한 뒤 메서드를 펼치면 Signature, 인자, 반환값과 오류 조건을 확인할 수 있습니다.

세부 HTTP Endpoint와 요청·응답 Schema는 HTTP API Reference (Advanced)에서 확인할 수 있습니다.

코드를 복사했습니다.