Request scene summary utilization

Available in VPC

Request a conversion job that generates text or scene metadata tailored to your purpose, based on the latest scene summary results for an asset. The target for conversion is automatically selected from the latest scene summary results for that asset. The conversion is processed asynchronously. Use the conversion job ID returned upon request to check the progress and results via Get scene summary utilization result.

Note

Conversions can only be requested for assets for which scene summary has been completed. An error will be returned if no scene summary exists or if one is currently in progress.
Regardless of the preset, only one conversion can be processed at a time for a single asset. If you request a new conversion while one is in progress, an error will be returned. You can request it again after the previous conversion is complete.
The language (locale) of the conversion result is inherited from the scene summary and cannot be specified separately in the conversion request.
Conversion requests are limited to 60 per minute per workspace. If this limit is exceeded, an error will be returned.

Request

This section describes the request format. The method and URI are as follows:

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

Request headers

For information about the headers common to all Media Intelligence APIs, see Media Intelligence request headers.

Request path parameters

The following describes the parameters.

Field	Type	Required	Description
`workspace_name`	String	Required	Workspace name
`project_id`	String	Required	Project ID See Get project list.
`asset_id`	String	Required	Media asset ID See Get media asset list. For conversion, the latest scene summary result for that asset is automatically selected.

Request body

You can include the following data in the body of your request:

Field	Type	Required	Description
`preset`	String	Required	Conversion preset `SCENE_DIGEST`: Create scene-level summary (title, keywords, summary paragraph). `SCENE_METADATA`: Create scene-level tags and metadata.
`outputFields`	Array<String>	Optional	Select output fields to return (for `SCENE_DIGEST` only). `title` \| `keywords` \| `paragraphs` If not specified, all of `title`, `keywords`, and `paragraphs` are returned. An error is returned if passed to `SCENE_METADATA`.
`keywordCount`	Integer	Optional	Number of keywords per scene (`SCENE_DIGEST` only) `1`-`30` (default:`10`) An error is returned if passed without including `keywords` in `outputFields`.
`paragraphCount`	Integer	Optional	Number of summary paragraphs per scene (`SCENE_DIGEST` only) `1`-`5` (default:`3`) An error is returned if passed without including `paragraphs` in `outputFields`.

Request example

The request example is as follows:

The following is a sample request for the SCENE_DIGEST preset.

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
}'

The following is a sample request for the SCENE_METADATA preset.

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"
}'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`code`	String	-	API processing result code
`message`	String	-	API processing result message
`result`	Object	-	Conversion request submission information
`result.id`	Integer	-	Conversion job ID Use for Get scene summary utilization conversion result.
`result.preset`	String	-	Requested conversion preset
`result.locale`	String	-	Conversion result language Inherit scene summary language. BCP 47 format (e.g., `ko-KR`, `en-US`).
`result.createdTime`	String	-	Conversion request creation date and time ISO 8601 format

Response status codes

For information about the HTTP status codes common to all Media Intelligence APIs, see Media Intelligence response status codes.

Response example

The response example is as follows:

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

Documentation Index