ScreenApp API 문서 v2.0.0

ScreenApp의 API를 사용하면 비디오 및 오디오 콘텐츠를 자동으로 트랜스크립션, 요약 및 분석할 수 있습니다. 고객 통화, 교육 비디오 및 회의 녹음을 대규모로 처리하려는 기업에 적합합니다.

주요 사용 사례

자동 트랜스크립션 및 요약: 모든 비디오 또는 오디오를 검색 가능한 텍스트 및 간결한 요약으로 변환합니다. 고객 서비스 팀, 교육 기관 및 콘텐츠 제작자에게 이상적입니다.
지식 관리: 자동 트랜스크립트, 요약 및 AI 기반 인사이트를 통해 검색 가능한 비디오 콘텐츠 저장소를 구축합니다. 교육 자료 및 회사 지식 기반에 적합합니다.
실시간 처리: 녹음이 처리되는 즉시 웹훅을 통해 트랜스크립트 및 요약을 받습니다. CRM 시스템 및 고객 서비스 플랫폼과 통합하는 데 적합합니다.
내장된 녹음: 화면 및 오디오 캡처를 모두 처리하는 임베디드 레코더를 사용하여 애플리케이션에 전문가 수준의 녹음 기능을 추가합니다.

✨ 인기 있는 사용 사례: 고객 서비스 팀은 API를 사용하여 지원 통화를 자동으로 트랜스크립션하고 요약을 생성한 다음 웹훅을 통해 CRM에 동기화합니다.

대시보드에서 API 자격 증명 가져오기 →

요금제 요구 사항 및 API 액세스

ScreenApp API를 사용하려면 다음이 필요합니다.

활성 비즈니스 요금제 구독
ScreenApp 대시보드의 API 자격 증명

API 자격 증명 가져오기

ScreenApp 계정에 로그인합니다.
설정 → 통합으로 이동합니다.
여기에서 다음을 찾을 수 있습니다.
- API 토큰
- 팀 ID

이러한 자격 증명을 안전하게 보관하고 공개적으로 공유하지 마십시오.

빠른 시작

바로 시작하고 싶으십니까? 다음 단계에 따라 ScreenApp을 웹사이트에 통합하십시오.

1. 플러그인 설치

다음 코드를 웹사이트의 HTML에 추가합니다.

<script>
  // 여기에 플러그인 설치 코드
</script>

2. 트리거 버튼 추가

페이지에 버튼 또는 트리거 요소를 추가합니다.

<button onclick="loadScreenApp()">녹음 시작</button>

3. 콜백 구성

녹음 완료를 처리하도록 콜백 함수를 사용자 정의합니다.

function callback({ id, url }) {
  // 예: 백엔드로 보내기
  fetch('/api/recordings', {
    method: 'POST',
    body: JSON.stringify({ recordingId: id, recordingUrl: url })
  });
  
  // 예: UI 업데이트
  document.getElementById('status').innerHTML = 
    `녹음이 저장되었습니다! ${url}에서 확인하세요.`;
}

인증

모든 API 요청에는 인증이 필요합니다. ScreenApp은 팀별 식별자와 함께 토큰 기반 인증을 사용합니다.

필요한 자격 증명

API 토큰: 비밀 API 키
팀 ID: 고유한 팀 식별자

인증 예제

curl -X POST "https://api.screenapp.io/v2/files/upload" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID"

인증 엔드포인트

`GET /auth/google`

인증을 위해 Google로 리디렉션합니다.

쿼리 매개변수:

redirectUrl - 인증 성공 후 사용자를 리디렉션할 인코딩된 URL
referrerUrl - 인코딩된 Referrer URL
intent - 사용자의 의도 (예: “가입”)

`GET /auth/facebook`

인증을 위해 Facebook으로 리디렉션합니다.

쿼리 매개변수:

