スキルセット

Classic/VPC環境で利用できます。

特定のスキルセットの APIを呼び出して適切な返答を生成します。

リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

メソッド	URI
POST	/v1/skillsets/{skillset-id}/versions/{version}/final-answer

リクエストヘッダ

リクエストヘッダの説明は次の通りです。

フィールド	必須の有無	説明
`Authorization`	Required	認証用 APIキー<例> `Bearer nv-************`
`X-NCP-CLOVASTUDIO-REQUEST-ID`	Optional	リクエスト ID
`Content-Type`	Required	リクエストデータの形式 `application/json`
`Accept`	Conditional	レスポンスデータの形式 `text/event-stream`

参考

レスポンス結果は基本的に JSON形式で返しますが、Acceptをtext/event-streamに指定するとストリーム形式で返します。

リクエストパスパラメータ

リクエストパスパラメータの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`skillset-id`	String	Required	スキルセット ID
`version`	Integer	Required	スキルセットのバージョン 1 ≤ `version`

リクエストボディ

リクエストボディの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`query`	String	Required	クエリ内容
`tokenStream`	Boolean	Optional	返答生成時のトークンストリーミング使用有無
`chatHistory`	Array	Optional	返答生成履歴
`chatHistory.role`	Enum	Required	会話メッセージのロール `user` \| `assistant` `user`: ユーザーの発話または質問 `assistant`: モデルの返答
`chatHistory.content`	String	Required	会話メッセージの内容
`requestOverride`	Object	Optional	すべての APIに適用する呼び出しオプション
`requestOverride.baseOperation`	Object	Optional	すべての APIに適用する呼び出しオプション情報
`requestOverride.baseOperation.header`	Object	Optional	すべての APIに適用するリクエストヘッダ
`requestOverride.baseOperation.query`	Object	Optional	すべての APIに適用するリクエストクエリパラメータ
`requestOverride.baseOperation.requestBody`	Object	Optional	すべての APIに適用するリクエストボディ GETメソッド APIの場合は適用しない
`requestOverride.operations`	Array	Optional	特定の APIに適用する呼び出しオプション

`operations`

operationsの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`operationId`	String	Conditional	特定の APIのオペレーション ID `operations`の入力時は必須
`header`	Object	Optional	特定の APIに適用するリクエストヘッダ
`query`	Object	Optional	特定の APIに適用するリクエストクエリパラメータ
`requestBody`	Object	Optional	特定の APIに適用するリクエストボディ GETメソッド APIの場合は適用しない

リクエスト例

リクエストのサンプルコードは次の通りです。

curl --location --request POST 'https://clovastudio.stream.ntruss.com/testapp/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": "明日の天気はどう?",
    "tokenStream": true,
    "chatHistory": [
        {
            "role": "user",
            "content": "今日のソウルの天気はどう?"
         },
        {
            "role": "assistant",
            "content": "嵐の前の静けさです。"
         }
     ],
     "requestOverride": {
        "baseOperation": {
            "query": {
                "appid": "appid-11223344"
                }
            }
        }
    }'

レスポンス

レスポンス形式を説明します。

レスポンスヘッダ

レスポンスヘッダの説明は次の通りです。

ヘッダ	必須の有無	説明
Content-Type	-	レスポンスデータの形式 `application/json`

レスポンスボディ

レスポンスボディの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`status`	Object	-	レスポンスステータス
`result`	Object	-	レスポンス結果
`result.finalAnswer`	String	-	モデルの最終実行結果最後まで実行されなかった場合、空の文字列を返す
`result.tokenCount`	Integer	-	返答生成時に測定されたトークン数
`result.useTask`	Boolean	-	呼び出したモデルの学習有無 `false` \| `true` `false`: 学習していない `true`: 学習完了
`result.apiResult`	Array	-	呼び出した APIの結果

`apiResult`

apiResultの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`url`	String	-	返答中に呼び出した API URL
`requestBody`	String	-	返答中に呼び出した APIリクエストボディ
`responseBody`	String	-	返答中に呼び出した APIレスポンスボディ
`apiOrder`	Integer	-	API呼び出しの結果に関係なく、レスポンス順序を固定するためのソート基準
`operationId`	String	-	返答中に呼び出した API Specのオペレーション ID
`nameForHuman`	String	-	返答中に呼び出した APIが登録されたスキルの名前

レスポンス例

レスポンスのサンプルコードは次の通りです。

成功

呼び出しに成功した場合のレスポンスのサンプルコードは次の通りです。

{
  "status": {
    "code": "20000",
    "message": "OK"
  },
  "result": {
    "finalAnswer": "明日のソウルの天気は晴れ、気温は約27度程度と予想されます。",
    "tokenCount": 1032,
    "apiResult": [
      {
        "url": "http://example.com?numOfRows=1&location=서울&date=20240530",
        "requestBody": "string",
        "responseBody": "string",
        "apiOrder": 1,
        "operationId": "weatherAPI",
        "nameForHuman": "WeatherSkill"
      }
    ]
  }
}

失敗

呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。

レスポンスストリーム

生成されるトークンを1つずつ出力するようにトークンストリーミングを使用できます。トークンストリーミング形式を説明します。