メインコンテンツまでスキップ

AI呼び出し(mlapi)

sdk.mlapi.fetchはfetchと同じ関数です。mlapiのドキュメントにあるサンプルコードをそのまま持ってきてfetchだけをsdk.mlapi.fetchに置き換えると、学習資料サーバーが閲覧者本人のキーを付けてmlapiに送信し、レスポンスをそのまま返します。コンテンツにAPIキーを入れません。

個人情報の禁止

リクエスト本文(プロンプト)に学習者の個人情報(氏名・連絡先・学籍番号など)を入れないでください。本文は外部のAIモデルに送られます。学習者が書いた文章を送る場合は、入力欄の近くに「個人情報は入力しないでください」と案内します。

// mlapi 문서 예시에서 fetch만 바꿈 (Authorization은 지워도 되고, 남겨도 SDK가 덮어씀)
const response = await sdk.mlapi.fetch('https://mlapi.run/<api_id>/v1/chat/completions', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Authorization: 'Bearer {API_KEY}' },
body: JSON.stringify({ model: '<model>', messages: [{ role: 'user', content: '안녕' }] }),
});
if (!response.ok) {
// 아래 오류 참고
}
const data = await response.json();

リクエスト​

  • URLはmlapiのドキュメントにある絶対URL(https://mlapi.run/<api_id>/<パス>)か<api_id>/<パス>を使います。SDKはホストと#以降を捨て、パスとクエリだけを学習資料サーバーに送信します。パスが正しいかはサーバーが確認します。
  • Requestオブジェクトを渡すときは、絶対URLである必要があります。
  • AuthorizationヘッダーはSDKが現在のアクセストークンに置き換えます。メソッド・その他のヘッダー・本文・signalはそのまま送られます。
  • POSTのみ受け付け、本文は4MBまでです。

レスポンスとストリーム(SSE)​

  • レスポンスはステータスに関係なくそのまま返し、例外は投げません。fetchと同様にresponse.okで確認します。
  • 本文を変更しないため、ストリーム(SSE)のレスポンスはモデルの形式に合わせてコンテンツが読み取ります(response.body)。ストリームで使用量が必要な場合は、リクエストにstream_options: { include_usage: true }を直接入れてください。

エラー​

mlapiに送信する前にサーバーが拒否すると、サーバーのエラーJSON({ data: null, meta: { error: { code, details } } })が返ります。それ以外はmlapiのレスポンス(エラーを含む)です。

ステータスcodeタイミング
429MATERIAL_TOO_MANY_AI_REQUESTS閲覧者・資料ごとに1分あたり20回を超えた
409MATERIAL_AI_CREDIT_UNAVAILABLE使用できるクレジットがない
403MATERIAL_READ_ONLY_MODEチューターが呼び出した
400INVALID_INPUT誤ったapi_id・パス、本文が4MBを超過
401AUTHENTICATION_INVALIDトークンが無効
502MATERIAL_AI_FAILEDAI呼び出しの失敗
503SERVICE_UNAVAILABLEAIを使用できない

SDKが投げるものは以下のとおりです。

  • init()の前ならnot_initialized、セッションが終了していればsession_expired。
  • レスポンスが届かなければfetchと同様にTypeError、キャンセルするとsignalの理由で失敗します。

プレビューでは​

  • 編集ページでトークンを使って開いたプレビューも、サーバーを呼び出します。
  • トークンのないプレビュー(#preview=1・#edit=1)はトークンなしで送信し、401を受け取ります。
  • ecdk devのプレビューはmlapiを呼び出さず、503 SERVICE_UNAVAILABLEで応答します。