redirectUrl - 인증 성공 후 사용자를 리디렉션할 인코딩된 URL
referrerUrl - 인코딩된 Referrer URL
intent - 사용자의 의도 (예: “가입”)

핵심 개념

특정 엔드포인트에 들어가기 전에 ScreenApp의 핵심 개념을 이해해 보겠습니다.

녹음: 업로드 및 처리할 수 있는 비디오 및 오디오 캡처
팀: 녹음을 공유하고 관리할 수 있는 그룹
웹훅: 녹음 이벤트 및 처리 결과에 대한 실시간 알림
태그: 녹음, 팀 또는 사용자 프로필에 첨부할 수 있는 메타데이터

API 참조

팀 관리

`POST /team/{teamId}/tag`

팀에 태그 추가

경로 매개변수:

teamId - 팀 ID

요청 본문:

{
  "key": "color",
  "value": "red"
}

`DELETE /team/{teamId}/tag`

팀에서 태그 제거

경로 매개변수:

teamId - 팀 ID

요청 본문:

{
  "key": "color"
}

팀 웹훅 통합

`POST /team/{teamId}/integrations/webhook`

팀에 대한 새 웹훅 URL 등록

경로 매개변수:

teamId - 팀 ID

요청 본문:

{
  "url": "https://example.com/webhook",
  "name": "내 웹훅"
}

응답:

200 - 웹훅이 성공적으로 등록되었습니다.
400 - 잘못된 요청 본문
500 - 내부 서버 오류

`DELETE /team/{teamId}/integrations/webhook`

팀에 대한 웹훅 URL 등록 취소

경로 매개변수:

teamId - 팀 ID

쿼리 매개변수:

url - 등록 취소할 웹훅 URL

응답:

200 - 웹훅이 성공적으로 등록 취소되었습니다.
400 - 잘못된 요청
404 - 웹훅 URL을 찾을 수 없음
500 - 내부 서버 오류

`GET /team/{teamId}/integrations/zapier/sample/list`

Zapier에 대한 샘플 데이터를 배열로 가져옵니다.

경로 매개변수:

teamId - 팀 ID

응답:

200 - 샘플 데이터를 성공적으로 검색했습니다.
404 - 샘플 파일을 찾을 수 없음

사용자 통합

`POST /integrations/webhook`

사용자에 대한 새 웹훅 등록

요청 본문:

{
  "url": "https://example.com/webhook",
  "name": "내 웹훅"
}

응답:

200 - 웹훅이 성공적으로 등록되었습니다.
400 - 잘못된 요청 본문

`DELETE /integrations/webhook`

사용자에 대한 웹훅 등록 취소

쿼리 매개변수:

url - 등록 취소할 웹훅 URL

응답:

200 - 웹훅이 성공적으로 등록 취소되었습니다.
400 - 잘못된 요청
404 - 웹훅 URL을 찾을 수 없음

웹훅 이벤트

웹훅 엔드포인트는 다음 형식으로 이벤트를 수신합니다.

{
  "event": "recording.completed",
  "fileId": "file789",
  "teamId": "team123",
  "data": {
    "url": "https://screenapp.io/recording/file789",
    "duration": 300,
    "status": "processed"
  }
}

일반적인 이벤트는 다음과 같습니다.

recording.started
recording.completed
recording.processed
recording.failed

파일 관리

`POST /files/{fileId}/tag`

파일에 태그 추가

경로 매개변수:

fileId - 파일 ID

요청 본문:

{
  "key": "color",
  "value": "red"
}

`DELETE /files/{fileId}/tag`

파일에서 태그 제거

경로 매개변수:

fileId - 파일 ID

요청 본문:

{
  "key": "color"
}

`POST /files/{fileId}/ask/multimodal`

여러 AI 모델을 사용하여 파일에 대한 질문하기

경로 매개변수:

fileId - 분석할 파일 ID

요청 본문:

