장면 분할 API란?
동영상에서 장면이 변화하는 시점을 탐지하여, 동영상을 썸네일로 요약하거나 편집을 용이하게 하는 포인트를 제공합니다. 동영상의 각 프레임의 특성 추출 후 특성이 시간적으로 크게 변화하는 시점을 탐지하여 출력합니다.
장면 분할 API는 HTTP 기반의 REST API 인터페이스로 JSON 포맷 기반의 입력 및 출력을 지원하며 ETRI에서 제공하는 API Key 인증을 통해 사용할 수 있는 Open API 입니다.
API 호출 1일 허용량
| 기술명 | API명 | 1일 허용량 |
|---|---|---|
| 동영상 인식 기술 |
|
100건/일 |
|
- |
- 동영상의 최대 용량은 50MB까지 업로드할 수 있습니다.
- 동영상의 영상 길이는 최소 5초 이상되어야 합니다.
- 동영상의 영상 길이는 최대 5분 미만이어야 합니다.
- 동영상의 영상 길이는 최소 5초 이상되어야 합니다.
- 동영상의 영상 길이는 최대 5분 미만이어야 합니다.
장면 분할 API 사용하기
장면 분할 API는 파일 업로드 API이며, 동영상 경로와 확장자를 HTTP 통신으로 ETRI Open API 서버에 전달하면 됩니다. 서버가 제공하는 파일 업로드 API의 URI는 다음과 같으며 POST 방식으로 호출해야 합니다.
http://epretx.etri.re.kr:8000/api/VideoParse
[HTTP Request Header]
"Authorization" : "YOUR_ACCESS_KEY"
Content-Type:multipart/form-data; boundary=----[파일 구분자 문자열]
[HTTP Request Body]
{
------[파일 구분자 문자열]
Content-Disposition: form-data; name="json"
{ "request_id": "reserved field", "argument": {} }
------[파일 구분자 문자열]
Content-Disposition: form-data; name="uploadfile"; filename="[파일 명]"
Content-Type: [파일 타입]
[파일의 Byte 문자열]
------[파일 구분자 문자열]--
}
위와 같은 HTTP 요청을 e-PreTX 서버로 전달하면 서버는 JSON 형태의
Text 데이터를 HTTP 응답 메시지로 반환합니다. 다음은 HTTP 응답 예제 입니다.
[HTTP Response Header]
Access-Control-Allow-Origin:*
Connection:close
Content-Length:0
Content-Type:application/json; charset=UTF-8
[HTTP Response Body]
{
"request_id": "reserved field",
"result": 0,
"return_type": "com.google.gson.internal.LinkedTreeMap",
"return_object": {비디오 파일 ID}
}
장면 분할 상태 체크 API 사용하기
장면 분할 상태 체크 API는 REST API이며, 장면 분할 API 결과로 전달 받은 비디오 파일 ID를 HTTP 통신으로 ETRI Open API 서버에 전달하면 됩니다. 서버가 제공하는 REST API의 URI는 다음과 같으며 POST 방식으로 호출해야 합니다.
http://epretx.etri.re.kr:8000/api/VideoParse/status
[HTTP Request Header]
"Authorization" : "YOUR_ACCESS_KEY"
[HTTP Request Body]
{
"request_id": "reserved field",
"argument": {
"file_id": {비디오 파일 파일 ID}
}
}
위와 같은 HTTP 요청을 e-PreTX 서버로 전달하면 서버는 JSON 형태의
Text 데이터를 HTTP 응답 메시지로 반환합니다. 다음은 HTTP 응답 예제 입니다.
[HTTP Response Header]
Access-Control-Allow-Origin:*
Connection:close
Content-Length:0
Content-Type:application/json; charset=UTF-8
[HTTP Response Body]
{
"result": [{
"num": {처리 번호},
"code": {결과 코드},
"msg": {결과 메시지},
"frame": {구분된 프레임 정보},
"time": {구분된 시간 정보}
}]
}
구현 예제(Python)
python 3.0을 기준으로 작성되었습니다.
HTTP 통신을 위해 urllib3 라이브러리를 사용하여 제공하고 있습니다. Python 3.0 이하의 버전에서
예제를 실행하기 위해서는 별도로 urllib3의 설치가 필요합니다.
설치에 대한 설명은 https://pypi.python.org/pypi/urllib3 를 참고하시기 바랍니다.
설치에 대한 설명은 https://pypi.python.org/pypi/urllib3 를 참고하시기 바랍니다.
urllib3 라이브러리에 대한 자세한 설명은 https://urllib3.readthedocs.io/en/latest/
에서 확인 하실 수 있습니다.
#-*- coding:utf-8 -*-
import urllib3
import json
openApiURL = "http://epretx.etri.re.kr:8000/api/VideoParse"
accessKey = "YOUR_ACCESS_KEY"
videoFilePath = "VIDEO_FILE_PATH"
file = open(videoFilePath, "rb")
imageContents = base64.b64encode(file.read()).decode("utf8")
file.close()
requestJson = {
"argument": {}
}
http = urllib3.PoolManager()
response = http.request(
"POST",
openApiURL,
headers={"Content-Type": "application/json; charset=UTF-8","Authorization" : accessKey},
body=json.dumps(requestJson)
)
print("[responseCode]" + str(response.status))
print("[responBody]")
print(str(response.data,"utf-8"))
장면 분할 검출 레퍼런스
다음은
파라미터에 대한 설명입니다.
| Field 명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| json | String | ○ | API 사용을 위해 ETRI에서 발급한 사용자 API Key 정보가 포함된 json 문자열 |
| uploadfile | File | ○ | API 사용 요청 시 분석을 위해 전달할 비디오 파일 |
분석된 결과는 다음과 같은 내용이 포함되어 있습니다.
| 구분 | JSON Key 이름 | 설명 |
|---|---|---|
| 장면 분할 기본정보 | file_id | 장면분할처리를 위한 file의 ID |
분석된 결과는 다음과 같은 내용이 포함되어 있습니다.
| 구분 | JSON Key 이름 | 설명 |
|---|---|---|
| 장면
분할 기본정보 |
num | 장면분할의 처리 번호 |
| code | 장면분할의 처리 결과 코드 | |
| msg | 장면분할의 처리 결과 메시지 | |
| frame | 장면분할의 결과로 나온 총 분할시점의 숫자 | |
| time | 분할된 구간의 시작 시점 (초) |
장면 분할이 제대로 이루어지지 않았을 경우에는 장면 분할 결과 대신 오류 메시지가 반환됩니다.
| JSON Key | 오류 메시지 | 설명 |
|---|---|---|
| error | Video file does not exist | 비디오 파일이 없는 경우 (업로드 오류 등으로 인해 파일이 없는 경우) |
| This file type is not allowed | 비디오 파일의 확장자가 맞지 않는 경우 | |
| This file is the corrupted file | 파일이 있고 확장자가 맞지만, 파일이 읽을 수 없는 비디오일 경우 (파일 손상) | |
| Video length is too long | 비디오 길이가 제한 길이보다 긴 경우 | |
| Video length is too short | 비디오 길이가 너무 짧은 경우 | |
| This file is not allowed file type | 파일 타입(확장자)이 ‘avi’, ‘mp4’, ‘png’, ‘bmp’가 아닐 경우 | |
| This file is not an available video file | 파일 타입(확장자)은 맞지만 입력된 파일이 코덱이나 업로드 등으로 비디오를 읽을 수 없는 경우 |
장면 분할 API의 오류 코드 목록은 다음과 같습니다.
| http status code | result | reason | 설명 |
|---|---|---|---|
| 403 | -1 | Empty Auth Header | Authorization 헤더가 없는 경우 |
| 403 | -1 | Invalid Key | KEY
API 키가 없는 경우 |
| 403 |
-1 | Blocked KEY | API
키가 관리자에 의해서 차단된 경우 |
| 403 |
-1 | Daily Limit Exceeded | 일간 호출 제한에 걸린 경우 |
| 403 |
-1 | Monthly
Limit Exceeded |
월간 호출 제한에 걸린 경우 |
| 403 |
-1 | Yearly
Limit Exceeded |
연간 호출 제한에 걸린 경우 |
| 403 |
-1 | Too Many Keys | 같은 IP에서 여러 API 키가 사용된 경우 |
| 403 |
-1 | Too Many IPs | 하나의 API 키를 여러 IP 에서 사용한 경우 |
| 403 |
-1 | Not Allowed IP | API
호출 가능한 IP 가 아닌경우 (API 설정에서 허용된 IP가 아닌경우) |
| 403 |
-1 | Not Allowed Subpath | 하위경로 접근 제한이 되어 있는 경우 |
| 403 | -1 | Invalid
API |
등록되지
않은 API를 요청한 경우 |
| 408 | -1 |
Request
Timeout |
서버의
요청 대기가 시간을 초과한 경우 |
| 413 |
-1 | Body
Size Limit Exceeded |
요청
바디가 설정된 값보다 큰 경우 |
| 429 |
-1 | Concurrent
Limit Exceeded |
연속호출
허용 범위를 넘어서 호출한 경우 |
| 500 | -1 | Internal Server Error | 내부 오류 발생한 경우 |
