Skillset

Available in Classic and VPC

Call the API for a specific skillset to generate the appropriate response.

Request

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

Method	URI
POST	/v1/skillsets/{skillset-id}/versions/{version}/final-answer

Request headers

The following describes the request headers.

Field	Required	Description
`Authorization`	Required	API key for authentication Example: `Bearer nv-************`
`X-NCP-CLOVASTUDIO-REQUEST-ID`	Optional	Request ID
`Content-Type`	Required	Request data format `application/json`
`Accept`	Conditional	Response data format `text/event-stream`

Note

Response results are returned in JSON by default, but if you specify Accept as text/event-stream, then the response results are returned as a stream.

Request path parameters

You can use the following path parameters with your request:

Field	Type	Required	Description
`skillset-id`	String	Required	Skillset ID
`version`	Integer	Required	Skillset version 1 ≤ `version`

Request body

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

Field	Type	Required	Description
`query`	String	Required	Query details
`tokenStream`	Boolean	Optional	Whether to use token streaming when generating answers `false` \| `true` `false`: Not use `true`: Use
`chatHistory`	Array	Optional	Answer generation history
`chatHistory.role`	Enum	Required	Conversation message role `user` \| `assistant` `user`: user's utterance or question `assistant`: model's answer
`chatHistory.content`	String	Required	Content of conversation messages
`requestOverride`	Object	Optional	Call options to apply to all APIs
`requestOverride.baseOperation`	Object	Optional	Call option information to apply to all APIs
`requestOverride.baseOperation.header`	Object	Optional	Request header to apply to all APIs
`requestOverride.baseOperation.query`	Object	Optional	Request query parameter to apply to all APIs
`requestOverride.baseOperation.requestBody`	Object	Optional	Request body to apply to all APIs Not applied to GET method APIs
`requestOverride.operations`	Array	Optional	Call options to apply to specific APIs

`operations`

The following describes operations.

Field	Type	Required	Description
`operationId`	String	Conditional	Operation ID of a specific API Required when entering `operations`
`header`	Object	Optional	Request header to apply to a specific API
`query`	Object	Optional	Request query parameter to apply to a specific API
`requestBody`	Object	Optional	Request body to apply to specific APIs Not applied to GET method APIs

Request example

The request example is as follows:

curl --location --request POST 'https://clovastudio.stream.ntruss.com/v1/skillsets/{skillset-id}/versions/{version}/final-answer' \
--header 'Authorization: Bearer {API Key}' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \
--header 'Content-Type: application/json' \
--data '{  
    "query": "What will the weather be like tomorrow?",
    "tokenStream": true,
    "chatHistory": [
        {
            "role": "user",
            "content": "How is the weather in Seoul today?"
         },
        {
            "role": "assistant",
            "content": "It's the calm before the storm."
         }
     ],
     "requestOverride": {
        "baseOperation": {
            "query": {
                "appid": "appid-11223344"
                }
            }
        }
    }'

Response

This section describes the response format.

Response headers

The following describes the response headers.

Headers	Required	Description
Content-Type	-	Response data format `application/json`

Response body

The response body includes the following data:

Field	Type	Required	Description
`status`	Object	-	Response status
`result`	Object	-	Response result
`result.finalAnswer`	String	-	Final execution result of the model If not run to the end, return an empty string.
`result.tokenCount`	Integer	-	Number of tokens measured when generating answers
`result.useTask`	Boolean	-	Whether the called model is trained `false` \| `true` `false`: not trained `true`: training completed
`result.apiResult`	Array	-	Called API result

`apiResult`

The following describes apiResult.

Field	Type	Required	Description
`url`	String	-	API URL called during the answer process
`requestBody`	String	-	API request body called during the answer process
`responseBody`	String	-	API response body called during the answer process
`apiOrder`	Integer	-	Sort by to fix the order of responses regardless of the result of the API call
`operationId`	String	-	Operation ID of the API Spec called during the answer process
`nameForHuman`	String	-	Name of the skill in which the API called during the answer process is registered

Response example

The response example is as follows:

Succeeded

The following is a sample response upon a successful call.

{
  "status": {
    "code": "20000",
    "message": "OK"
  },
  "result": {
    "finalAnswer": "The weather in Seoul tomorrow is expected to be sunny, with temperatures around 27 degrees.",
    "tokenCount": 1032,
    "apiResult": [
      {
        "url": "http://example.com?numOfRows=1&location=서울&date=20240530",
        "requestBody": "string",
        "responseBody": "string",
        "apiOrder": 1,
        "operationId": "weatherAPI",
        "nameForHuman": "WeatherSkill"
      }
    ]
  }
}

Failure

The following is a sample response upon a failed call.

Response stream

You can use token streaming to output the tokens as they are generated, one by one. The following describes the token streaming format.