{
  "promptText": "논의된 주요 사항은 무엇입니까?",
  "mediaAnalysisOptions": {
    "transcript": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "video": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "screenshots": {
      "timestamps": [30, 60, 90]
    }
  }
}

응답:

200 - 질문을 성공적으로 처리했습니다.
403 - AI 사용량 제한 초과
500 - 서버 오류

파일 업로드

`POST /files/upload/{teamId}/{folderId}/url`

파일 업로드를 위한 사전 서명된 URL 생성

경로 매개변수:

teamId - 팀 ID
folderId - 폴더 ID

요청 본문:

{
  "files": [
    {
      "contentType": "video/mp4",
      "name": "meeting-recording.mp4"
    }
  ]
}

응답:

200 - 업로드 URL이 성공적으로 생성되었습니다.
400 - 잘못된 요청 매개변수
500 - 서버 오류

`POST /files/upload/{teamId}/{folderId}/finalize`

업로드된 파일 완료

경로 매개변수:

teamId - 팀 ID
folderId - 폴더 ID

요청 본문:

{
  "file": {
    "fileId": "file123",
    "contentType": "video/mp4",
    "name": "영업 통화",
    "description": "고객과의 주간 영업 통화",
    "recorderName": "John Doe",
    "recorderEmail": "[email protected]"
  }
}

응답:

200 - 파일 업로드가 성공적으로 완료되었습니다.
400 - 잘못된 요청 매개변수
403 - 업로드 제한 초과
500 - 서버 오류

멀티파트 업로드 (대용량 파일용)

`PUT /files/upload/multipart/init/{teamId}/{folderId}`

대용량 파일에 대한 멀티파트 업로드 초기화

경로 매개변수:

teamId - 팀 ID
folderId - 폴더 ID

요청 본문:

{
  "contentType": "video/mp4"
}

응답:

200 - 업로드가 성공적으로 초기화되었습니다.
400 - 잘못된 요청 매개변수
500 - 서버 오류

응답 예제:

{
  "success": true,
  "data": {
    "fileId": "file789",
    "uploadId": "upload123"
  }
}

`PUT /files/upload/multipart/url/{teamId}/{folderId}/{fileId}/{uploadId}/{partNumber}`

특정 파트에 대한 업로드 URL 가져오기

경로 매개변수:

teamId - 팀 ID
folderId - 폴더 ID
fileId - 업로드 중인 파일 ID
uploadId - 멀티파트 업로드 세션 ID
partNumber - 파트 번호 (1-10000)

요청 본문:

{
  "contentType": "video/mp4"
}

응답:

200 - 업로드 URL이 성공적으로 생성되었습니다.
400 - 잘못된 요청 매개변수
500 - 서버 오류

응답 예제:

{
  "success": true,
  "data": {
    "uploadUrl": "https://presigned-s3-url.com/part1"
  }
}

`PUT /files/upload/multipart/finalize/{teamId}/{folderId}/{fileId}/{uploadId}`

멀티파트 업로드 완료

경로 매개변수:

teamId - 팀 ID
folderId - 폴더 ID
fileId - 업로드 중인 파일 ID
uploadId - 멀티파트 업로드 세션 ID

요청 본문:

{
  "file": {
    "contentType": "video/mp4",
    "recorderName": "John Doe",
    "recorderEmail": "[email protected]",
    "name": "내 녹음",
    "description": "녹음된 비디오 세션",
    "notes": [
      {
        "text": "논의된 중요한 사항",
        "timestamp": 1234567890
      }
    ]
  }
}

응답:

200 - 업로드가 성공적으로 완료되었습니다.
400 - 잘못된 요청 매개변수
404 - 활성 업로드를 찾을 수 없음
500 - 서버 오류

`PUT /files/upload/multipart/fallback/{teamId}/{folderId}/{fileId}/{partNumber}`

백엔드를 통해 파일 파트 업로드 (폴백)

경로 매개변수:

