NULX API로 만드세요.

공유 링크와 사이트 삽입 고르기

재생 주소를 쓰기 전에 영상별 공개 플레이어 주소, 보호된 공유 링크, 지정된 사이트 배포처를 조회하세요. 두 조회 API에는 assets:read 권한이 필요합니다.

curl https://nulx.dev/api/v1/assets/<asset_id>/distribution \
  -H "X-API-Key: $NULX_API_KEY"
curl https://nulx.dev/api/v1/deliveries \
  -H "X-API-Key: $NULX_API_KEY"

사이트 배포처의 생성·수정은 계정 소유자가 대시보드에서 합니다. ?delivery=slug 삽입은 영상 범위·허용 도메인·언어·통계를 구분하지만 웹사이트를 배포하지는 않습니다. 일시정지하면 해당 삽입은 410을 반환합니다.

공개 링크는 고정 주소입니다. 보호된 공유 링크에는 PIN과 만료 기간을 둘 수 있습니다. 서명 삽입 주소에는 만료되는 서버 발급 토큰이 필요하므로 고정 삽입 코드로 저장하지 마세요. 허용 도메인은 iframe 위치만 제한합니다.

HLS 주소만 받는 외부 플레이어는 계정 소유자가 영상 → 공유 → 외부 플랫폼에 연결에서 외부 HLS 링크를 관리할 수 있습니다. 상대 플랫폼과 시청자가 재생 주소를 볼 수 있습니다.

인증

헤더 하나, 범위가 정해진 키.

/api/v1 요청에는 키를 함께 보냅니다. oEmbed는 키 없이 호출합니다. 키는 대시보드에서 만들며 필요한 범위만 담을 수 있습니다.

요청 예시

curl https://nulx.dev/api/v1/assets \
  -H "X-API-Key: $NULX_API_KEY"

사용 가능한 범위

API 키는 유료 플랜에서 제공됩니다. 무료 플랜은 키 화면을 볼 수 있지만 발급은 불가합니다.

강의 플랫폼에 연결하기

강사는 강의 사이트에서 영상을 올리고, 수강생은 그 사이트에서 시청합니다. NULX API 키는 강의 플랫폼 서버에만 보관하세요.

1. 강사가 올릴 수 있는지 확인

   플랫폼 서버가 강사 권한을 확인하고 assets:write 키로 업로드를 시작합니다. 한 번에 보낼 파일은 initiate, 큰 파일이나 이어 올리기는 initiate_multipart를 사용하세요. 고객 R2 연결을 쓰려면 storage_connection_id를 지정합니다. 유료 강의는 playback_policy를 signed로 지정하세요.

2. R2로 파일 보내기

   기본 제공 R2에는 플랫폼 서버가 발급받은 단기 주소로 파일을 전송하세요. 고객 R2의 CORS에서 강의 사이트 출처의 PUT과 업로드 요청 헤더를 허용하고 ETag 응답 헤더를 노출하면 강사 브라우저에서 직접 보낼 수 있습니다. 전송 후 NULX 완료 API를 호출해야 화질별 변환이 시작됩니다.

3. 영상이 준비되면 강의에 연결

   video.asset.ready 웹훅이나 자산 조회로 준비 완료를 확인하고, NULX 영상 ID를 해당 강사의 강의에 연결합니다. 강사별 영상 소유권은 강의 플랫폼에서 검사하세요.

4. 수강생에게만 재생 주소 발급

   재생 요청마다 플랫폼 서버가 수강 권한을 확인한 뒤 별도 playback:read 키로 재생 정보를 받아 허용된 수강생에게만 embed_url을 전달하세요. 기본 15분 토큰이 만료되면 서버에서 새 주소를 발급받아 플레이어를 다시 열어야 합니다. 새 embed_url의 t 쿼리에 이전 시청 초를 넣으면 그 위치에서 시작합니다. API 키나 원본 다운로드 주소를 브라우저에 보내지 마세요.

