---
title: "Visual Object Tracking"
slug: "arc-eye-vot-api"
tags: ["ARC eye"]
updated: 2026-09-17T09:16:30Z
published: 2026-09-17T09:16:30Z
canonical: "api.ncloud-docs.com/arc-eye-vot-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Visual Object Tracking

Classic/VPC 환경에서 이용 가능합니다.

오브젝트(객체)에 대한 기본 정보와 포즈 추정 결과를 조회합니다.

## 사전 단계

ARC eye VOT API를 사용하기 위한 사전 단계는 다음과 같습니다.

### 1. 오브젝트(객체) 생성

콘솔에서 오브젝트(객체)를 생성합니다. 자세한 생성 방법은 [ARC eye 사용 가이드](https://guide.ncloud-docs.com/docs/arceye-votapi)를 참조해 주십시오.

### 2. API 배포

오브젝트(객체)를 생성하면 네이버 클라우드 플랫폼 콘솔의 **Menu** > **All Services** > **Digital Twin** > **ARC eye** > **Visual Object Tracking** > **API** 메뉴에 **대기** 상태인 API가 생성됩니다. 해당 API를 선택하여 배포해 주십시오. **완료** 상태로 배포가 완료되면 ARC eye VOT API를 사용할 수 있습니다. 자세한 배포 방법은 [ARC eye 사용 가이드](https://guide.ncloud-docs.com/docs/arceye-votapi)를 참조해 주십시오.

## 요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

| 메서드 | URI |
| --- | --- |
| POST | [InvokeURL](/docs/arc-eye-overview#APIURL) |

### 요청 헤더

ARC eye API에서 공통으로 사용하는 헤더에 대한 정보는 [ARC eye 요청 헤더](/docs/arc-eye-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오.

### 요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `image` | File | Required | 오브젝트 검출을 수행할 RGB 이미지이미지 파일 확장자: jpg, png |
| `uuid` | String | Required | 이미지를 촬영한 디바이스의 고유 식별자 - UUID 형식 |
| `timestamp` | Number | Required | 이미지 생성 시간(밀리초) - Unix Timestamp 형식 |
| `intrinsic` | String | Required | 포즈 추정에 사용된 카메라 intrinsic 파라미터 |
| `distort` | String | Required | 포즈 추정에 사용된 카메라 distortion 파라미터 |
| `gravity` | String | Optional | 포즈 추정에 사용된 중력 방향 - 미입력 시 `extrinsic`으로 계산한 값 사용 |
| `extrinsic` | String | Required | 포즈 추정에 사용된 카메라와 좌표계 간 위치 및 방향(회전 및 이동) |
| `videoid` | String | Optional | VOT 클라이언트에서 인식된 영상 아이디 |
| `imgid` | String | Optional | VOT 클라이언트에서 인식된 이미지 아이디 |
| `keyframeid` | String | Optional | VOT 클라이언트에서 인식된 키프레임 아이디 |

### 요청 예시

요청 예시는 다음과 같습니다.

```
curl --location --request POST '{InvokeURL}' \
--header 'X-ARCEYE-SECRET: {SecretKey}' \
--header 'Content-Type: multipart/form-data' \
--form 'image=@object.jpg \
--form 'uuid=a4315b63-2d64-11ef-becb-005056a70a22' \
--form 'timestamp=1718709558076' \
--form 'intrinsic=1524.3942260742188,0.0,539.0464782714844,0.0,1524.3942260742188,950.2188720703125,0.0,0.0,1.0' \
--form 'distort=0.0,0.0,0.0,0.0,0.0' \
--form 'extrinsic=-0.5501050024473961,-0.03056710354932507,-0.834535882070361,-0.2494854635652485-0.42819610313094764,0.8682865385146257,0.25045275861479593,-0.16543658916848714,0.7169606569023306,,0.495120328016226,-0.4907374830184501,0.189104661569504620.0,0.0,0.0,1.0'
```

## 응답

응답 형식을 설명합니다.

### 응답 바디(성공)

조회가 성공한 경우의 응답 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `result` | String | - | 응답 결과 - `SUCCESS` \| `FAILURE` \| `ERROR` - `SUCCESS`: 성공 - `FAILURE`: 실패 - `ERROR`: 오류 |
| `version` | String | - | ARC eye VOT API 배포 버전 |
| `projectid` | String | - | 포즈 추정을 수행한 프로젝트 아이디 |
| `recvtime` | Number | - | Poser(포즈 추정)가 Detector(오프젝트 검출)의 요청 수신 시점(밀리초) - Unix Timestamp 형식 |
| `timestamp` | Number | - | 요청 시 사용된 이미지의 생성 시간(밀리초) - Unix Timestamp 형식 |
| `uuid` | String | - | 요청 시 사용된 디바이스의 고유 식별자 - UUID 형식 |
| `status` | Number | - | 검출 상태 코드 |
| `message` | String | - | 검출 상태 메시지 |
| `objects` | Array | - | 포즈 추정에 사용된 오브젝트 정보: [objects](/docs/arc-eye-vot-api#objects) |
| `flpose` | Array | - | 대상 오브젝트 이용하여 계산된 사용자 포즈 |

#### `objects`

`objects`에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `bbox2d` | Array(4,2) | - | 포즈 추정을 위해 제공된 Detector의 검출 ROI(Region of Interest) - 이미지상에서 오브젝트의 경계를 나타내는 2D 바운딩 박스 좌표 |
| `conf_thresh` | Number | - | 검출된 오브젝트의 신뢰도 임계값 - 0에 가까울수록 신뢰도가 낮고, 1에 가까울수록 신뢰도가 높음 |
| `corners2d` | Array(9,2) | - | 3D object bounding box에 대응되는 2D 이미지 좌표 |
| `corners3d` | Array(9,3) | - | 3D 공간에서 (0,0)을 중심으로 한 3D object bounding box 좌표 |
| `distort` | Array(5) | - | 포즈 추정에 사용된 카메라 렌즈의 왜곡 정보 |
| `extrinsic` | Array(4,4) | - | 포즈 추정에 사용된 카메라와 좌표계 간의 위치 및 방향(회전 및 이동)을 나타내는 좌표 |
| `global_pose` | Array(4,4) | - | 글로벌 좌표계에서의 오브젝트 위치 및 방향을 나타내는 좌표 |
| `global_prob` | Number | - | 글로벌 포즈 추정의 신뢰도 - 0에 가까울수록 신뢰도가 낮고, 1에 가까울수록 신뢰도가 높음 |
| `intrinsic` | Array(3,3) | - | 포즈 추정에 사용된 카메라의 초점 거리(focal length), 광학 중심(optical center) 등 내부 특성을 나타내는 좌표 |
| `message` | String | - | 오브젝트의 포즈 추정 상태 정보 |
| `obj_prob` | Number | - | 오브젝트 검출의 신뢰도 - 0에 가까울수록 신뢰도가 낮고, 1에 가까울수록 신뢰도가 높음 |
| `objid` | String | - | 포즈 추정에 사용된 오브젝트 아이디 |
| `pose` | Array(4,4) | - | 오브젝트의 위치 및 방향 좌표 |
| `poserid` | String | - | 포즈 추정을 수행한 영상 아이디(`videoid` 또는 `objectid`와 동일) |
| `projectid` | String | - | 오브젝트가 속한 프로젝트 아이디 |
| `sim_prob` | Number | - | 오브젝트와 모델 간의 유사 신뢰도 - 0에 가까울수록 신뢰도가 낮고, 1에 가까울수록 신뢰도가 높음 |
| `size` | Array(3) | - | 오브젝트의 크기 정보 - 차례대로 width, height, depth |
| `status` | boolean | - | 오브젝트의 포즈 추정 상태 - `True` \| `False` - `True`: 포즈 추정 성공 - `False`: 포즈 추정 실패 |
| `type` | String | - | 오브젝트 유형 |

### 응답 바디(실패)

조회가 실패한 경우의 응답 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `result` | String | - | 응답 결과 - `SUCCESS` \| `FAILURE` \| `ERROR` - `SUCCESS`: 성공 - `FAILURE`: 실패 - `ERROR`: 오류 |
| `running_time` | Object | - | 처리 시간 정보 |
| `running_time.processing` | Number | - | 처리 시간(밀리초) |
| `timestamp` | Number | - | 요청 시 사용된 이미지의 생성 시간(밀리초) - Unix Timestamp 형식 |
| `version` | String | - | ARC eye VOT API 배포 버전 |
| `candidate_obj_id` | Number | - | 후보 오브젝트 아이디 - 값이 0인 경우, 후보 오브젝트가 없음을 의미 |

### 응답 상태 코드

ARC eye VOT API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [ARC eye 응답 상태 코드](/docs/arc-eye-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오.

### 응답 예시

응답 예시는 다음과 같습니다.

#### 성공

조회가 성공한 경우의 응답 예시는 다음과 같습니다.

```
{
    "result": "SUCCESS",
    "version": "3.0.0-1",
    "projectid": "123",
    "recvtime": 1712213062.4720848,
    "timestamp": 1712213062.2513185,
    "uuid": "933ec42646f8",
    "status": 0,
    "message": "VOT_DETECTOR_SUCCESS",
    "objects": [
        {
            "bbox2d": [[677.0, 1472.0], [1466.0, 1472.0], [1466.0, 2861.0], [677.0, 2861.0]],
            "conf_thresh": 0.3,
            "corners2d": [[1048, 2119], [746, 2513], [726, 1473], [715, 2864], [686, 1564], [1297, 2500], [1335, 1477], [1408, 2842], [1472, 1568]],
            "corners3d": [[0.0, 0.0, 0.0],
                [-0.29031120781734804, -0.5381274223327637, -0.3174518426978675],
                [-0.29031120781734804, 0.5381274223327637, -0.3174518426978675],
                [-0.29031120781734804, -0.5381274223327637, 0.3174518426978675],
                [-0.29031120781734804, 0.5381274223327637, 0.3174518426978675],
                [0.29031120781734804, -0.5381274223327637, -0.3174518426978675],
                [0.29031120781734804, 0.5381274223327637, -0.3174518426978675],
                [0.29031120781734804, -0.5381274223327637, 0.3174518426978675],
                [0.29031120781734804, 0.5381274223327637, 0.3174518426978675]],
            "distort": [0.0, 0.0, 0.0, 0.0, 0.0],
            "extrinsic": [[-0.2429226121477801, -0.2506293885132776, 0.9371091260471003, 0.0],
                [-0.009911837278829036, 0.9666372782061301, 0.2559572774195017, 0.0],
                [-0.9699950309094669, 0.05288933725909484, -0.23730225033748942, 0.0],
                [0.012476532015234023, 0.021933435026800476, 0.024992155870001847, 1.0]],
            "global_pose": [[1.0, 0.0, 0.0, 0.0],
                [0.0, 1.0, 0.0, 0.0],
                [0.0, 0.0, 1.0, 0.0],
                [0.0, 0.0, 0.0, 1.0]],
            "global_prob": 1.0,
            "intrinsic": [[2834.314, 0.0, 1093.1019], [0.0, 2834.314, 1933.7009], [0.0, 0.0, 1.0]],
            "message": "VOT_OBJECT_POSE_SUCCESS",
            "obj_prob": 1.0,
            "objid": "rookie",
            "pose": [[0.9968414902687073, 0.014719659462571144, 0.0780409649014473, -0.03976171463727951],
                [-0.006204552017152309, -0.9652349948883057, 0.26131001114845276, 0.16608235239982605],
                [0.07917426526546478, -0.2609688639640808, -0.9620949625968933, 2.5332860946655273],
                [0.0, 0.0, 0.0, 1.0]],
            "poserid": "14dfc56c-a640-4281-9e95-aa49b61d51bd",
            "projectid": "b385865f-67f3-4341-aca5-166d20df952b",
            "sim_prob": 0.9999999255277782,
            "size": [0.5806224156346961, 1.0762548446655273, 0.634903685395735],
            "status": True,
            "type": "normal"
        }
    ]
    "flpose": [[0.9999973932548811, -0.001259764878431, -0.0019043308258140002, 5.813885266846625], ....], 
}
```

#### 실패

조회가 실패한 경우의 응답 예시는 다음과 같습니다.

```
{
  "result": "FAILURE",
  "running_time": {
    "processing": 2
  },
  "timestamp": 1718709558076,
  "version": "3.0.0-1",
  "candidate_obj_id": 0
}
```

참고

API 호출이 실패한 경우의 응답 바디와 응답 예시는 [ARC eye 개요](/docs/arc-eye-overview#%EC%9D%91%EB%8B%B5)를 참조해 주십시오.