teamId - 팀 ID
folderId - 폴더 ID
fileId - 업로드 중인 파일 ID
partNumber - 파트 번호 (1-10000)

폼 데이터:

file - 업로드할 파일 파트
contentType - 업로드 중인 파일의 MIME 유형

응답:

200 - 파트가 성공적으로 업로드되었습니다.
400 - 잘못된 요청 매개변수
500 - 서버 오류

계정 관리

`POST /v2/account/tag`

인증된 사용자에게 태그 추가

요청 본문:

{
  "key": "color",
  "value": "red"
}

응답:

200 - 태그가 성공적으로 추가되었습니다.
400 - 잘못된 요청 매개변수

`PUT /account/profile`

인증된 사용자의 프로필 업데이트

요청 본문:

{
  "firstName": "John",
  "lastName": "Doe",
  "name": "John Doe",
  "gender": "male",
  "userType": "user",
  "company": "Acme Inc",
  "role": "Developer",
  "goals": "새로운 기술 배우기",
  "phoneNumber": "+1234567890",
  "location": "San Francisco, CA",
  "website": "https://example.com",
  "picture": "https://example.com/avatar.jpg",
  "provider": "local",
  "providerId": "12345",
  "primaryField": "development"
}

응답:

200 - 프로필이 성공적으로 업데이트되었습니다.
400 - 잘못된 요청 매개변수

고급 기능

AI 분석

AI를 사용하여 녹음을 분석하여 통찰력을 얻으십시오.

// 녹음에 대한 AI 분석 요청
const analysis = await fetch(`/v2/files/${fileId}/ask/multimodal`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptText: "논의된 주요 요점은 무엇입니까?",
    mediaAnalysisOptions: {
      transcript: {
        segments: [{ start: 0, end: 300 }]
      },
      video: {
        segments: [{ start: 0, end: 300 }]
      }
    }
  })
});

일괄 처리

여러 녹음을 효율적으로 관리합니다.

// 여러 녹음에 태그 지정
async function batchTag(fileIds, tag) {
  const promises = fileIds.map(fileId => 
    fetch(`/v2/files/${fileId}/tag`, {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(tag)
    })
  );
  await Promise.all(promises);
}

오류 처리

일반적인 오류 코드

400: 잘못된 요청 매개변수
403: AI 사용량 제한 초과 또는 무단 액세스
404: 리소스를 찾을 수 없음
500: 서버 오류

오류 응답 형식

오류 응답은 일반적으로 다음 형식을 따릅니다.

{
  "success": false,
  "message": "자세한 오류 메시지"
}

예제

팀 웹훅 설정

웹훅을 사용하면 녹음이 처리될 때 실시간 업데이트를 받을 수 있습니다.

// 팀에 대한 새 웹훅 등록
async function registerTeamWebhook(teamId, webhookUrl, webhookName) {
  const response = await fetch(`/v2/team/${teamId}/integrations/webhook`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: webhookUrl,
      name: webhookName
    })
  });
  return await response.json();
}

// 사용 예
const result = await registerTeamWebhook(
  'team123',
  'https://your-domain.com/webhooks/screenapp',
  '녹음 업데이트'
);

대용량 파일 업로드 및 처리

100MB보다 큰 파일의 경우 멀티파트 업로드 흐름을 사용하십시오.

// 1. 업로드 초기화
const initResponse = await fetch(`/v2/files/upload/multipart/init/${teamId}/${folderId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    contentType: 'video/mp4'
  })
});

const { data: { fileId, uploadId } } = await initResponse.json();

// 2. 파일을 청크로 분할하고 각 파트 업로드
const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB 청크
const totalParts = Math.ceil(file.size / CHUNK_SIZE);

for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
  // 이 파트에 대한 업로드 URL 가져오기
  const urlResponse = await fetch(
    `/v2/files/upload/multipart/url/${teamId}/${folderId}/${fileId}/${uploadId}/${partNumber}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        contentType: 'video/mp4'
      })
    }
  );
  
  const { data: { uploadUrl } } = await urlResponse.json();
  
  // 파일에서 청크 생성
  const start = (partNumber - 1) * CHUNK_SIZE;
  const end = Math.min(start + CHUNK_SIZE, file.size);
  const chunk = file.slice(start, end);
  
  // 청크를 S3에 직접 업로드
  await fetch(uploadUrl, {
    method: 'PUT',
    body: chunk,
    headers: {
      'Content-Type': 'video/mp4'
    }
  });
}

