Skip to main content

AI calls (mlapi)

sdk.mlapi.fetch is the same function as fetch. Take the example code from the mlapi documentation as is and replace only fetch with sdk.mlapi.fetch; the learning material server then attaches the viewer's own key, sends the request to mlapi, and returns the response unchanged. Do not put API keys in the content.

No personal information

Do not put learners' personal information (name · contact details · student id, etc.) in the request body (prompt). The body is sent to an external AI model. If you send text written by learners, show a notice such as "Do not enter personal information" near the input field.

// 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();

Requests​

  • Use the absolute URL from the mlapi documentation (https://mlapi.run/<api_id>/<path>) or <api_id>/<path>. The SDK drops the host and everything after # and sends only the path and query to the learning material server. The server checks whether the path is valid.
  • When passing a Request object, it must have an absolute URL.
  • The SDK replaces the Authorization header with the current access token. The method, other headers, body, and signal are passed through as is.
  • Only POST is accepted, and the body can be up to 4MB.

Responses and streams (SSE)​

  • The response is returned as is regardless of status and never throws. Check response.ok as with fetch.
  • Since the body is not modified, the content reads stream (SSE) responses according to the model's format (response.body). If you need usage in a stream, add stream_options: { include_usage: true } to the request yourself.

Errors​

If the server rejects the request before sending it to mlapi, a server error JSON ({ data: null, meta: { error: { code, details } } }) is returned. Everything else is mlapi's response (including errors).

StatuscodeWhen
429MATERIAL_TOO_MANY_AI_REQUESTSMore than 20 calls per minute per viewer and material
409MATERIAL_AI_CREDIT_UNAVAILABLENo credits available
403MATERIAL_READ_ONLY_MODECalled by a tutor
400INVALID_INPUTInvalid api_id · path, body over 4MB
401AUTHENTICATION_INVALIDThe token is invalid
502MATERIAL_AI_FAILEDThe AI call failed
503SERVICE_UNAVAILABLEAI is not available

The SDK throws the following.

  • not_initialized before init(), and session_expired if the session has ended.
  • If no response arrives, it fails with TypeError like fetch; if cancelled, it fails with the signal's reason.

In previews​

  • Previews opened with a token on the edit page also call the server.
  • Previews without a token (#preview=1 · #edit=1) send the request without a token and receive 401.
  • The ecdk dev preview does not call mlapi and answers with 503 SERVICE_UNAVAILABLE.