Python SDK
새 Backend 개발의 기본 방식입니다. URL, HTTP Method, 인증 Header와 Polling 규칙을 SDK가 처리합니다.
- FastAPI, Django, Flask에 적합
- 기능 단위 resource interface
- 구조화된 오류와 Workflow helper
TENSTOS EXTERNAL API
다중 카메라 연습 영상을 실시간에 가깝게 확인하고, 캡처 종료 후 다시 탐색하며, 선택한 기록을 회원별 라이브러리에 보관하는 방법을 설명합니다.
처음 사용하는 개발자는 개념을 확인한 뒤 설치와 첫 조회 테스트를 진행하세요. 이후 녹화·다시보기, 웹 화면 연동, 회원별 보관, 고급 재생·분석 순서로 기능을 확장할 수 있습니다.
Tenstos API Key는 개발자 Backend에만 저장합니다. 브라우저 코드, HTML, 모바일 앱 번들에 장기 API Key를 포함하지 마세요.
OVERVIEW
서비스 Backend에서 SDK로 API를 호출하고, 반환된 상태와 재생 URL을 화면에 전달합니다. 브라우저는 재생 URL을 HLS 플레이어에 연결합니다.
start()와 stop()으로 사용할 캡처 구간을 지정합니다. 상태 응답에 재생 URL이 제공되면 영상을 표시하고, 완료 후 필요한 기록을 보관할 수 있습니다.
애플리케이션에는 group_id 또는 media_archive_id를 저장하세요. 재생 URL은 만료될 수 있으므로 다시 볼 때 재생 준비 API로 갱신합니다.
CAPTURE
API의 start와 stop은 애플리케이션에서 사용할 캡처 구간의 시작과 종료를 지정합니다. 실제 사용 가능한 영상 범위는 상태·재생 응답에서 확인합니다.
node_id실제 Recorder 장비 식별자입니다. 장비가 바뀌면 애플리케이션 설정도 새 ID로 갱신합니다.
camera_idRecorder가 제공하는 카메라 ID입니다. 예: CamA, CamB.
group_id동시에 시작·종료되는 다중 카메라 캡처 한 건의 ID입니다.
application_idAPI Key에 연결된 애플리케이션 경계입니다. 자동 발급 시 Key 또는 소유 사용자 기준으로 생성되며, 같은 ID를 명시한 Key만 Capture Group과 멱등성 상태를 공유합니다.
client_reference_id애플리케이션이 생성한 요청 ID입니다. 멱등성과 애플리케이션 DB 연결에 사용합니다.
subject_id애플리케이션의 로그인 사용자를 나타내는 불투명한 ID입니다.
media_archive_id장기 보관을 선택한 영상 묶음의 영구 식별자입니다.
INTEGRATION
새 Backend 개발의 기본 방식입니다. URL, HTTP Method, 인증 Header와 Polling 규칙을 SDK가 처리합니다.
Node.js Backend를 위한 동등한 비동기 SDK입니다. 기존 JavaScript 코드와 새 Node.js 연동에서 사용할 수 있습니다.
화면과 HLS Player에는 계속 필요합니다. 단, 브라우저는 Tenstos API가 아니라 개발자 Backend의 안전한 route를 호출합니다.
Node.js Backend에서 사용하는 비동기 SDK입니다. URL, HTTP Method, 인증 Header와 Polling 규칙을 SDK가 처리합니다.
신규 Backend 개발의 우선 권장 SDK입니다. FastAPI, Django, Flask 기반 애플리케이션에서 사용할 수 있습니다.
Server-side JavaScript SDK와 구분됩니다. Browser helper에는 API Key가 없으며 개발자 Backend의 안전한 route만 호출합니다.
SECURITY
| 기능 | 필요한 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별로 최소 권한을 사용하는 것이 원칙입니다.
DOWNLOAD
전체 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.gz | Python Backend SDK. 가상환경에서 pip로 설치합니다. |
packages/tenstos-external-api-0.3.1.tgzpackages/tenstos-external-api-server-0.3.1.tgz | Node.js core SDK와 Backend wrapper. 두 패키지를 같은 Backend 프로젝트에 설치합니다. |
packages/tenstos-external-api-browser-0.3.1.tgz | Frontend용 helper. 화면 프로젝트에 설치합니다. |
examples/README.mdexamples/*.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를 업데이트할 때 사용합니다. 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"
# Node.js backend
npm install https://api.tenstos.com/docs-assets/downloads/tenstos-external-api-0.3.1.tgz https://api.tenstos.com/docs-assets/downloads/tenstos-external-api-server-0.3.1.tgz
# Browser frontend
npm install https://api.tenstos.com/docs-assets/downloads/tenstos-external-api-browser-0.3.1.tgz
0.3.1은 0.3.0의 세그먼트 재생 지원에 Ball Activity 조회, JavaScript 요청 취소, Retry-After 전달과 재시도·짧은 리플레이 예제를 보충합니다. 기존 wait_for_playback / waitForPlayback은 ready 대기를 유지합니다. 즉시 재생에는 새 wait_until_playable / waitUntilPlayable을 사용하세요.
QUICKSTART
선택한 Python 또는 JavaScript SDK로 새 프로젝트를 준비합니다. 아래 명령은 공개 배포 URL에서 SDK를 직접 설치하므로 소스 저장소나 압축 파일을 미리 받을 필요가 없습니다.
nodes:read가 필요합니다. Pose·녹화·보관 기능의 권한은 Scope 표를 참고하세요.Python 3.10+·pip·venv, JavaScript 경로는 Node.js 22+·npm을 준비합니다. SDK 설치와 선택적 Backend 의존성 설치에는 인터넷 연결이 필요합니다.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 연동 단계에서 추가합니다.
node --version
npm --version
mkdir tenstos-node-demo
cd tenstos-node-demo
npm init -y
npm install https://api.tenstos.com/docs-assets/downloads/tenstos-external-api-0.3.1.tgz
npm ls @tenstos/external-api
설치 목록에 @tenstos/external-api@0.3.1이 표시됩니다. 아래 예제는 .mjs 파일이므로 package.json의 module 설정을 바꾸지 않아도 실행됩니다. Server wrapper와 Browser helper는 필요한 단계에서 별도로 설치합니다.
프로젝트 폴더에 .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
설치 버전이 확인되고 환경변수를 적용했다면, 다음 간단 예제 테스트에서 노드 목록을 조회합니다.
FIRST REQUEST
앞 단계에서 만든 프로젝트 폴더와 환경변수를 그대로 사용합니다. 이 예제는 접근 가능한 노드를 조회하며 녹화·보관 작업을 시작하지 않습니다.
프로젝트 폴더에 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
프로젝트 폴더에 smoke.mjs로 저장합니다.
import { TenstosClient } from "@tenstos/external-api";
const apiKey = process.env.TENSTOS_API_KEY;
if (!apiKey || apiKey === "replace-with-developer-key") {
console.error(".env에 실제 API Key를 입력하고 환경변수를 적용하세요.");
process.exit(1);
}
const tenstos = new TenstosClient({
apiKey,
baseUrl: process.env.TENSTOS_API_BASE || "https://api.tenstos.com",
fetchImpl: (url, options) => fetch(url, {
...options, signal: AbortSignal.timeout(10000),
}),
});
try {
const nodes = await tenstos.recorderNodes.list();
const items = nodes.items || [];
console.log(`연결 성공: 접근 가능한 노드 ${items.length}개`);
for (const node of items) {
console.log(node.node_id, node.status);
for (const camera of node.cameras || []) {
console.log(" camera:", camera.camera_id);
}
}
} catch (error) {
console.error(`조회 실패: HTTP ${error.statusCode || "network"}`);
process.exitCode = 1;
}
node smoke.mjs
연결 성공: 접근 가능한 노드 N개와 노드·카메라 ID가 출력되면 SDK 설치·환경변수·인증·목록 조회가 완료된 것입니다. 0개라도 조회는 성공한 상태이며, 사용할 노드의 등록·접근 권한은 관리자에게 확인하세요. 목록에 노드가 있다고 영상이나 Pose 결과가 현재 제공된다는 뜻은 아닙니다.
사용할 node_id를 .env의 TENSTOS_NODE_ID에 넣고 환경변수를 다시 적용합니다. CamA 등 문서의 카메라 ID도 실제 조회 결과로 바꾸세요.
기본 흐름은 노드 선택 → 용량 확인 → 녹화 시작 → 종료 → 다시보기입니다. 녹화 시작부터 실제 캡처 구간이 생성됩니다.
기본 흐름을 확인한 뒤 웹 화면 연동, 회원별 영상 보관, 세밀한 재생 제어로 확장하세요. 자세 좌표만 필요한 경우에는 inference:read 권한을 준비하고 Pose API 사용법으로 이동할 수 있습니다.
이후 기능별 코드는 기존 서비스에 붙이는 발췌 예제입니다. 위와 같이 생성한 tenstos 클라이언트를 사용하며 node_id/nodeId, 선택한 카메라 목록, 이전 응답의 group_id/groupId 등은 해당 흐름에서 준비해야 합니다. ...나 처리 함수 이름이 있는 예제는 완성된 실행 파일이 아닙니다.
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 / 403 | 401은 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의 포트를 함께 바꿉니다. |
CAPTURE
캡처 전에 접근 가능한 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")
const nodes = await tenstos.recorderNodes.list();
for (const node of nodes.items || []) {
console.log(node.node_id, node.status);
for (const camera of node.cameras || []) {
console.log(" -", camera.camera_id);
}
}
const health = await tenstos.recorderNodes.health("recorder-node-001");
CAPTURE
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("선택한 카메라 수가 현재 가용 슬롯보다 큽니다.")
const capacity = await tenstos.captureGroups.capacity("recorder-node-001");
const available = capacity.application.available;
if (selectedCameraIds.length > available) {
throw new Error("선택한 카메라 수가 현재 가용 슬롯보다 큽니다.");
}
| 필드 | 의미 |
|---|---|
application | 현재 API Key의 running, reserved, used, available, max_slots, active_groups |
node | 선택한 NODE_ID에서 실행 중인 Group·카메라 슬롯·애플리케이션 수 |
global | 전체 캡처 용량과 사용량 |
policy | 애플리케이션별 슬롯 및 Node별 동시 Group 제한 |
CAPTURE
coaching.start_practice()coaching.startPractice()는 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"]
const practice = await tenstos.coaching.startPractice({
nodeId: "recorder-node-001",
cameraIds: ["CamA", "CamB", "CamC", "CamD"],
clientReferenceId: "practice-20260831-0001",
title: "포핸드 자세 교정",
durationSec: 600,
metadata: { lesson_id: "lesson-1042" },
waitUntilStreaming: false,
});
const groupId = practice.group_id;
네트워크 오류로 시작 요청을 다시 보내도 같은 client_reference_id를 사용하세요. Coaching helper는 이를 기반으로 생성 요청의 멱등성 Key를 구성합니다. 동일한 문자열을 다른 API Key가 사용해도 애플리케이션별 namespace가 분리됩니다.
CAPTURE
웹 요청을 오랫동안 열어 두기보다 짧은 Polling으로 Capture Group을 조회하고 UI에 현재 단계를 보여주세요.
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"),
)
const group = await tenstos.captureGroups.get(groupId);
const status = group.status;
for (const camera of group.cameras || []) {
const delivery = camera.delivery || {};
console.log(
camera.camera_id,
delivery.status,
delivery.playlist_url,
);
}
| 상태 | 화면에 권장하는 설명 | UI 동작 |
|---|---|---|
created / starting | 연습 기록을 시작하고 있습니다. | 시작 버튼 잠금 |
preparing | 카메라 영상을 준비하고 있습니다. | 카메라별 준비 상태 표시 |
streaming | 실시간에 가까운 영상이 들어오고 있습니다. | 준비된 화면부터 재생 |
draining | 마지막 영상을 정리하고 있습니다. | 기존 영상 재생 유지 |
ready | 전체 연습 영상이 준비되었습니다. | 전체 Seek 활성화 |
partial / failed | 일부 또는 전체 영상을 준비하지 못했습니다. | 재시도·운영 문의 안내 |
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,
)
const stopped = await tenstos.coaching.stopPractice(groupId, {
note: "연습 종료",
waitUntilReady: false,
});
// Worker, CLI 또는 테스트에서만 blocking helper 사용을 권장합니다.
const ready = await tenstos.captureGroups.waitUntilReady(groupId, {
timeoutMs: 180_000,
});
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"])
let playback = await tenstos.captureGroups.preparePlayback(groupId, {
ttlSeconds: 3600,
});
while (playback.status === "preparing") {
await new Promise((resolve) => setTimeout(resolve, 1000));
playback = await tenstos.captureGroups.preparePlayback(groupId, {
ttlSeconds: 3600,
});
}
for (const camera of playback.cameras || []) {
console.log(camera.camera_id, camera.playlist_url);
}
| 수명 | 관리 위치 | 만료 후 처리 |
|---|---|---|
| 연습 목록 | 개발자 애플리케이션 DB | 서비스 정책에 따라 며칠간 group_id 유지 |
| 임시 Playback | 유효 기간이 있는 재생 URL | prepare_playback() 재호출 |
| 장기 보관 | Media Archive | 별도 보관본에서 Playback 준비 |
multi-camera-coaching-review-session-python은 미보관 연습 메타데이터를 7일간 유지하고, 임시 Playback URL은 1시간으로 준비합니다. HLS network error가 발생하면 선택한 Group의 Playback을 자동으로 다시 확인합니다.
SECURITY
subject_idsubjectId 결정subject_idsubjectId는 Backend의 인증 Session에서 결정합니다.BACKEND
첫 API 조회를 마친 프로젝트에서 이어서 실행합니다. Python 또는 Node.js 중 하나를 선택하세요. 아래는 로그인 기능을 연결하기 전의 로컬 개발 예제로 127.0.0.1:8080에서만 실행합니다. 외부 공개 전에는 전체 /api/tenstos 경로에 서비스의 인증·접근 제어를 연결하세요.
활성화한 가상환경에서 실행합니다. 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", ""),
))
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를 사용합니다.
같은 프로젝트에 core SDK와 server wrapper를 함께 설치합니다. 아래 다운로드 URL을 사용하면 npm 공개 레지스트리에서 Tenstos 패키지를 찾을 필요가 없습니다.
npm install https://api.tenstos.com/docs-assets/downloads/tenstos-external-api-0.3.1.tgz https://api.tenstos.com/docs-assets/downloads/tenstos-external-api-server-0.3.1.tgz
프로젝트 폴더에 server.mjs로 저장합니다.
import { createServer } from "node:http";
import { createTenstosApiHandler } from "@tenstos/external-api-server";
if (!process.env.TENSTOS_API_KEY) {
throw new Error("TENSTOS_API_KEY 환경변수를 적용하세요.");
}
const tenstosApi = createTenstosApiHandler({
apiBasePath: "/api/tenstos",
serviceName: "tenstos-local-demo",
apiKey: process.env.TENSTOS_API_KEY,
baseUrl: process.env.TENSTOS_API_BASE || "https://api.tenstos.com",
defaultNodeId: process.env.TENSTOS_NODE_ID || "",
});
createServer((request, response) => {
void tenstosApi(request, response);
}).listen(8080, "127.0.0.1", () => {
console.log("Backend: http://127.0.0.1:8080/api/tenstos/health");
});
node server.mjs
이 터미널은 열어 둡니다. 종료는 Ctrl+C입니다. 기존 HTTP 서버에 통합할 때는 /api/tenstos 요청만 이 handler로 보내고 나머지는 기존 route에서 처리합니다.
다른 터미널에서 다음 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가 필요합니다.
화면 개발 시 사용하는 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 플레이어를 포함하지 않습니다.
위 로컬 예제는 회원 보관 경로를 활성화하지 않으므로 /media-archives 요청은 404입니다. 실제 서비스에서는 로그인 세션에서 회원 식별자를 반환하는 Python subject_resolver(request) 또는 JavaScript subjectResolver(request)를 구현하고 router/handler 생성 옵션에 전달하세요. 브라우저가 보낸 임의의 회원 ID를 그대로 사용하지 않습니다. 세션 인증 자체는 SDK가 제공하지 않으며, 보관 기능에는 해당 archives Scope도 필요합니다.
PLAYBACK
같은 Capture Group의 카메라는 공통 source segment index 경계를 기준으로 구성됩니다. Backend는 API가 반환한 카메라별 playlist를 그대로 전달하고, Browser Player는 같은 Group의 재생 위치와 재생 속도를 함께 제어합니다.
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"]
const archive = await tenstos.coaching.retainPractice({
subjectId: "member_8f2a1c",
captureGroupId: groupId,
clientReferenceId: "practice-20260831-0001",
title: "포핸드 자세 교정",
metadata: { lesson_id: "lesson-1042" },
waitUntilReady: false,
});
const mediaArchiveId = archive.media_archive_id;
애플리케이션 DB에는 group_id, media_archive_id, 제목, 사용자 ID, 생성 시각 등 필요한 참조 정보를 저장합니다.
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"))
const library = await tenstos.archives.list({
subjectId: "member_8f2a1c",
collectionId: "coaching-practices",
limit: 100,
});
for (const item of library.items || []) {
console.log(item.media_archive_id, item.status, item.title);
}
Backend는 로그인한 사용자의 subject_idsubjectId만 사용해야 합니다. Browser 요청에서 임의의 사용자 ID를 받아 그대로 SDK에 넘기지 마세요.
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"])
const playback = await tenstos.archives.waitUntilPlayable(
mediaArchiveId,
{
cameraIds: ["CamA", "CamB", "CamC", "CamD"],
ttlSeconds: 3600,
},
);
for (const camera of playback.cameras || []) {
console.log(camera.camera_id, camera.playlist_url);
}
SEGMENT PLAYBACK
API의 playlist_url을 HLS 플레이어에 연결하고 현재 위치 주변만 버퍼링합니다. 전체 TS 다운로드나 Blob 병합, 추론 결과 전체 로딩을 재생 시작 조건으로 두지 않습니다. playlist 메타데이터 전체 조회와 영상 전체 다운로드는 다릅니다.
| 대상 | 재생 준비 | 아직 playlist에 없는 위치로 seek |
|---|---|---|
| 일반 녹화 | POST /v1/recording-nodes/{node_id}/recording-vod-jobs | POST /v1/recording-vod-jobs/{job_id}/playback-views |
| 보관 영상 | POST /v1/media-archives/{media_archive_id}/playback | POST /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에 연결합니다.
const playback = await tenstos.archives.waitUntilPlayable(mediaArchiveId, {
cameraIds: ["CamA"], timeoutMs: 180000,
});
// Backend는 descriptor를 Browser로 전달합니다.
// Browser는 cameras[0].playlist_url을 HLS player에 연결합니다.
현재 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,
)
const view = await tenstos.archives.preparePlaybackViews(mediaArchiveId, {
cameraIds: ["CamA"], positionSec: 125.4,
viewKey: "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 이벤트를 무시하고, 카메라마다 반환된 보정값을 적용하세요.
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가 필요합니다.
| 기능 | Python / Node.js SDK | Browser helper + Backend wrapper |
|---|---|---|
| 일반 녹화 재생·seek | recording_node_vod_job / recordingNodeVodJob, recording_vod_job / recordingVodJob, recording_vod_view / recordingVodView, recording_vod_view_status / recordingVodViewStatus | Browser의 camelCase 메서드. 양쪽 wrapper 모두 /recording-nodes/{node_id}/vod-jobs, /recording-vod-jobs/{job_id}, view POST/GET 지원 |
| 세그먼트 + 추론 조회 | inference.aligned_segments / inference.alignedSegments | recordingNodeAlignedSegments → /recording-nodes/{node_id}/aligned-segments |
| 보관 영상 seek | archives.prepare_playback_views / archives.preparePlaybackViews | archives.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 응답 역전, 타임라인·추론 정렬을 검수하세요.
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
const requestedStart = eventUnix - 2.2;
const view = await tenstos.archives.preparePlaybackViews(mediaArchiveId, {
cameraIds: ["CamA"], timestampUnix: requestedStart, windowSec: 4.4,
viewKey: "review-main", generation: 3,
});
// 이벤트의 view 내 위치(연속된 짧은 구간):
// camera.position_in_view_sec + eventUnix - requestedStart
재생 목록은 세그먼트 경계에서 시작하므로 요청 시각보다 앞선 프레임을 포함할 수 있습니다. 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 공통 필드로 가정하지 않습니다.
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를 대신하지 않습니다.
REALTIME
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", []))
const snapshot = await tenstos.inference.snapshot({
nodeId,
kinds: ["object.track.3d"],
includeObservations: false,
});
for await (const event of tenstos.inference.events({
nodeId,
kinds: ["object.track.3d"],
includeObservations: false,
})) {
if (event.event === "inference.packet") {
handleSemanticEvents(event.data.e || []);
}
}
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,
)
const aligned = await tenstos.inference.alignedSegments({
nodeId,
startUnix,
endUnix,
cameras: ["CamA", "shared"],
artifactKinds: ["video", "ball", "fusion"],
includeSignedUrls: true,
});
궤적을 매 frame 표시할 때만 include_observations를 켜고 max_hz를 제한하세요. Replay에서는 aligned descriptor의 signed URL 중 필요한 결과 파일만 읽습니다. 반환된 URL로 필요한 파일을 읽으세요.
POSE
사람의 2D 관절 좌표를 조회해 자세 표시, 동작 구간 탐색, 영상 비교에 사용할 수 있습니다. API Key는 서비스 Backend에만 두고, 브라우저에는 서비스에서 허용한 결과만 전달하세요. 아래 SDK 예제는 첫 API 호출에서 만든 Backend용 tenstos 클라이언트를 사용합니다.
| 목적 | API | 선택 기준 |
|---|---|---|
| 최신 자세를 작은 창에 표시 | GET /v1/inference-streams/poses | 카메라별 최신 프레임만 반환합니다. 과거 프레임 목록은 포함하지 않습니다. |
| 실시간 관절 좌표를 연속 수신 | GET /v1/inference-streams/snapshotGET /v1/inference-streams/events | Pose 종류로 필터하고 관측치 포함을 켭니다. 재연결과 누락 처리가 필요합니다. |
| 스윙 구간 분석·영상과 프레임 맞추기 | GET /v1/recording-nodes/{node_id}/aligned-segments | 같은 구간의 영상과 저장된 자세 결과를 조회합니다. 자세 결과가 제공되는 구간에 사용할 수 있습니다. |
/poses를 자주 호출해도 모든 프레임을 수집한다는 보장은 없습니다. 손목 속도 피크나 정확한 동작 시점을 찾을 때는 프레임 간격과 누락을 확인할 수 있는 연속 관측 또는 저장 결과를 사용하세요. 조회 요청은 새 분석 작업을 시작하지 않으며, 데이터 제공 여부와 관절 검출 품질은 노드·카메라·구간에 따라 다릅니다.
필요 권한은 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 | 선택 / 3 | API 수신 시각 기준 최신 자세의 유효 시간(초)입니다. 범위는 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)
const query = new URLSearchParams({
node_id: "example-node", max_age_sec: "3",
});
for (const camera of ["CamA", "CamB"]) query.append("camera", camera);
const poses = await tenstos.request(`/v1/inference-streams/poses?${query}`);
for (const item of poses.items) {
if (item.status !== "ready") continue;
for (const person of item.people) {
const joints = Object.fromEntries(
poses.keypoint_names.map((name, i) => [name, person.keypoints[i]])
);
const [x, y, confidence] = joints.left_wrist;
if (confidence >= 0.3) { // 표시용 예시 기준. 서비스에 맞게 조정합니다.
console.log(item.camera_id, item.frame_number, x, y);
}
}
}
다운로드 SDK 0.3.1에는 최신 자세 전용 메서드가 없으므로 위 예제는 공통 request()를 사용합니다. 인증 헤더는 클라이언트가 설정합니다. HTTP Query 이름은 camera이며 여러 값을 반복해서 보냅니다. Browser helper가 모든 inference 호출을 대신 제공하는 것은 아니므로, 서비스 Backend에서 인증·노드 접근을 확인하는 조회 경로를 구성하세요.
아래는 카메라 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_space | stored_video_normalized: 저장 영상 기준 정규화 좌표입니다. |
keypoint_names | 각 keypoints 배열의 이름·순서입니다. 응답의 이름으로 관절을 매핑하세요. |
items | 카메라별 결과입니다. 요청한 카메라라도 자세 결과가 없으면 항목이 생략될 수 있습니다. |
camera_id / stream_id / session_id | 관측을 구분하는 식별자입니다. 세션·스트림이 바뀌면 이전 자세와 궤적을 초기화하세요. |
status | ready: 표시 가능한 자세 있음. waiting: 현재 유효한 자세 없음. |
received_at_unix | API가 결과를 받은 시각입니다. 촬영 시각이나 영상 재생 위치가 아닙니다. |
frame_number | 결과의 프레임 번호입니다. 대기 상태에서는 null입니다. 단독으로 영상의 재생 초를 의미하지 않습니다. |
people | 해당 프레임의 최대 4명입니다. 배열 순서는 고정된 사람 ID나 회원 ID가 아닙니다. |
people[].keypoints | 17개의 [x, y, confidence]입니다. 각 값은 0~1이며 confidence는 관절별 신뢰도입니다. |
| 인덱스 | 관절 이름 | 부위 |
|---|---|---|
| 0 | nose | 코 |
| 1 / 2 | left_eye / right_eye | 왼쪽 / 오른쪽 눈 |
| 3 / 4 | left_ear / right_ear | 왼쪽 / 오른쪽 귀 |
| 5 / 6 | left_shoulder / right_shoulder | 왼쪽 / 오른쪽 어깨 |
| 7 / 8 | left_elbow / right_elbow | 왼쪽 / 오른쪽 팔꿈치 |
| 9 / 10 | left_wrist / right_wrist | 왼쪽 / 오른쪽 손목 |
| 11 / 12 | left_hip / right_hip | 왼쪽 / 오른쪽 골반 |
| 13 / 14 | left_knee / right_knee | 왼쪽 / 오른쪽 무릎 |
| 15 / 16 | left_ankle / right_ankle | 왼쪽 / 오른쪽 발목 |
left/right는 화면의 좌우가 아니라 사람의 신체 기준입니다. 이 응답은 2D 좌표이며 높이·거리·실제 속도 단위를 제공하지 않습니다. 여러 사람이 있으면 서비스에서 인물을 연결하는 기준이 필요하며, people[0]을 특정 회원으로 고정하면 안 됩니다.
원점은 영상 왼쪽 위이며 x는 오른쪽, y는 아래로 증가합니다. 영상이 표시되는 실제 영역의 크기를 W × H라고 하면 pixel_x = x × W, pixel_y = y × H입니다. 여백이 있는 플레이어에서는 영상 영역의 위치도 더하세요. 확대·잘라내기·좌우 반전을 적용했다면 자세에도 동일한 화면 변환을 적용합니다.
0.3은 예시 표시 기준이며 정확도 보장이 아닙니다.items: [], 카메라 항목 생략, waiting, people: []이면 해당 자세를 지우고 대기 상태를 표시합니다. HTTP 200의 빈 결과도 정상입니다.최신 자세 창과 실시간 영상은 시간차가 있을 수 있습니다. received_at_unix로 영상을 seek하거나 손목 속도를 계산하지 마세요. 영상 위에 정확히 겹쳐 그릴 때는 아래의 프레임 정렬 경로를 사용합니다.
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"])
const snapshot = await tenstos.inference.snapshot({
nodeId: "example-node", kinds: ["pose.keypoints.2d"],
cameraIds: ["CamA"], includeObservations: true, windowSec: 10,
});
for (const packet of snapshot.packets) handlePosePacket(packet);
for await (const event of tenstos.inference.events({
nodeId: "example-node", cursor: snapshot.cursor,
kinds: ["pose.keypoints.2d"], cameraIds: ["CamA"],
includeObservations: true, maxHz: 30,
})) {
if (["inference.reset", "inference.gap"].includes(event.event)) {
break; // snapshot을 다시 읽어 복구하고 누락 구간을 기록합니다.
}
if (event.event === "inference.packet") handlePosePacket(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 이후 복원되지 않은 구간은 저장 결과로 확인합니다. 완전한 기록이 필요한 분석은 실시간 수신만으로 완료했다고 판단하지 마세요.
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,
)
const aligned = await tenstos.inference.alignedSegments({
nodeId: "example-node", startUnix, endUnix,
cameras: ["CamA"], artifactKinds: ["video", "player"],
includeSignedUrls: true,
});
segments[].artifacts에서 같은 session_id·segment_index·camera_id의 영상과 자세 결과를 선택합니다. player는 결과 종류를 지정하는 공개 필터 값입니다.signed_url로 필요한 파일을 읽습니다. URL은 영구 저장하지 말고 만료되면 재발급하세요. has_more가 참이면 next_cursor를 다음 요청의 cursor로 전달합니다.frame_times[i]를 해당 영상 구간의 재생 시작 위치에 더합니다. 프레임 번호를 무조건 30 또는 60으로 나누거나 API 수신 시각으로 대체하지 마세요.구간별 결과 파일의 필드와 좌표계를 확인한 뒤 읽으세요. 저장 결과는 /poses의 응답 JSON과 동일한 형식이라고 가정하지 않습니다. 영상의 view offset과 seek 처리는 세그먼트 재생·seek를 참고하세요. 별도 /v1/inference-results로 결과 목록을 조회하는 경우에는 inference:read가 필요합니다.
| 응답 / 상황 | 사용자 서비스의 처리 |
|---|---|
200, 빈 결과 또는 waiting | 자세 수신 대기로 표시합니다. 사람의 부재·관측 불가·결과 지연을 이 상태만으로 구분하지 않습니다. |
| 401 | Backend의 API Key 설정과 유효성을 확인합니다. |
| 403 | 사용한 endpoint의 Scope와 해당 노드 접근 권한을 확인합니다. |
| 404 | 노드 식별자와 사용 가능한 API 경로를 확인합니다. |
| 400 | /poses의 카메라 식별자 형식 또는 카메라 선택 수(최대 16개)를 확인합니다. |
| 422 | 필수 파라미터, 자료형, max_age_sec 등의 허용 범위를 확인합니다. |
| 연결 실패·시간 초과·5xx | 이전 자세를 지우거나 지연 상태로 표시하고 간격을 늘려 재시도합니다. 인증·입력 오류를 그대로 반복 요청하지 않습니다. |
| 스윙 피크 누락 또는 영상과 어긋남 | 최신 자세 조회를 전체 프레임 분석에 사용했는지, 실제 샘플 간격·누락·세션 전환·영상 표시 영역·재생 offset을 확인합니다. |
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)
import {
TenstosApiError,
TenstosWorkflowError,
} from "@tenstos/external-api";
try {
const group = await tenstos.coaching.startPractice({ /* ... */ });
} catch (error) {
if (error instanceof TenstosWorkflowError) {
// 생성 후 시작만 실패했을 수 있으므로 partialResult를 보존합니다.
saveForRecovery(error.partialResult);
} else if (error instanceof TenstosApiError && error.retryable) {
if (["active_capture_capacity_exceeded", "application_capture_capacity_exceeded"].includes(error.code)) {
showCapacity(error.capacity, error.retryAfterSec);
} else {
scheduleRetry();
}
} else {
showRequestError(error.statusCode, error.detail);
}
}
| 분류 | 대표 상황 | 권장 처리 |
|---|---|---|
| 4xx | 인증, 권한, 잘못된 입력 | 자동 반복보다 입력·권한 확인 |
| 408 / 425 / 429 | 시간 초과, 처리 중, 요청 제한 | 간격을 늘려 제한적으로 재시도 |
| 409 + capacity code | 애플리케이션 또는 전체 캡처 용량 부족 | capacity와 retry_after_sec를 표시하고 재조회 |
| 502 / 503 / 504 | 일시적인 API 연결 문제 | 지수 Backoff와 멱등성 ID 사용 |
| partial | 일부 카메라만 준비됨 | 카메라별 상태 표시 후 운영 판단 |
PRODUCTION
API Key를 코드와 Browser bundle에서 제거하고 운영 Secret으로 주입합니다.
필요한 Scope와 Recorder Node만 허용된 Key를 발급받습니다.
client_reference_idclientReferenceId, group_id, media_archive_id를 애플리케이션 DB에 연결합니다.
preparing, streaming, draining, ready, partial, failed 상태를 사용자에게 설명합니다.
무한 Polling을 피하고 멱등성 ID와 제한된 Backoff 정책을 적용합니다.
보관 목록과 재생 요청의 subject를 로그인 Session에서만 결정합니다.
Workflow 오류의 partial_resultpartialResult를 보존하여 중복 캡처 생성을 방지합니다.
Node 목록을 동적으로 표시하고 Capture Group마다 선택한 node_id와 용량 조회 결과를 저장합니다.
REFERENCE
Resource를 선택한 뒤 메서드를 펼치면 Signature, 인자, 반환값과 오류 조건을 확인할 수 있습니다.
세부 HTTP Endpoint와 요청·응답 Schema는 HTTP API Reference (Advanced)에서 확인할 수 있습니다.
다른 검색어를 입력하거나 검색어를 지워 전체 문서를 확인하세요.