Completions

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

プレイグラウンドの一般モード(LKモデル)で会話型の文を生成します。

参考

Completions APIと LKモデルは年内サポート終了予定です。性能が向上した HyperCLOVA Xモデルの使用をお勧めします。

リクエスト

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

メソッド	URI
POST	/v1/completions/{modelName} モデルを使用して文を生成する場合 /v1/tasks/{taskId}/completions チューニング学習した結果を使用して文を生成する場合

リクエストヘッダ

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

ヘッダ	必須の有無	説明
`Authorization`	Required	認証用 APIキー<例> `Bearer nv-************`
`X-NCP-CLOVASTUDIO-REQUEST-ID`	Optional	リクエスト ID
`Content-Type`	Required	リクエストデータの形式 `application/json`

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

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

フィールド	タイプ	必須の有無	説明
`model`	String	Conditional	モデル名モデルを使用して文を生成する場合 <例> LK-D2
`taskId`	String	Conditional	学習 ID チューニング学習の結果を使用して文を生成する場合学習作成 APIのレスポンスボディで確認可能

リクエストボディ

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

フィールド	タイプ	必須の有無	説明
`text`	String	Required	ユーザーの入力値(プロンプト) プロンプトに基づいて新しい文を生成
`topK`	Integer	Optional	生成トークン候補群から確率の高いトークン K個を候補に指定してサンプリング 0 ≤ `topK` ≤ 128 (デフォルト: 0)
`topP`	Float	Optional	生成トークン候補群を累積確率に基づいてサンプリング 0.00 ＜ `topP` ≤ 1.00 (デフォルト: 0.80) 小数点第二位まで表記
`repeatPenalty`	Float	Optional	同じトークンを生成することに対するペナルティの程度(設定値が高いほど同じ結果値を繰り返し生成する確率は下がる) 0.0 ＜ `repeatPenalty` ≤ 10.0 (デフォルト: 5.0)
`stopBefore`	Array	Optional	トークン生成停止文字 [](デフォルト)
`restart`	String	Optional	生成された結果の末尾に付けるテキスト
`start`	String	Optional	ユーザー入力値の末尾に付けるテキスト
`maxTokens`	Integer	Optional	最大トークン生成数 0 ＜ `maxTokens` ≤ 2048 (デフォルト: 100)
`includeTokens`	Boolean	Optional	レスポンスに input_tokens、output_tokensを含めるかどうか `false` \| `true`(デフォルト) `false`: 含めない `true`: 含める
`temperature`	Float	Optional	生成トークンに対する多様性の程度(設定値が高いほど多様な文を生成) 0.00 ＜ `temperature` ≤ 1.00 (デフォルト: 0.50) 小数点第二位まで表記
`includeAiFilters`	Boolean	Optional	AIフィルタ(生成された結果値に対する罵倒、蔑み/差別/嫌悪、セクハラ/わいせつなどカテゴリ別に当てはまる程度)結果を表示するかどうか `false`(デフォルト) \| `true` `false`: 表示しない `true`: 表示

参考

一部フィールドの入力時、下記の内容をご確認ください。

text: 入力したトークン数と maxTokensで入力したトークン数の合計は2,048トークンを超えることはできません。

リクエスト例

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

curl --location --request POST 'https://clovastudio.stream.ntruss.com/v1/completions/LK-D2' \
--header 'Authorization: Bearer {API Key}' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \
--header 'Content-Type: application/json' \
--data '{
  "start": "\n英語: ",
  "stopBefore": ["\n韓国語: "],
  "text": "韓国語: 사과\n英語: Apple\n韓国語: 바나나",
  "includeAiFilters": true
}'

レスポンス

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

レスポンスヘッダ

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

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

レスポンスボディ

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

