자람AI 연동 API

업체 시스템이 우리 영상·자막·문항·질의응답을 가져가는 규격입니다.

기본 주소	http://api.jaram.co.kr/api/v1
경로	아래 표기는 모두 이 기본 주소 뒤에 붙습니다 — 예: `/api/v1/videos`
형식	요청·응답 모두 JSON (UTF-8). 자막만 `srt`·`vtt` 로도 받습니다.
인증	`X-API-Key` 헤더 한 장
요금	조회는 과금하지 않습니다. 부를 때마다 AI 가 도는 `/api/v1/ask` 만 토큰을 씁니다.

인증

발급받은 키를 헤더에 넣습니다. 키가 없거나 틀리면 401 입니다.

curl -H "X-API-Key: 발급받은키" http://api.jaram.co.kr/api/v1/categories

키는 곧 신원입니다. 브라우저(자바스크립트)에서 직접 부르면 키가 그대로 노출됩니다. 업체 서버에서 호출하시고, 키가 새어 나갔다고 판단되면 바로 알려 주세요 — 재발급해 드립니다.

공통 규약

증분 조회 — 바뀐 것만 가져갑니다

목록형 조회는 모두 같은 규칙입니다. 처음에는 since 로 시작하고, 그 다음부터는 응답이 준 next_cursor 를 그대로 넣으면 됩니다.

파라미터	설명
since	이 시각 이후 것만 (예: `2026-08-01T00:00:00Z`)
cursor	지난 응답의 `next_cursor`. `since` 보다 우선합니다
limit	한 번에 받을 개수. 기본 100, 최대 500

커서를 그대로 보관하세요. 시각만으로 이어받으면 같은 초에 들어온 자료가 페이지 경계에서 누락될 수 있습니다. 커서는 (시각, 번호) 를 함께 담고 있어 그 구멍을 막습니다. 받은 것이 0건이어도 커서는 돌려드리니 그대로 저장해 두시면 됩니다.

{
  "items": [ ... ],
  "next_cursor": "MjAyNi0wOC0xNiAxMDoxMjozM3wxNDIx",
  "has_more": true
}

호출 제한

업체별로 셉니다 — 조회 분당 60회, 질의응답 분당 30회. 넘기면 429 입니다.

영상을 가리키는 방법

영상 하나를 지정하는 자리({video})에는 우리 번호와 업체 관리번호 어느 쪽을 넣어도 됩니다. 등록하실 때 관리번호를 함께 주시면 그 값으로 조회할 수 있습니다.

질의응답

GET/api/v1/categories

질문을 걸 수 있는 분류(과목·강좌) 목록입니다. /api/v1/ask 의 category_id 가 여기서 나옵니다.

POST/api/v1/ask

분류에 매달린 자료·자막·게시물 세 갈래에서 근거를 찾아 답합니다.

본문	설명
question	필수 · 2~2,000자
category_id	필수 · `/api/v1/categories` 의 번호
k	근거 건수(생략 가능)

curl -X POST http://api.jaram.co.kr/api/v1/ask \
  -H "X-API-Key: 발급받은키" -H "Content-Type: application/json" \
  -d '{"question":"주주총회 소집 통지 기한은?","category_id":12}'

{
  "found": true,
  "answer": "...",
  "category": { "id": 12, "name": "상법", "path": "..." },
  "sources": [ { "cite": "[자료 3]", "text": "..." } ],
  "usage": { "tokens": 1840 }
}

근거가 없으면 지어내지 않습니다. 찾지 못하면 found:false 로 답하고 토큰도 쓰지 않습니다(AI 를 부르지 않으므로). sources[].cite 는 답변 본문의 인용 표시와 문자까지 같으니 그대로 대조하시면 됩니다.

자료 조회

모두 무과금이고, 위의 증분 규칙(since·cursor·limit)을 공통으로 받습니다.

엔드포인트	주는 것 / 추가 파라미터
GET/api/v1/videos	영상 목록 · `category`, `status`(`encoded`·`subtitled`·`summarized`)
GET/api/v1/videos/{video}	영상 한 건
GET/api/v1/videos/{video}/subtitle	자막 · `format`=`json`(기본)·`srt`·`vtt`
GET/api/v1/videos/{video}/summary	강의 요약
GET/api/v1/subtitles	자막 목록(증분) · `category`
GET/api/v1/quiz	문항 · `video`, `category` — 사람이 승인한 문항만 나갑니다
GET/api/v1/chat-logs	질의 기록 · `category`, `found`, `origin`
GET/api/v1/board	게시물 Q&A · `category`, `answered`, `q`

계약한 상품만 열립니다. 자막을 계약하지 않았다면 자막 조회는 403 입니다. 또한 업체 자료만 보입니다 — 남의 분류·영상 번호를 넣으면 404 입니다.

영상 수신

POST/api/v1/ingest/{token}

업체 시스템에 새 영상이 생겼을 때 알려 주는 자리입니다. 토큰은 수신 경로마다 따로 발급하며, 이 엔드포인트는 X-API-Key 대신 그 토큰으로 신원을 확인합니다. 받은 영상은 계약한 단계(인코딩 → 자막 → 문제)까지 자동으로 진행됩니다.

오류

코드	뜻	대처
`401`	키가 없거나 틀림	`X-API-Key` 확인
`403`	계약하지 않은 상품	계약 범위 확인
`404`	없는 자료 · 남의 자료	번호·분류 확인
`422`	파라미터가 틀림 · 커서가 깨짐	응답의 `message` 를 그대로 읽으면 됩니다
`429`	호출 제한 · 월 한도 초과	잠시 뒤 재시도

문의는 담당자에게 주세요. 이 문서는 실제 서비스 중인 규격과 함께 갱신됩니다.