{"filename":"lecture.mp4","bytes_expected":73400320,"playback_policy":"signed"}

업로드·변환 상태 표시

파일 전송률은 강사 화면에서 직접 측정하세요. NULX는 video.upload.completed·video.upload.failed, video.job.queued·video.job.started·video.job.failed, video.asset.ready·video.asset.errored 웹훅으로 상태 변화를 알립니다. 작업 실패는 재시도될 수 있고 영상 오류는 이번 처리에서 재생할 수 없다는 뜻입니다. 변환 중에는 플랫폼 서버가 assets:read 키로 업로드 응답의 숫자 asset_id를 조회하면 작업 상태와 진행률을 받을 수 있습니다. 진행률은 작업자가 보고한 값이며 재시도 시 다시 낮아질 수 있습니다.

GET /api/v1/assets/<asset_id>
{"playback_status":"processing","processing_stage":"transcoding","transcoding_job":{"status":"running","progress_percent":42}}

JavaScript SDK로 R2에 업로드

아래 /lessons/42/... 주소는 강의 사이트 서버에 직접 만들 예시입니다. SDK는 그 서버에서 받은 짧은 업로드 주소로만 파일을 보내며, 브라우저에 NULX API 키를 두지 않습니다.

<script src="https://nulx.dev/player/nulx-player-dd7597fd0f3742ce.js?locale=ko"
  integrity="sha384-9sVWZ35V6gt1rYswpaB09YVGjGfA3BOvHgdZ7CLbDFy3fMEKJB3VNmRhw2319SCU" crossorigin="anonymous" async></script>
<input id="lesson-file" type="file" accept="video/*">
<p id="upload-status" role="status"></p>
<script type="module">
await customElements.whenDefined("nulx-player")
const post = async (path, body) => {
  const headers = { "Content-Type": "application/json" }
  const csrf = document.querySelector('meta[name="csrf-token"]')?.content
  if (csrf) headers["X-CSRF-Token"] = csrf
  const response = await fetch(path, {
    method: "POST", credentials: "same-origin", headers, body: JSON.stringify(body)
  })
  if (!response.ok) {
    const error = new Error("Request failed: " + response.status)
    error.status = response.status
    throw error
  }
  return response.json()
}
document.querySelector("#lesson-file").addEventListener("change", async (event) => {
  const file = event.target.files[0]
  if (!file) return
  const status = document.querySelector("#upload-status")
  try {
    await NulxSDK.uploadMultipart(file, {
      create: (file) => post("/lessons/42/uploads", { filename: file.name, bytes_expected: file.size, content_type: file.type || "application/octet-stream" }),
      signPart: ({ uploadId, partNumber, contentLength }) => post(`/lessons/42/uploads/${uploadId}/parts`, { part_number: partNumber, content_length: contentLength }),
      complete: ({ uploadId, bytesReceived, parts }) => post(`/lessons/42/uploads/${uploadId}/complete`, { bytes_received: bytesReceived, parts }),
      onProgress: ({ percent }) => { status.textContent = percent + "%" }
    })
    status.textContent = "업로드를 마쳤어요. 영상 변환이 시작됩니다."
  } catch (_error) {
    status.textContent = "영상을 올리지 못했어요. 다시 시도해 주세요."
  }
})
</script>

강의 사이트 서버는 로그인·강사 소유권·CSRF를 확인하고, NULX의 initiate_multipart에 signed 정책과 Idempotency-Key를 직접 지정하세요. 이어 sign_part와 complete_multipart를 대신 호출해 필요한 값만 브라우저에 돌려줍니다. SDK는 R2의 s3_multipart 업로드를 지원합니다. R2 CORS에 강의 사이트의 PUT과 ETag 응답 헤더가 필요합니다. 단기 업로드 주소는 브라우저에 보이므로 기록·공유하지 마세요. 업로드가 실패하면 서버에서 같은 세션으로 재개하거나 abort_multipart로 정리하세요.

수강생 플레이어 상태 받기

