본문으로 건너뛰기

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

요청​

  • 주소는 mlapi 문서의 절대 주소(https://mlapi.run/<api_id>/<경로>)나 <api_id>/<경로>를 씁니다. SDK는 호스트와 # 뒤를 버리고 경로와 쿼리만 학습자료 서버로 보냅니다. 경로가 맞는지는 서버가 확인합니다.
  • Request 객체를 넘길 때는 절대 주소여야 합니다.
  • 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로 답합니다.