Note는 단일 녹음 세션을 담는 최상위 컨테이너예요. 그 내용은 세 종류의 하위 항목으로 노출돼요. Paragraphs(전사), NoteSummary(한 페이지 요약), 그리고 NoteDocument(여러 섹션으로 구성된 구조화된 리포트)예요. 이 페이지는 엔티티 간 관계를 정리하고, 무엇을 위해 어떤 API를 호출하면 되는지 알려줘요.
엔티티 관계
엔티티
Note
녹음 세션이 시작될 때(또는 오디오·텍스트를 가져올 때) 생성되는 컨테이너예요.guid 필드로 식별하며, API 경로에서는 {noteGuid}로 참조해요. 제목, 소스 타입, 녹음 길이, 협업자 같은 메타데이터를 담아요. 실제 내용은 아래 하위 항목에 들어 있어요.
Paragraph
Note 전사의 의미 단위예요. 보통 화자 발화 구간이나 주제 덩어리이며, 일반적인 산문 문단이 아니에요. 각 Paragraph는transcript, translated(번역을 요청한 경우), summary(짧은 문단 단위 요약), 그리고 타임스탬프를 담아요. 각 텍스트 필드는 { type, content } 형태의 TextObject(type은 text/plain 또는 text/markdown)이며, 전사·번역·요약이 비동기로 완료됨에 따라 단계적으로 non-null이 돼요.
NoteSummary
Note 전체를 다루는 단일 요약 텍스트 블록이에요. “한 페이지” 요약으로 보이는 것이 바로 이거예요.content 필드는 raw 문자열이 아니라 TextObject({ type, content })예요. 하나의 Note는 여러 개의 NoteSummary를 가질 수 있어요(언어나 템플릿이 다를 때). NoteDocument와 달리 섹션으로 나뉘지 않아요.
NoteDocument
여러 섹션으로 구성된 구조화된 문서예요. 예를 들면 회의록, 액션 아이템, 영업 통화 노트 같은 거예요. 어떤 섹션이 있는지 정의하는NoteDocumentTemplate으로부터 생성돼요. 각 섹션은 개별적으로 렌더링돼요. 자유 형식 요약이 아니라 템플릿 기반의 구조화된 산출물이 필요할 때 사용하세요.
NoteDocumentTemplate
NoteDocument의 섹션 구조를 정의해요. 플랫폼에서 관리하거나(isManaged: true, 예: “회의록”) 팀이 커스텀할 수 있어요. NoteDocument를 생성하기 전에 사용 가능한 템플릿을 둘러보고 적절한 형태를 고르세요.
Folder
Note를 계층적으로 정리해요. 하나의 Note는 최대 하나의 Folder에 속해요. Folder는 사용자 소유이거나 팀 소유일 수 있고, 공유 규칙이 적용돼요.어떤 API를 호출해야 하나요?
| 원하는 것… | 사용할 API |
|---|---|
| 노트의 전체 전사 | GET /v1/external/notes/{noteGuid}/paragraphs |
| 한 페이지 요약 | GET /v1/external/notes/{noteGuid}/summaries |
| 구조화된 리포트 (회의록 등) | GET /v1/external/notes/{noteGuid}/documents |
| 사용 가능한 문서 템플릿 | GET /v1/external/note-document-templates |
| 폴더 상세 정보 | GET /v1/external/teams/me/folders/{folderId} |
FAQ
“한 페이지” 요약은 어디에 있나요?NoteSummary에 있어요. GET /v1/external/notes/{noteGuid}/summaries를 호출하세요. NoteDocument는 여러 섹션으로 구성된 구조화된 리포트를 위한 것이지, 한 페이지 요약을 위한 게 아니에요.
NoteSummary와 NoteDocument 중 무엇을 써야 하나요?
- 단일 요약 텍스트 블록 →
NoteSummary. - 여러 섹션으로 구성된 구조화된 리포트(템플릿 기반) →
NoteDocument.