SDK는 위의 버전 고정·무결성 검증 스크립트에서 함께 제공됩니다. 이전에 복사한 플레이어 코드에는 SDK가 없을 수 있습니다. 강의 사이트의 로그인 세션으로 재생 정보를 요청하고, 갱신할 때는 lesson.renew()를 호출하면 이전 시청 위치에서 이어집니다.

<div id="lesson-player"></div>
<p id="lesson-status" role="status"></p>
<script type="module">
await customElements.whenDefined("nulx-player")
const host = document.querySelector("#lesson-player")
const status = document.querySelector("#lesson-status")
host.addEventListener("nulx:state", ({ detail }) => {
  // detail.state: idle, loading, ready, buffering, playing, paused, ended, error
  status.textContent = {
    loading: "영상을 불러오는 중…",
    buffering: "재생을 준비하는 중…",
    error: "영상을 재생하지 못했어요. 다시 시도해 주세요."
  }[detail.state] || ""
})
host.addEventListener("nulx:progress", ({ detail }) => {
  // detail.currentTime and detail.duration are seconds
})
const lesson = NulxSDK.player(host, async () => {
  const response = await fetch("/lessons/42/playback", { credentials: "same-origin" })
  if (!response.ok) throw new Error("Playback denied: " + response.status)
  return response.json() // { asset_id, playback_policy: "signed", embed_url }
})
try { await lesson.load() }
catch (_error) { status.textContent = "영상을 재생하지 못했어요. 다시 시도해 주세요." }
// Refresh from your backend before the token expires; watch position is kept.
// await lesson.renew()
</script>

강의 사이트 서버는 매 요청마다 수강 권한을 확인하고 별도 playback:read 키로 NULX 재생 정보를 발급받으세요. 브라우저에는 asset_id, signed playback_policy, 단기 embed_url만 보내세요. SDK는 다른 출처·공개 재생 주소를 거부하지만, 허가된 시청자가 받은 단기 주소의 복사나 화면 녹화까지 막지는 못합니다.

Cloudflare R2 CORS 설정 방법

서명 재생은 지원 플랜과 저장소의 보호 재생 설정이 필요합니다. 원본 버킷을 공개하면 보호 재생을 우회할 수 있습니다. 임베드 도메인에는 강의 사이트 주소를 등록하세요.

외부 플레이어에 시청자별 재생 주소 주기

다른 회사의 웹 플레이어(hls.js, Video.js 등)나 자체 앱이 NULX 영상을 직접 재생할 때 씁니다. 로그인한 시청자가 재생을 누를 때마다 플랫폼 서버가 playback:read 키로 주소를 새로 받아 그 시청자의 플레이어에만 넘기세요. 비공개·보호 재생 영상만 됩니다.

• 처음 재생한 곳(같은 인터넷 연결)에서만 재생돼요. 다른 곳에서 열면 막혀요.
• 영상 길이 + 30분 동안만 쓸 수 있어요 (최소 2시간, 최대 24시간).
• 다른 회사 웹사이트의 플레이어와 자체 앱 모두에서 재생돼요.
• 와이파이에서 데이터로 바뀌는 등 연결이 바뀌면 주소를 다시 받아야 해요.

POST /api/v1/playback/<asset_id>/grants
X-API-Key: <playback:read key>
{"viewer":"student-1024"}

201 {"grant_id":"0123456789abcdef","hls_url":"https://cdn.nulx.dev/_nulx_edge/grant-…/master.m3u8",
     "expires_at":"…","ttl_seconds":7200,"binding":"first_network","viewer":"student-1024"}

DELETE /api/v1/playback/<asset_id>/grants/<grant_id>

공개 영상은 422 public_video, 직접 연결한 저장소의 영상은 422 storage_unsupported로 거절됩니다. 다른 곳에서 재생하면 영상 요청이 403이 되며, 그때는 새 주소를 받으면 됩니다. 영상을 휴지통에 넣거나 재생할 수 없게 바꾸거나 키를 지우면 그 주소도 바로 멈춥니다.

