녹음 파일

녹음 파일 목록 보기

GET /api/v1/recordings

인증된 사용자가 액세스할 수 있는 녹음 파일의 페이지별 목록을 반환합니다.

쿼리 매개변수

매개변수	유형	기본값	설명
limit	number	20	결과 수 (1–100)
offset	number	0	페이지네이션 오프셋
search	string	-	제목으로 필터링 (부분 일치)
status	string	-	상태로 필터링 (녹음 파일 상태 참조)
date_from	string	-	ISO 8601 날짜 - 이 날짜 이후에 생성된 녹음 파일만 반환
date_to	string	-	ISO 8601 날짜 - 이 날짜 이전에 생성된 녹음 파일만 반환
organization_id	string	-	조직으로 범위 지정
folder_id	string	-	폴더로 범위 지정 (organization_id 필요)

응답

{
  "data": [
    {
      "id": "uuid",
      "status": "COMPLETED",
      "title": "주간 동기화",
      "createdAt": "2025-09-19T15:00:00.000Z",
      "thumbnailUrl": "https://...",
      "progress": 1.0,
      "capabilities": {
        "canDownload": true,
        "canShare": true,
        "canViewTranscription": true,
        "canGenerateSummary": true,
        "canAskQuestions": true
      }
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

---

녹음 파일 가져오기

GET /api/v1/recordings/:id

단일 녹음 파일에 대한 전체 세부 정보를 반환합니다.

조직 녹음 파일은 해당 파일을 볼 수 있는 권한이 있는 모든 조직 구성원에게 제공됩니다. 소유자와 관리자는 조직의 모든 녹음 파일을 열 수 있으며, 편집자와 뷰어는 자신의 역할 및 폴더 액세스 권한에 따라 녹음 파일을 볼 수 있습니다. 조직 녹음 파일의 경우 is_locked, download_url 및 capabilities는 호출자의 개인 요금제가 아닌 조직의 요금제와 구성원의 기능 플래그를 반영합니다.

조직의 엔터프라이즈 구독이 더 이상 활성화되지 않은 경우 402 ORGANIZATION_SUBSCRIPTION_EXPIRED를 반환합니다.

응답

{
  "data": {
    "id": "uuid",
    "status": "COMPLETED",
    "title": "주간 동기화",
    "createdAt": "2025-09-19T15:00:00.000Z",
    "updatedAt": "2025-09-19T15:30:00.000Z",
    "startedAt": "2025-09-19T15:01:00.000Z",
    "endedAt": "2025-09-19T15:30:00.000Z",
    "videoUrl": "https://...",
    "hlsUrl": "https://...",
    "downloadUrl": "https://...",
    "downloadUrlExpiresAt": "2025-09-19T21:00:00.000Z",
    "thumbnailUrl": "https://...",
    "organizationId": "org_uuid or null",
    "transcription": {
      "status": "completed",
      "language": "en",
      "speakers": ["화자 1", "화자 2"],
      "segmentsCount": 184,
      "duration": 1740.5
    },
    "summary": {
      "status": "completed",
      "content": "## 주요 토픽\n...",
      "topics": [
        {
          "title": "프로젝트 타임라인",
          "keyPoints": [
            { "point": "출시일 확정", "details": ["Q1로 설정"] }
          ]
        }
      ]
    },
    "isLocked": false,
    "capabilities": {
      "canDownload": true,
      "canShare": true,
      "canViewTranscription": true,
      "canStartTranscription": true,
      "canRegenerateTranscription": false,
      "canRenameSpeaker": true,
      "canViewSummary": true,
      "canGenerateSummary": true,
      "canAskQuestions": true
    }
  }
}

---

스크립트 세그먼트 가져오기

GET /api/v1/recordings/:id/transcript

녹음 파일의 페이지별 스크립트 세그먼트를 반환합니다.

조직 녹음 파일은 녹음 파일 가져오기와 동일한 액세스 규칙을 따릅니다. 녹음 파일이 잠겨 있으면 403 RECORDING_LOCKED를 반환하고, 조직 또는 구성원에 대해 스크립트 생성이 비활성화되어 있으면 403 TRANSCRIPT_NOT_AVAILABLE을 반환합니다. 아직 스크립트가 생성되지 않은 녹음 파일은 "status": "not_started" 및 빈 segments 배열과 함께 200을 반환합니다.

쿼리 매개변수

매개변수	유형	기본값	설명
start_chunk	number	0	시작할 청크 인덱스
limit	number	50	청크 수 (1–100)

응답

{
  "data": {
    "status": "completed",
    "language": "en",
    "speakers": ["화자 1", "앨리스"],
    "duration": 1740.5,
    "segments": [
      {
        "id": 1,
        "start": 0.5,
        "end": 3.2,
        "text": "모두 좋은 아침입니다.",
        "speaker": "앨리스",
        "confidence": 0.97
      }
    ],
    "pagination": {
      "total_chunks": 184,
      "has_more": true
    }
  }
}

---

녹음 파일 업데이트

PATCH /api/v1/recordings/:id

녹음 파일의 제목 또는 메모를 업데이트합니다. 하나 이상의 필드가 필요합니다.

요청 본문

{
  "title": "새 제목 (1–500자)",
  "notes": "선택 사항 메모 (최대 100,000자)"
}

응답

{
  "data": { "success": true }
}

---

녹음 파일 삭제

DELETE /api/v1/recordings/:id

녹음 파일과 모든 관련 데이터(스크립트, 요약, 공유)를 영구적으로 삭제합니다.

응답

{
  "data": { "success": true }
}

위험

삭제는 영구적이며 되돌릴 수 없습니다.

---

공유 링크 생성

POST /api/v1/recordings/:id/share-link

녹음 파일에 대한 공개 공유 링크를 생성합니다.

조직 녹음 파일의 경우, 녹음 파일을 볼 수 있는 모든 구성원이 링크를 생성할 수 있습니다. 링크는 녹음 파일 소유자를 대신하여 생성되며 조직의 요금제를 사용하므로 호출자의 개인 요금제가 무료인 경우에도 download 링크가 조직 녹음 파일에 대해 작동합니다. 녹음 파일이 잠겨 있으면 403 RECORDING_LOCKED를 반환하고, 조직 또는 구성원에 대해 공유가 비활성화되어 있으면 403 SHARING_DISABLED를 반환합니다.

요청 본문

{
  "permission": "view"
}

값	설명
view	수신자는 비디오를 시청하고 스크립트/요약에 액세스할 수 있습니다.
download	수신자는 비디오 파일을 다운로드할 수도 있습니다.

응답

{
  "data": {
    "share_url": "https://recordmeeting.com/app/shared/abc123",
    "share_token": "abc123",
    "permission": "view"
  }
}

---

녹음 파일 상태

상태	설명
STARTING	녹음 요청 수신, 설정 진행 중
CONNECTING	Google Meet 세션에 연결 중
WAIT_APPROVAL	녹음 승인을 위해 통화 중 승인 대기 중
RECORDING	활발하게 녹음 중
UPLOADING	클라이언트 측 업로드 진행 중 (청크가 스토리지로 드레이닝 중)
PROCESSING	Cloudflare Stream HLS/DASH 패키징 중 - 아직 재생 불가
MIGRATING	비디오 재생 가능; HLS가 장기 스토리지로 마이그레이션 중
COMPLETED	녹음이 완전히 처리되어 저장됨
ERROR	녹음 실패

API 소비자는 재생, 다운로드 및 공유 작업에 대해 MIGRATING을 COMPLETED와 동일하게 처리해야 합니다. 차이점은 내부적입니다.