判定

テキストへの質問に確率つきで答える /v1/decisions と /v1/systemone の使い方です。

対応モデル

判定 API は、テキストに対する Yes/No・分類・スコアの質問に、文章ではなく確率で答えます。 同じモデルを /v1/decisions(OpenAI SDK の client.decisions.create の形)と /v1/systemone の 2 つの形で呼べます。テキスト生成とは別サーフェスのため、モデル ID は GET /v1/models には含まれません(GET /v1/decisions/models で確認できます)。トライアルキーは対象外です。

モデル IDモデル名精度入力 ¥/1M tok
clef-flashClef Flash
利用モデル Cloudflare/clef-flash
BF16¥20

/v1/decisions

input に判定対象、questions に質問を配列で渡します。答えは質問と同じ順で answers に返ります。

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.router.hello.ai/v1",
  apiKey: "hello_...",
});

const res = await client.decisions.create({
  model: "clef-flash",
  input: "届いた商品が壊れていました。返金してください。",
  questions: [
    { type: "predicate", name: "refund", instructions: "返金を求めていますか?" },
    {
      type: "choice",
      name: "topic",
      instructions: "問い合わせの種類はどれですか?",
      choices: [{ value: "配送" }, { value: "請求" }, { value: "その他" }],
    },
    {
      type: "score",
      name: "anger",
      instructions: "どのくらい怒っていますか?",
      levels: [{ label: "落ち着いている" }, { label: "不満" }, { label: "激怒" }],
    },
  ],
});
console.log(res.answers);
curl https://api.router.hello.ai/v1/decisions \
  -H "Authorization: Bearer hello_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "clef-flash",
    "input": "届いた商品が壊れていました。返金してください。",
    "questions": [
      { "type": "predicate", "name": "refund", "instructions": "返金を求めていますか?" }
    ]
  }'
{
  "model": "clef-flash",
  "answers": [
    { "type": "predicate", "name": "refund", "probability": 0.98 }
  ],
  "usage": {
    "input_tokens": 151,
    "input_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 0 },
    "output_tokens": 0,
    "output_tokens_details": { "reasoning_tokens": 0 },
    "total_tokens": 151
  }
}
質問の type渡すもの返るもの
predicateinstructionsprobability(Yes である確率、0〜1)
choiceinstructions と choices(2〜255 件。value は文字列か真偽値、description は任意)choice(最も確率の高い値)・probabilities・confidence
scoreinstructions と levels(低い順に 2〜10 件。label と任意の description)score(レベル番号の期待値。先頭が 0)・probabilities・confidence

input は文字列のほか、role: "user" のメッセージ配列も受け付けます(content は文字列か input_text パーツの配列)。name は任意で、答えにそのまま返ります。

/v1/systemone

state に判定対象、questions に質問をキー付きのオブジェクトで渡します。答えは同じキーで返ります。state と instructions / criteria の値には、文字列だけでなく JSON のオブジェクトや配列をそのまま渡せます。

curl https://api.router.hello.ai/v1/systemone \
  -H "Authorization: Bearer hello_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "clef-flash",
    "state": [{ "role": "customer", "text": "届いた商品が壊れていました。返金してください。" }],
    "questions": {
      "refund": { "type": "noul", "instructions": "返金を求めていますか?" },
      "topic": {
        "type": "choice",
        "criteria": { "配送": "配達や破損の問題", "請求": null, "その他": null }
      },
      "anger": {
        "type": "score",
        "instructions": "どのくらい怒っていますか?",
        "criteria": ["落ち着いている", "不満", "激怒"]
      }
    }
  }'
{
  "model": "clef-flash",
  "answers": {
    "refund": { "type": "noul", "noul": 0.98 },
    "topic": {
      "type": "choice",
      "choice": "配送",
      "confidence": 0.53,
      "probabilities": { "配送": 0.69, "請求": 0.08, "その他": 0.23 }
    },
    "anger": {
      "type": "score",
      "score": 0.88,
      "confidence": 0.5,
      "legend": { "0": "落ち着いている", "1": "不満", "2": "激怒" },
      "probabilities": { "0": 0.23, "1": 0.67, "2": 0.1 }
    }
  },
  "usage": { "input_tokens": 310, "output_tokens": 0 }
}
  • noul(Yes/No)は instructions か criteria(true / false それぞれの説明)のどちらかが必須です。
  • choice の criteria は「ラベル: 説明」のオブジェクトです(1〜255 件。説明が不要なら null)。
  • score の criteria は低い順に並べたレベルの配列です(1〜10 件)。

仕様と課金

  • 1 リクエストの入力は 16,384 トークン未満です(判定対象と質問の合計)。超えると 400(code: context_length_exceeded)を返し、課金しません。長い文書は分割して送ってください。
  • 入力はテキストのみです。画像・音声・動画(images / input_image など)と、画像内の位置を答える box 質問には対応していません(400 を返します)。
  • 質問は 1 リクエストに 128 件まで入れられます。同じ判定対象への質問はまとめて送ると、判定対象の トークンを 1 回分しか消費しません。
  • 分類の選択肢名(choices の value、criteria のラベル)は、空文字・改行・制御文字を含められません。大文字と小文字、前後の空白だけが違う名前は同じものとして扱うため、1 つの質問の中で重複させられません。
  • 質問の中にこのページに無いキーがあると 400 を返します。temperature などの生成パラメータは受け取っても使いません(判定は確率をそのまま返すため、指定する箇所がありません)。
  • /v1/decisions の答えは、モデルが判定を控えた質問について { "type": "refusal" } になることがあります。
  • ストリーミングには対応していません。応答は同期で返ります。
  • 課金は入力トークンのみです。答えは確率のためトークンを持たず、レスポンスの usage.output_tokens は常に 0 です。定額プランの対象外で、クレジットから消費します。