oEmbed API

공개 영상 URL을 제목·썸네일·iframe 코드가 담긴 JSON으로 변환합니다. API 키 없이 호출할 수 있습니다.

oEmbed는 처리 완료된 공개 영상에서만 사용할 수 있어요. 비공개·보호 재생·공개 예정 영상과 보호 공유 링크는 지원하지 않아요.

요청 예시

curl --get https://nulx.dev/oembed \
  --data-urlencode "url=https://nulx.dev/watch/<external_id>" \
  --data-urlencode "format=json" \
  --data-urlencode "maxwidth=640"

<external_id>를 영상의 외부 ID로 바꾸세요. 영상 상세 → 공유 → 웹사이트에 영상 넣기 → 개발자용 연동 보기에서 해당 영상의 요청 주소를 복사할 수 있습니다.

요청 파라미터

url

필수. 같은 호스트의 /watch/<external_id> 또는 /embed/<external_id> URL. 쿼리 값은 URL 인코딩하세요. /s/ 보호 공유 링크와 HLS 주소는 지원하지 않습니다.

format

선택. json만 지원하며 생략해도 JSON을 반환합니다.

maxwidth

선택. 기본 너비 640px. 양의 정수는 80~1920px로 보정하며 16:9 비율로 높이를 계산합니다.

maxheight

선택. 기본 높이 360px. 양의 정수는 80~1080px로 보정하며 현재 높이보다 작으면 너비도 함께 줄입니다.

성공 응답 예시

{
  "version": "1.0",
  "type": "video",
  "provider_name": "NULX",
  "provider_url": "https://nulx.dev/",
  "title": "...",
  "author_name": "...",
  "width": 640,
  "height": 360,
  "html": "<iframe src=\"https://nulx.dev/embed/<external_id>\" width=\"640\" height=\"360\" frameborder=\"0\" allow=\"autoplay; fullscreen; picture-in-picture; encrypted-media\" allowfullscreen title=\"...\"></iframe>",
  "thumbnail_url": "https://nulx.dev/watch/<external_id>/poster"
}

포스터가 있는 영상만 thumbnail_url을 반환합니다. 공개 시청·임베드 페이지의 application/json+oembed 링크로 API를 자동 발견할 수 있으며, 실제 자동 임베드 지원 여부는 사용하는 서비스에 따라 다릅니다.

오류 응답은 본문이 비어 있습니다. 404: URL 누락·잘못된 호스트/경로·없는 영상·비공개·보호 재생·처리 중·공개 예정 영상. 501: JSON 이외의 형식. 429: IP당 분당 60회 제한 초과. 임베드 도메인 제한은 그대로 적용됩니다.

웹훅

폴링 대신 구독하세요.

대시보드나 API로 HTTPS 엔드포인트를 등록하면 수명주기 이벤트를 서명된 JSON으로 보내드립니다. 5xx·429·전송 오류는 백오프로 재시도하고, 그 외 4xx·3xx 응답은 재시도하지 않습니다.

전달 형식

POST https://your-server.example/hooks/nulx
NULX-Event: video.asset.ready
NULX-Event-Id: <event uuid>
NULX-Delivery-Id: <delivery uuid>
NULX-Timestamp: 1758432000
NULX-Signature: t=1758432000,v1=<hex hmac-sha256>

{
  "id": "<event uuid>",
  "event": "video.asset.ready",
  "created_at": "2026-09-21T04:00:00Z",
  "data": { "asset_id": "…", "title": "…", "playback_status": "ready", "playback_url": "…" }
}

서명 검증

엔드포인트 생성 시 한 번만 표시되는 secret으로 "<timestamp>.<raw body>"의 HMAC-SHA256(hex)을 계산해 v1과 비교하세요. 재전송 공격을 막으려면 5분 이상 오래된 timestamp는 거부하세요.

expected = "t=" + timestamp + ",v1=" + hex_hmac_sha256(secret, timestamp + "." + raw_body)

구독 가능한 이벤트