// 3. 업로드 완료
const finalizeResponse = await fetch(
  `/v2/files/upload/multipart/finalize/${teamId}/${folderId}/${fileId}/${uploadId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      file: {
        contentType: 'video/mp4',
        name: '고객 회의 녹음',
        description: '클라이언트와의 분기별 검토',
        recorderName: 'Jane Smith',
        recorderEmail: '[email protected]'
      }
    })
  }
);

대시보드에서 API 자격 증명 가져오기 →

ScreenApp API 문서 v2.0.0

주요 사용 사례

요금제 요구 사항 및 API 액세스

API 자격 증명 가져오기

빠른 시작

1. 플러그인 설치

2. 트리거 버튼 추가

3. 콜백 구성

인증

필요한 자격 증명

인증 예제

인증 엔드포인트

GET /auth/google

GET /auth/facebook

핵심 개념

API 참조

팀 관리

POST /team/{teamId}/tag

DELETE /team/{teamId}/tag

팀 웹훅 통합

POST /team/{teamId}/integrations/webhook

DELETE /team/{teamId}/integrations/webhook

GET /team/{teamId}/integrations/zapier/sample/list

사용자 통합

POST /integrations/webhook

DELETE /integrations/webhook

웹훅 이벤트

파일 관리

POST /files/{fileId}/tag

DELETE /files/{fileId}/tag

POST /files/{fileId}/ask/multimodal

파일 업로드

POST /files/upload/{teamId}/{folderId}/url

POST /files/upload/{teamId}/{folderId}/finalize

멀티파트 업로드 (대용량 파일용)

PUT /files/upload/multipart/init/{teamId}/{folderId}

PUT /files/upload/multipart/url/{teamId}/{folderId}/{fileId}/{uploadId}/{partNumber}

PUT /files/upload/multipart/finalize/{teamId}/{folderId}/{fileId}/{uploadId}

PUT /files/upload/multipart/fallback/{teamId}/{folderId}/{fileId}/{partNumber}

계정 관리

POST /v2/account/tag

PUT /account/profile

고급 기능

AI 분석

일괄 처리

오류 처리

일반적인 오류 코드

오류 응답 형식

예제

팀 웹훅 설정

대용량 파일 업로드 및 처리

We value your privacy

`GET /auth/google`

`GET /auth/facebook`

`POST /team/{teamId}/tag`

`DELETE /team/{teamId}/tag`

`POST /team/{teamId}/integrations/webhook`

`DELETE /team/{teamId}/integrations/webhook`

`GET /team/{teamId}/integrations/zapier/sample/list`

`POST /integrations/webhook`

`DELETE /integrations/webhook`

`POST /files/{fileId}/tag`

`DELETE /files/{fileId}/tag`

`POST /files/{fileId}/ask/multimodal`

`POST /files/upload/{teamId}/{folderId}/url`

`POST /files/upload/{teamId}/{folderId}/finalize`

`PUT /files/upload/multipart/init/{teamId}/{folderId}`

`PUT /files/upload/multipart/url/{teamId}/{folderId}/{fileId}/{uploadId}/{partNumber}`

`PUT /files/upload/multipart/finalize/{teamId}/{folderId}/{fileId}/{uploadId}`

`PUT /files/upload/multipart/fallback/{teamId}/{folderId}/{fileId}/{partNumber}`

`POST /v2/account/tag`

`PUT /account/profile`