External Integration Specifications

Integration Flow

Video Upload/Analysis Procedure

Video Search Procedure

---

Integration Details

Video Upload/Analysis - Request

Request

POST http://{HOST}:{PORT}/api/v1/stt_svc
Content-Type: application/json

{
  "v_id": 202,
  "file_path": "vod/2/202.mp4",
  "title": "2026 KBO KT vs NC",
  "category": "Sports-Baseball",
  "year": 2026,
  "callback_url" : "http://sbs.co.kr/",
  "stream_mode": "N",
  "stream_id" : "20260831120000"
}

The descriptions of each field are as follows

Field	Type	Required	Default	Description
v_id	int	X	N/A	Initially issued (value -100), and subsequently used as a key A key that manages a single game (entire video—episodes 1 through 9)
file_path	String	O	N/A
title	String	O	N/A	Must be written accurately, such as “South Korea vs. the United States.” Meaningless titles are prohibited.
category	String	O	N/A	Fixed as “Sports-Baseball” (Currently, this is the only option.)
year	int	O	N/A	Set to 2026
callback_url	String	X	N/A	When you want to receive a completion report (callback)
stream_mode	String	O	“N”	N = VOD mode, when analyzing the entire video at once Y = Stream mode, when continuously analyzing portions of the video
stream_id	String	X	N/A	Unique identifier for the segmented video Required when stream_mode=stream Ignored when stream_mode=vod Will we generate this ourselves, or will we receive it from the client and use it?
stream_last	String	X	Y	When stream_mode = ‘Y’ Indicates that this is the last video in the stream. When the server receives a ‘Y’, it will no longer accept streams with that v_id.
forced_yn	String	X	“Y”	Y|N VOD mode: If a video exists under the specified v_id, the existing video is deleted and reanalyzed. Stream mode: If a video exists under the specified v_id or stream_id, the existing video is deleted and reanalyzed. In Stream mode, if stream_id has reached a, b, c, or d and you delete b, all subsequent streams are deleted.

Response

Situation	HTTP	Body
Received (vod)	200	{"v_id": 202, "stream_id": "VOD", "code": 0, "result": "OK"}
Received (stream)	200	{"v_id": 202, "stream_id": "333", "code": 0, "result": "OK"}
Throttle Exceeded	200	{"v_id": 202, "code": -1, "result": "busy, retry later"}
Request Format Error	422	Standard Validation Error

---

Video Upload/Analysis - Reporting

Request

[VOD Mode]
POST {callback_url}
Content-Type: application/json

{
  "v_id": 202,
  "stream_id": "VOD",
  "result": "OK",
  "code": 0
}

[Stream Mode]
POST {callback_url}
Content-Type: application/json

{
  "v_id": 202,
  "stream_id": "abc",
  "result": "OK",
  "code": 0
}

The descriptions of each field are as follows

Field	Description
v_id	Unique identifier for the entire video
stream_id	Returned along with v_id in stream mode
result	OK| fail
code	0

Response

HTTP 200 OK

---

Video Search - Request

Request

POST http://{HOST}:{PORT}/api/v1/search_svc
Content-Type: application/json

{
  "v_id": 202,
  "stream_id": "ABC"
  "query": "A scene of a KT starting pitcher striking out a batter",
  "callback_url": "http://sbs.co.kr/"
}

The descriptions of each field are as follows

Field	Type	Required	Description
v_id	int	O	Video to search
stream_id	String	X	The video’s stream_id. The server returns the received stream_id as-is; this is not intended to search only that specific stream
query	String	O	A sentence describing the scene you want to find. Examples: "home run," "comeback scene," etc.
callback_url	String	X	Use this when you want to receive search results via a callback

Response

[If successful]
{"v_id": 201, "stream_id": "a", "search_id": "20260902-0001", "code": 0, "result": "OK"}

[If successful]
{"v_id": 201, "stream_id": "ABC", "search_id": "20260902-0001", "code": 0, "result": "OK"}

[No video available]
{"v_id": 201, "code": -1, "result": "Not found v_id"}

[Exceeded Capacity]
{"v_id": 201, "code": -1, "result": "busy, retry later"}

[Request Format Error]
HTTP 4XX

Field Descriptions

Field	Type	Required	Description
v_id	int	O	Key value for the entire video
stream_id	String	X	Return as-is if a stream_id is present
search_id	string	X	Issued when all search conditions are met
code	int	O	0: Success, other: Failure
result	string	O	Status message

---

Video Search - View

Request

[If successful]
POST {callback_url}
Content-Type: application/json

{
  "v_id": 202,
  "stream_id": "abc",
  "search_id": "20260902-0001",  
  "query": "A scene of a KT starting pitcher striking out a batter",
  "result": "OK",
  "code": 0,
  "scenes": [
    {
      "stream_id": "ABC",
      "start_time": "01:12:33.4",
      "end_time": "01:12:48.9",
      "start_sec": 4353.4,
      "end_sec": 4368.9,
      "text": "[Top of the 5th]\nRun scored"
    },
    {
      "stream_id": "ABC",
      "start_time": "02:05:11.0",
      "end_time": "02:05:26.2",
      "start_sec": 7511.0,
      "end_sec": 7526.2,
      "text": "[Bottom of the 6th]\nStrikeout"
    }
  ]
}

[In case of failure]
{
  "v_id": 202,
  "stream_id": "abc",
  "search_id": "20260902-0001",
  "query": "A scene of a KT starting pitcher striking out a batter",
  "result": "fail",
  "code": -1,
  "scenes": []
}

Response

HTTP 200 OK

---