장면 요약 활용 요청

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

에셋의 최신 장면 요약(scene summary) 결과를 기반으로 목적별 변환 텍스트 또는 장면 메타데이터를 생성하는 변환 작업을 요청합니다. 변환 대상은 해당 에셋의 최신 장면 요약 결과가 자동으로 선택됩니다. 변환은 비동기로 처리되며, 요청 시 반환되는 변환 작업 ID로 장면 요약 활용 결과 조회를 통해 진행 상태와 결과를 확인합니다.

참고

변환은 장면 요약이 완료된 에셋에서만 요청할 수 있습니다. 장면 요약이 없거나 진행 중인 경우 에러가 반환됩니다.
하나의 에셋에는 프리셋과 무관하게 동시에 하나의 변환만 처리할 수 있습니다. 진행 중인 변환이 있는 상태에서 새 변환을 요청하면 에러가 반환되며, 이전 변환이 완료된 후 다시 요청할 수 있습니다.
변환 결과의 언어(locale)는 장면 요약의 언어를 상속하며, 변환 요청에서 별도로 지정할 수 없습니다.
워크스페이스당 변환 요청은 분당 60회로 제한되며, 한도를 초과하면 에러가 반환됩니다.

요청

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

메서드	URI
POST	/api/v1/workspaces/{workspace_name}/projects/{project_id}/assets/{asset_id}/scene-summary/transformations

요청 헤더

Media Intelligence API에서 공통으로 사용하는 헤더에 대한 정보는 Media Intelligence 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`workspace_name`	String	Required	워크스페이스 이름
`project_id`	String	Required	프로젝트 ID 프로젝트 목록 조회 참조
`asset_id`	String	Required	미디어 에셋 ID 미디어 에셋 목록 조회 참조 변환 대상은 해당 에셋의 최신 장면 요약 결과가 자동으로 선택됨

요청 바디

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

필드	타입	필수 여부	설명
`preset`	String	Required	변환 프리셋 `SCENE_DIGEST`: 장면 단위 요약(제목·키워드·요약 문단) 생성 `SCENE_METADATA`: 장면 단위 태그 및 메타데이터 생성
`outputFields`	Array<String>	Optional	반환할 출력 필드 선택(`SCENE_DIGEST` 전용) `title` \| `keywords` \| `paragraphs` 미입력 시 `title`, `keywords`, `paragraphs` 전체 반환 `SCENE_METADATA`에 전달 시 에러 반환
`keywordCount`	Integer	Optional	장면당 키워드 개수(`SCENE_DIGEST` 전용) `1`~`30` (기본값:`10`) `outputFields`에 `keywords`를 포함하지 않은 상태에서 전달 시 에러 반환
`paragraphCount`	Integer	Optional	장면당 요약 문단 개수(`SCENE_DIGEST` 전용) `1`~`5` (기본값: `3`) `outputFields`에 `paragraphs`를 포함하지 않은 상태에서 전달 시 에러 반환

요청 예시

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

SCENE_DIGEST 프리셋 요청 예시입니다.

curl --location --request POST 'https://mi.apigw.ntruss.com/api/v1/workspaces/my-workspace/projects/1234/assets/5678/scene-summary/transformations' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
    "preset": "SCENE_DIGEST",
    "outputFields": ["title", "keywords"],
    "keywordCount": 20
}'

SCENE_METADATA 프리셋 요청 예시입니다.

curl --location --request POST 'https://mi.apigw.ntruss.com/api/v1/workspaces/my-workspace/projects/1234/assets/5678/scene-summary/transformations' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
    "preset": "SCENE_METADATA"
}'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`code`	String	-	API 처리 결과 코드
`message`	String	-	API 처리 결과 메시지
`result`	Object	-	변환 요청 접수 정보
`result.id`	Integer	-	변환 작업 ID 장면 요약 활용 변환 결과 조회 시 사용
`result.preset`	String	-	요청한 변환 프리셋
`result.locale`	String	-	변환 결과 언어 장면 요약 언어를 상속 BCP 47 형식(예: `ko-KR`, `en-US`)
`result.createdTime`	String	-	변환 요청 생성 일시 ISO 8601 형식

응답 상태 코드

Media Intelligence API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Media Intelligence 응답 상태 코드를 참조해 주십시오.

응답 예시

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

{
    "code": "0",
    "message": "success",
    "result": {
        "id": 2001,
        "preset": "SCENE_DIGEST",
        "locale": "en-US",
        "createdTime": "2026-05-22T14:30:00"
    }
}

Documentation Index