フィールド	タイプ	必須の有無	説明
`status`	Object	-	レスポンスステータス
`result`	Object	-	レスポンス結果
`result.text`	String	-	生成トークン(プロンプトと生成された結果値)
`result.stopReason`	String	-	結果生成停止の理由 `length` \| `end_token` \| `stop_before` `length`: 長さ制限 `end_token`: トークン数制限 `stop_before`: 回答生成中`stopBefore`に指定した文字が登場
`result.startLength`	Integer	-	入力トークン数
`inputText`	String	-	ユーザー入力値(プロンプト)
`result.inputLength`	Integer	-	入力トークン数(課金の基準で、end of turnといった特殊なトークンも含む)
`result.inputTokens`	Array	-	入力トークン情報
`result.outputText`	Integer	-	生成結果値
`result.outputLength`	Integer	-	生成トークン数
`result.outputTokens`	Array	-	生成トークン情報
`result.probs`	Array	-	レスポンストークンの候補トークンと候補トークンの確率
`result.ok`	Boolean	-	レスポンスは成功したかどうか `false` \| `true` `false`: レスポンス失敗。エラーメッセージを返す `true`: レスポンス成功
`aiFilter`	Array	-	AIフィルタの結果

`aiFilter`

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

フィールド	タイプ	必須の有無	説明
`groupName`	String	-	AIフィルタのカテゴリ `curse` \| `unsafeContents` `curse`: 蔑み、差別、嫌悪および罵倒 `unsafeContents`: セクハラ、わいせつ
`name`	String	-	AIフィルタの詳細カテゴリ `discrimination` \| `insult` \| `sexualHarassment` `discrimination`: 蔑み、差別、嫌悪 `insult`: 罵倒 `sexualHarassment`: セクハラ、わいせつ
`score`	String	-	AIフィルタスコア `-1` \| `0` \| `1` \| `2` `-1`: AIフィルタにエラー発生 `0`: 会話メッセージに要注意/危険な表現を含む可能性が高い `1`: 会話メッセージに要注意/危険な表現を含む可能性がある `2`: 会話メッセージに要注意/危険な表現を含む可能性が低い
`result`	String	-	AIフィルタは正常に動作しているか `OK` \| `ERROR` `OK`: 正常に動作 `ERROR`: エラー発生

参考

AI Filterは最大500文字まで分析できます。ただし、分析対象テキストに異常な形式、絵文字、記号などが多い場合、正常に分析されないことがあります。

レスポンス例

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

成功

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

{
 
    "status": {
        "code": "20000",
        "message": "OK"
    },
    "result": {
        "text": "豊かな感受性のキャッチコピーを作成しなさい\n\n商品: 乳液\nキャッチコピー: お肌に触れる瞬間、満たされる潤い\n###\n商品: 手帳\nキャッチコピー: 自分へのご褒美",
        "stopReason": "end_token",
        "startLength": 33,
        "inputText": "豊かな感受性のキャッチコピーを作成しなさい\n\n商品: 乳液\nキャッチコピー: お肌に触れる瞬間、満たされる潤い\n###\n商品: 手帳",
        "inputLength": 33,
        "inputTokens": ["豊かな","感受性","の"," キャッチ"," コピー","を"," 作成","しなさい","\n",
        "\n","商品",":"," 乳液","\n","キャッチコピー",":","お","肌","に","触れる","瞬間","、","満たされる","潤い",
        "\n","##","#","\n","商品",":"," 手帳","\n","キャッチコピー",":"
        ],
        "outputText": "\nキャッチコピー: 自分へのご褒美",
        "outputLength": 7,
        "outputTokens": ["自分","へ","の","ご","褒美",""
        ],
        "probs": [],
        "ok": true,
        "aiFilter": [
            {
                "groupName": "curse",
                "name": "insult",
                "score": "2"
            },
            {
                "groupName": "curse",
                "name": "discrimination",
                "score": "1"
            },
            {
                "groupName": "unsafeContents",
                "name": "sexualHarassment",
                "score": "2"
            }
        ]
    }
}

失敗

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