SNS API Response Schema

Account, Post, Comment, Group, Page — 모든 SNS 플랫폼이 돌려주는 타입을 필드 하나하나.

다섯 가지 타입이 모든 SNS 오퍼레이션을 덮으며, 한 필드는 어느 플랫폼에서나 같은 뜻입니다.

선택 필드는 정말로 선택입니다. 없다는 것은 플랫폼이 말하지 않았다는 뜻입니다. metrics.likes가 없으면 숨겨진 수치이지 좋아요 0개가 아닙니다. 시각은 ISO 8601, UTC입니다. 모든 객체는 platform을 가지며, ext를 가질 수 있습니다. ext는 그 플랫폼에만 있는 사실을 그 플랫폼의 이름 그대로 담습니다.

Account

사람, 크리에이터, 채널 또는 페이지.

필드	타입	설명
`platform`	string	`reddit` `tiktok` `youtube` `instagram` `threads` `linkedin` `x`
`handle`	string	@이름, 또는 그 플랫폼에서 그에 해당하는 것
`url`	string	프로필 페이지
`id`	string?	플랫폼의 고정 id
`displayName` `bio`	string?
`avatarUrl` `bannerUrl`	string?
`verified`	boolean?
`createdAt`	string?	계정이 만들어진 시각
`counts`	object?	`{followers?, following?, posts?}`
`links`	array?	`{url, title?}` — 프로필에 걸린 링크
`private`	boolean?	비공개(보호) 계정. 승인된 팔로워만 게시물을 볼 수 있습니다
`category`	string?	계정이 스스로 고른 카테고리 이름, 표기 그대로(`Musician/Band`, `Media & News Company`)
`ext`	object?	그 플랫폼에만 있는 사실

Post

게시물, 영상, 릴스, 쇼츠, 스레드 또는 트윗.

필드	타입	설명
`id` `url`	string
`author`	AccountRef	`{platform, id?, handle?, displayName?, url?, avatarUrl?, verified?, counts?}`
`title`	string?	제목이 있는 플랫폼(Reddit, YouTube)에서
`text`	string?	본문 또는 캡션
`createdAt` `editedAt`	string?
`lang`	string?
`media`	Media[]	이미지, GIF, 영상, 임베드 — 아래 참고
`metrics`	object?	`{likes?, comments?, shares?, views?, reposts?, quotes?, saves?, liveViewers?}`
`entities`	object?	본문에서 찾은 `{mentions?, urls?, hashtags?}`
`linkPreview`	object?	`{url, title?, description?, thumbnailUrl?, domain?}`
`poll`	object?	`{options: [{text, votes?}], totalVotes?, endsAt?}`
`place`	object?	`{name, id?, lat?, lng?, address?, city?, region?, postalCode?, country?}`
`audio`	object?	`{id?, title?, artist?, url?}` — TikTok 사운드, 릴스의 오디오
`live`	boolean?	라이브 방송
`broadcast`	object?	`{status, scheduledAt?, startedAt?, endedAt?}` — 방송의 진행 상태. `status`는 `scheduled`, `live`, `ended` 중 하나
`repostOf` `quoteOf`	Post?	이 게시물이 리포스트하거나 인용한 게시물
`inReplyTo`	object?	`{id, url?, author?}` — 이 게시물이 답글로 단 게시물
`sponsored`	boolean?	유료 광고 또는 브랜디드 콘텐츠 게시물
`pinned`	boolean?	작성자가 프로필 맨 위에 고정한 게시물
`aiGenerated`	boolean?	플랫폼이 AI 생성 콘텐츠로 표시한 게시물
`sensitive`	boolean?	플랫폼이 민감한 콘텐츠(NSFW)로 표시한 게시물
`ext`	object?	그 플랫폼에만 있는 사실

views로 무엇을 세는지는 플랫폼마다 다릅니다. TikTok과 YouTube는 재생 수, X는 노출 수를 보고합니다. Reddit의 score는 좋아요가 아니므로 metrics.likes가 아니라 ext에 있습니다. shares는 공유·보내기만 셉니다. 리포스트와 인용은 각각 reposts와 quotes로 따로 세고, saves는 북마크(저장) 수입니다. liveViewers는 지금 방송을 보고 있는 사람 수라서 broadcast.status가 live일 때만 옵니다.

true/false 플래그(sponsored, pinned, aiGenerated, sensitive, byAuthor 등)도 수치와 같은 규칙을 따릅니다. 없으면 플랫폼이 말하지 않았다는 뜻입니다.

Media

필드	타입	설명
`type`	`image` \| `gif` \| `video` \| `embed`
`url`	string
`width` `height`	number?
`thumbnailUrl`	string?
`durationSec`	number?
`variants`	array?	다른 해상도·비트레이트: `{url, width?, height?, bitrate?, contentType?}`
`altText` `caption`	string?

Comment

필드	타입	설명
`id` `postId`	string
`parentId`	string?	이 댓글이 답하는 댓글
`author`	AccountRef
`text`	string
`createdAt` `editedAt` `lang`	string?
`pinned`	boolean?
`byAuthor`	boolean?	게시물 작성자가 단 댓글
`likedByAuthor`	boolean?	게시물 작성자가 좋아요(하트)를 누른 댓글
`metrics`	object?	`{likes?, replies?}`
`media`	Media[]?
`replies`	Comment[]	이 댓글과 함께 온 답글
`moreReplies`	object?	`{count?, ids?, cursor?}` — 불러오지 않고 남은 것. `comments`로 불러오세요: `comment=`에 cursor(YouTube)나 댓글 `id`(Reddit, TikTok), 또는 Reddit의 `ids`

Group

게시물이 모이는 모든 곳.

필드	타입	설명
`kind`	string	`community` `channel` `company` `hashtag` `sound` `topic` `location` `list`
`id` `name` `url`	string
`description`	string?
`avatarUrl` `bannerUrl`	string?
`createdAt`	string?
`counts`	object?	`{members?, posts?}`
`sensitive`	boolean?	플랫폼이 민감한 그룹(NSFW)으로 표시한 경우

Page

모든 목록.

{ "platform": "tiktok", "items": [ /* Post, Comment, Account or Group */ ], "cursor": "…", "total": 1640 }

다음 페이지는 같은 오퍼레이션을 cursor만 넣어 호출하세요. cursor가 없으면 마지막 페이지입니다.

total이 있으면 목록 전체의 항목 수이며, 플랫폼이 밝힌 값 그대로입니다. 플랫폼이 정확한 수를 주지 않으면 빠집니다. 모든 항목을 끝까지 받을 수 있다는 약속은 아닙니다. 플랫폼마다 페이지를 넘길 수 있는 깊이에 한도가 있고, 목록은 cursor가 끝나는 곳에서 끝납니다.

댓글 페이지에는 ext.post(댓글이 달린 게시물)와 ext.more(플랫폼이 불러오지 않은 최상위 댓글)가 함께 올 수 있습니다 — Reddit은 둘 다 돌려줍니다.

Response Schema