Generate skillset answer

English

Generate skillset answer

Article summary

Did you find this summary helpful?

Thank you for your feedback

Available in Classic and VPC

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

Request

The following describes the request format for the endpoint. The request format is as follows:

Method	URI
POST	/v1/skillsets/{skillset-id}/versions/{version}/final-answer Version specified /v1/tasks/{taskId}/chat-completions Version not specified

Request headers

The following describes the request headers.

Field	Required	Description
`X-NCP-CLOVASTUDIO-API-KEY`	Required	API key issued when creating the test app or service app
`X-NCP-APIGW-API-KEY`	Required	API Gateway key issued when creating the test app or service app
`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

The following describes the request path parameters.

Field	Type	Required	Description
`skillset-id`	String	Required	Skillset ID to generate answers for
`version`	Integer/String	Required	Skillset version to generate answers for Specify a version to enter when using the skillset `{Version number}` \| `latest` `{Version number}`: specific version 1 ≤ `version` `latest`: currently applied version

Note

You can request version as either an integer or a string, depending on which version of the skillset you want to enter.

Request body

The following describes the request body.

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 following is a sample request.

curl --location --request POST 'https://clovastudio.stream.ntruss.com/testapp/v1/skillsets/{skillset-id}/versions/{version}/final-answer' \
--header 'X-NCP-CLOVASTUDIO-API-KEY: {CLOVA Studio API Key}' \
--header 'X-NCP-APIGW-API-KEY: {API Gateway 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

The following 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 following describes the response body.

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 following is a sample example.

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.

Response headers

The following describes the response headers.

Field	Required	Description
Accept	-	Response data format `text/event-stream`

Response body

The following describes the response body.

Field	Type	Requirement status	Description
`selectedSkill`	Object	-	Name of the selected skill Only displayed in planning events
`finalAnswer`	String	-	Final execution result of the model If not run to the end, return an empty string Only displayed in FinalAnswer events
`tokenCount`	Integer	-	Number of tokens used in the event
`apiResult`	Object	-	Results of APIs called during the answer process Only displayed in FinalAnswer events
`apiResult.url`	String	-	API URL called during the answer process
`apiResult.requestBody`	String	-	API request body called during the answer process
`apiResult.responseBody`	String	-	API response body called during the answer process
`apiResult.apiOrder`	Integer	-	Sort by to fix the order of responses regardless of the result of the API call
`apiResult.operationId`	String	-	Operation ID of the API Spec called during the answer process
`apiResult.nameForHuman`	String	-	Name of the skill in which the API called during the answer process is registered

Token Event

The following describes TokenEvent.

Field	Type	Required	Description
`probs`	Array	-	List of response candidate tokens and probability values for each token
`stopReason`	String	-	Reason for stopping results generation (generally passed to the last event) `length` \| `end_token` \| `stop_before` `length`: length limit `end_token`: token count limit `stop_before`: Settings value specified in `stopBefore` occurred during answer generation
`text`	String	-	Complete text pair

Response example

The following is a sample example.

Succeeded

The following is a sample response upon a successful call.

id: aabdfe-dfgwr-edf-hpqwd-f2asd-g
event: planning
data: {"selectedSkill": {["nameForHuman":"Search hotel"]}, "tokenCount": 432}
id: aabdfe-dfgwr-edf-hpqwd-f1asd-g
event: cot
data: {"apiResult": [{"url": "https://example.com/search_reviews_get?keyword=accessible to subway station", "requestBody": "keyword=accessible to subway station", "responseBody": "[{\"review_id\": 5,
\"review_date\": \"20230809\", \"reviewer\": \"ClaudeCalder\", \"rating\": 4.0, \"content\": \"I was disappointed
that they didn't have a sauna, pool, or other facilities, but the price was reasonable. There's a subway station and a convenience store
nearby. It's perfect for a short stay.\", \"hotel_name\": \"Movenpick Hotel\", \"address\": \"120 Walkerhill-ro,
Gwangjin-gu, Seoul\", \"room_name\": \"City View\", \"good_cnt\": 9, \"bad_cnt\": 0, \"rating_service\":
3. 0, \"rating_clean\": 4.0, \"rating_room\": 4.0}]", "apiOrder": 1}], "tokenCount": 2401 }
id: aabdfe-dfgwr-edf-hpqwd-f2asd-g
event: finalAnswer
data: {"finalAnswer": "A hotel with good subway access in Seoul is Movenpick Hotel, located at 120 Walkerhill-ro,
Gwangjin-gu, Seoul.", "apiResult": [{"url": "https://example.com/search_reviews_get?keyword=accessible to subway station", "requestBody": "keyword=accessible to subway station", "responseBody":
"[{\"review_id\": 5, \"review_date\": \"20230809\", \"reviewer\": \"ClaudeCalder\", \"rating\": 4.0,
\"content\": \"I was disappointed that they didn't have a sauna, pool, or other facilities, but the price was reasonable. There's a subway station
and a convenience store nearby. It's perfect for a short stay.\", \"hotel_name\": \"Movenpick Hotel\",
\"address\": \"120 Walkerhill-ro, Gwangjin-gu, Seoul\", \"room_name\": \"City View\", \"good_cnt\": 9, \"bad_cnt\":
0, \"rating_service\": 3.0, \"rating_clean\": 4.0, \"rating_room\": 4.0}]", "apiOrder": 1}],
"tokenCount": 214 }
...

Failure

The following is a sample response upon a failed call.

Was this article helpful?

What's Next

Troubleshooting CLOVA Studio

Table of contents

Request
Response
Response stream