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.
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
Requestobject, it must have an absolute URL. - The SDK replaces the
Authorizationheader with the current access token. The method, other headers, body, andsignalare 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.okas withfetch. - 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, addstream_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).
| Status | code | When |
|---|---|---|
| 429 | MATERIAL_TOO_MANY_AI_REQUESTS | More than 20 calls per minute per viewer and material |
| 409 | MATERIAL_AI_CREDIT_UNAVAILABLE | No credits available |
| 403 | MATERIAL_READ_ONLY_MODE | Called by a tutor |
| 400 | INVALID_INPUT | Invalid api_id · path, body over 4MB |
| 401 | AUTHENTICATION_INVALID | The token is invalid |
| 502 | MATERIAL_AI_FAILED | The AI call failed |
| 503 | SERVICE_UNAVAILABLE | AI is not available |
The SDK throws the following.
not_initializedbeforeinit(), andsession_expiredif the session has ended.- If no response arrives, it fails with
TypeErrorlikefetch; 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 devpreview does not call mlapi and answers with 503SERVICE_UNAVAILABLE.