TikTok 크리에이터 데이터 API: 프로필과 동영상 샘플로 1차 선별하기

TikTok 크리에이터 목록을 검토할 때는 보통 팔로워 수로 정렬하는 데서 시작합니다. 하지만 팔로워가 많다고 최근 동영상 성과가 안정적인 것은 아니며, 동영상 하나가 크게 화제가 되었다고 모든 콘텐츠의 성과가 꾸준하다는 뜻도 아닙니다. 데이터셋에 사용자 이름, 팔로워 수, 정의가 모호한 참여율만 있다면 그 목록은 검증하기 어렵고 섭외 대상으로 평가하기도 어렵습니다.

TikTok 크리에이터 데이터 API를 사용하면 근거에 기반해 선별할 수 있습니다. 먼저 계정 식별자와 프로필 정보를 확인하고, 범위가 명확한 동영상 샘플을 가져온 다음, 콘텐츠 적합성 판단과 수동 검토를 함께 진행합니다. 이 가이드는 EveryInfra의 profile 및 user_videos 엔드포인트로 이 워크플로를 실행하며, 공개 참여 데이터를 매출, 구매자 페르소나, ROI 예측으로 확장하지 않습니다.

파라미터와 필드 정의는 2026-09-04 기준 공개 디렉터리와 소스 코드로 검증했습니다. 아래 요청은 권한이 확인된 상황에 맞춰 수정해 쓰는 템플릿이며, 이번 작업에서는 실제 계정으로 호출하지 않았습니다. 계산 예시는 합성 데이터를 사용합니다.

공식 승인 기반 표시와 데이터 조회 구분하기

TikTok 공식 Display API는 사용자 정보, 동영상 목록, ID 기반 동영상 조회 등 크리에이터 프로필과 동영상을 제공하며, 앱 신청과 사용자 승인 절차를 거쳐야 합니다. 공식 문서에는 user.info.basic 및 video.list 권한이 명시되어 있습니다. 사용자가 자신의 TikTok 계정을 연결하는 경우라면 이 공식 연동 경로부터 시작하십시오.

EveryInfra의 platform/action/params는 별도의 요청 방식입니다. 공식 Display API와는 다르며, 공식 액세스 토큰을 재사용하지 않고, 이 문서에서 공식 문서를 참조한다고 해서 플랫폼의 보증을 받는 것도 아닙니다. 각 경로의 권한, 필드, 커버리지를 따로 평가하십시오.

이 가이드는 프로필과 계정 동영상 샘플만 다룹니다. 댓글, 해시태그, 상품, 마켓플레이스 기능에는 별도의 액션이 필요합니다. 프로필 객체에서 상품 판매량을 도출하거나 상품 검색의 지역 필터를 크리에이터 국적으로 취급하지 마십시오. 먼저 조사 범위를 좁혀 필요한 필드를 파악하십시오.

1단계: 조사 작업을 서로 다른 두 번의 조회로 나누기

profile 엔드포인트는 공개 프로필 정보를, user_videos는 해당 계정의 동영상 레코드를 반환합니다. 둘 다 username을 받지만 응답 구조가 다릅니다. 전자는 객체를, 후자는 배열을 반환합니다. 따라서 action 파라미터만 바꿔서 같은 파싱 로직을 쓸 수는 없습니다.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=tiktok' \
  | jq '.capabilities[]
    | select(.action == "profile" or .action == "user_videos")
    | {action, required_params, optional_params, param_meanings,
       mode, returns_list, default_limit, max_limit, response_fields}'

이 디렉터리에서 두 엔드포인트는 모두 username이 필수이며 sync 모드를 사용합니다. user_videos는 기본 10개, 최대 50개 항목을 반환하며, profile은 단일 객체라 목록 개수 제한이 없습니다. username은 표시 닉네임, 전체 프로필 URL, 내부 ID가 아니라 계정 핸들을 의미합니다. 예시는 현재 공개 디렉터리에 맞춰 @ 기호 없이 핸들을 사용합니다.

요청에는 사용자 이름을 쓰고, 장기적인 연결에는 안정적인 계정 ID를 씁니다. 핸들이 바뀌었다고 새 핸들을 완전히 새로운 크리에이터로 취급하지 말되, 비슷한 아바타나 닉네임만으로 매칭해서도 안 됩니다. ID가 있으면 우선 사용하고, 식별자가 충돌하거나 ID가 없을 때는 미확인 상태를 유지하십시오.

2단계: 점수를 매기기 전에 프로필을 조회하고 객체 확인하기

서버에 EVERYINFRA_API_KEY와 권한이 확인된 EVERYINFRA_TIKTOK_USERNAME이 설정되어 있다고 가정하고, profile 요청을 한 번 실행한 뒤 초기 점검을 위해 HTTP 상태와 본문을 보관합니다. 키를 프런트엔드 코드나 공개 분석 시트에 노출하지 마십시오.

: "${EVERYINFRA_API_KEY:?set the API Key first}"
: "${EVERYINFRA_TIKTOK_USERNAME:?paste the authorized account short name}"
jq -cn --arg username "${EVERYINFRA_TIKTOK_USERNAME}" '{
  platform: "tiktok", action: "profile", params: {username: $username}
}' | curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' --data-binary @-

현재 구현은 프로필 객체를 results 안에 넣고, 요청 추적 및 과금 메타데이터를 함께 반환합니다. username, user_id, 소스 URL이 대상과 일치하는지 확인하십시오. 객체가 반환되지 않았다면 모든 값이 0인 계정 프로필을 만들지 말고, 접근할 수 없는 콘텐츠, 조회 실패, 실제로 공개 데이터가 없는 경우를 구분하십시오.

프로필 필드는 bio, follower_count, following_count, video_count, is_verified, is_private 등 계정 소개와 규모를 파악하는 데 도움이 됩니다. 하지만 오디언스 연령, 구매 행동, 크리에이터의 민감한 속성을 증명하지는 않습니다. is_private가 true이면 동영상을 읽을 수 있다고 가정하거나 우회를 시도하지 마십시오.

이름이 같은 필드를 구분하십시오. profile의 like_count는 계정 단위 지표이고, 동영상의 like_count는 해당 동영상에 속한 값입니다. 둘을 범위 구분 없는 “좋아요 수” 열 하나에 섞거나, 계정 누적 값을 최근 동영상 조회수로 나누지 마십시오.

3단계: 동영상 샘플을 가져오고 선정 기준 기록하기

: "${EVERYINFRA_API_KEY:?set the API Key first}"
: "${EVERYINFRA_TIKTOK_USERNAME:?paste the authorized account short name}"
jq -cn --arg username "${EVERYINFRA_TIKTOK_USERNAME}" '{
  platform: "tiktok",
  action: "user_videos",
  params: {username: $username, limit: 5}
}' | curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' --data-binary @-

여기서 가져오는 5개 항목은 필드 검증용이며 통계적으로 대표성 있는 샘플 크기가 아닙니다. 이 요청은 profile 조회와 별개로 실행되고 과금되며, profile 조회가 성공했다고 동영상 목록 조회도 성공한다는 보장은 없습니다. 두 요청의 요청 ID, 타임스탬프, 과금 데이터를 각각 저장하십시오.

정렬이 필요하다면 현재 user_videos 디렉터리에는 newest, oldest, popular가 있으며, 조사 목표에 맞게 선택해야 합니다. popular 샘플은 기본 성과가 아니라 두드러진 콘텐츠를 보여 줍니다. 시간순 샘플은 고정 항목, 누락 항목, 게시 시각, 기간 범위의 일치 여부를 확인해야 합니다.

until 파라미터는 동영상 게시 시각의 상한을 지정하며, 수집 시각이나 검증된 페이지네이션 커서가 아닙니다. 현재 목록 엔드포인트는 전체 기록을 페이지 단위로 끝까지 조회할 수 있다고 보장하지 않으며, 날짜를 여러 번 조정한다고 누락이 없다는 것이 증명되지도 않습니다. 최소 예시는 필터 없이 시작하고, 결과를 검증하면서 필터를 하나씩 추가합니다.

디렉터리에서 한 파라미터가 여러 액션에 나타날 수 있습니다. 파라미터가 나열되어 있다고 모든 대상에 적용된다는 보장은 없습니다. 예를 들어 동영상 정렬은 크리에이터 팔로워 수 기준 정렬이 아닙니다. 파라미터의 효과가 확인되지 않았다면 조사 결론이 아닌 연동 테스트 단계에서만 다루십시오.

인터페이스 경계를 비교하자면, TikTok 공식 승인 기반 video/list는 cursor, has_more, 페이지당 max_count를 지정합니다. 공식 페이지네이션 파라미터를 EveryInfra user_videos에 적용하지 마십시오. 페이지네이션 지원 여부는 전적으로 해당 엔드포인트의 문서와 결과에 따라 달라집니다.

4단계: 계정, 동영상, 관측 데이터를 따로 저장하기

데이터는 세 가지 객체 유형으로 구성할 수 있습니다. 계정 테이블은 식별자와 프로필 관측을 저장하고, 동영상 테이블은 동영상 ID로 콘텐츠와 계정을 연결하며, 관측 테이블은 특정 요청에서 얻은 지표 값, 조건, 타임스탬프를 저장합니다. 이렇게 구성하면 동영상 조회수가 갱신될 때 크리에이터 프로필이 중복 저장되지 않습니다.

• 계정 관측: user_id, 요청한 핸들, 반환된 핸들, 프로필 참조, 확인 가능한 수치, 관측 타임스탬프, 요청 ID.
• 동영상 관측: 동영상 ID, URL, 텍스트, 작성자 핸들, posted_at, 참여 수와 조회수, 관측 타임스탬프, 요청 ID.
• 파생 분석: 사용한 동영상, 제외한 레코드, 지표 공식 버전, 계산 타임스탬프, 직접 작성한 메모.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/fields?platform=tiktok&action=user_videos' \
  | jq '{fields, undocumented}'

동영상 디렉터리에는 like_count, comment_count, share_count, view_count가 나열되어 있습니다. 공식 동영상 문서의 좋아요, 댓글, 공유, 조회수 설명은 용어를 확인하는 데 도움이 되지만, EveryInfra가 공식 필드를 모두 반환한다는 보장은 아닙니다. 각 엔드포인트는 실제 응답을 기준으로 파싱하십시오.

null 값, 누락된 필드, 0을 구분하십시오. 제공되지 않은 조회수를 0으로 채워서는 안 되며, 공유 수가 누락된 레코드를 아무런 표시 없이 참여도 계산에 포함해서도 안 됩니다. posted_at과 observed_at은 다릅니다. 전자는 게시 시각을, 후자는 관측 시각을 기록합니다.

5단계: 참여율을 계산하기 전에 공식부터 정의하기

모든 팀에 맞는 단일 참여율 공식은 없습니다. 예시를 위해 다음 샘플 지표를 정의합니다. 조회 대비 참여 비율 = 조건을 충족한 샘플의 좋아요, 댓글, 공유 합계 ÷ 같은 샘플의 총 조회수. 분자는 참여 이벤트를, 분모는 조회를 집계하며, 둘 다 고유 사용자 수나 전환율을 나타내지 않습니다.

이 가이드는 수치가 유효한 음이 아닌 정수이고 조회수가 0보다 큰 레코드만 포함하며, 불완전한 레코드는 따로 나열합니다. 이 보수적인 규칙은 누락 데이터가 0으로 가려지는 것을 막습니다. 자체 정의를 쓰려면 규칙을 조정하고 버전을 관리해야 하며, 서로 다른 공식으로 계산한 결과는 함께 순위를 매길 수 없습니다.

function interactionPerView(rows) {
  const seen = new Set();
  let events = 0, views = 0, used = 0;
  const excluded = [];
  for (const row of rows) {
    if (typeof row.id !== "string" || !row.id || seen.has(row.id)) {
      throw new Error("missing or duplicate video id");
    }
    seen.add(row.id);
    const counts = [row.like_count, row.comment_count,
                    row.share_count, row.view_count];
    if (!counts.every(x => Number.isSafeInteger(x) && x >= 0)
        || row.view_count === 0) {
      excluded.push(row.id);
      continue;
    }
    events += row.like_count + row.comment_count + row.share_count;
    views += row.view_count;
    if (!Number.isSafeInteger(events) || !Number.isSafeInteger(views)) {
      throw new Error("aggregate exceeds safe integer range");
    }
    used++;
  }
  return {used, excluded, events, views,
          ratio: views > 0 ? events / views : null};
}

console.log(interactionPerView([
  {id: "synthetic-a", like_count: 8, comment_count: 1,
   share_count: 1, view_count: 100},
  {id: "synthetic-b", like_count: 7, comment_count: 1,
   share_count: 1, view_count: 10},
  {id: "synthetic-c", like_count: null, comment_count: 1,
   share_count: 0, view_count: 20}
]));

합성 레코드 3개 중 앞의 2개는 계산에 포함되고, 세 번째는 좋아요 수가 없어 제외됩니다. 총 참여 수는 19, 총 조회수는 110이며, 조회 대비 참여 비율은 약 17.27%입니다. 개별 비율을 평균하면 50%가 나오는데, 두 값은 서로 다른 질문에 답합니다. 전자는 조회량에 따라 가중치를 두고, 후자는 동영상마다 같은 가중치를 둡니다. 보고서에 어떤 방식을 택했는지 명확히 밝히십시오.

이 예시는 크리에이터 평가 기준이나 업계 표준이 아닙니다. 한 계정에 두드러진 콘텐츠와 평균적인 성과가 함께 있을 수 있으며, 콘텐츠 길이, 게시 시점, 선정 기준이 비교 가능성에 영향을 줍니다. 백분율 하나보다 샘플 크기, 제외 항목, 총 조회수, 관측 기간을 함께 제시하는 편이 더 유용합니다.

6단계: 선별 결과에 사람이 해석할 여지 남기기

공개 데이터는 검토할 계정의 우선순위를 정하는 데 도움이 되지만, 콘텐츠 검토를 대신해서는 안 됩니다. 동영상 묶음을 검토할 때는 주제 관련성, 타깃 오디언스 적합성, 최근 콘텐츠가 충분한지를 확인하십시오. 콘텐츠 적합성에 대한 결론에는 블랙박스 점수가 아닌 구체적인 근거가 필요합니다.

소개 글, 이름, 아바타, 언어에서 민감한 개인 속성을 추론하지 마십시오. 검증된 오디언스 데이터, 전환, 이행 지표가 필요한 상업적 협업은 적절한 승인과 협업 절차를 거쳐야 합니다. 그런 근거가 없다면 모델로 완전한 프로필을 지어내지 말고 해당 필드를 알 수 없음으로 표시하십시오.

상품 조사에는 명확한 방법론이 필요합니다. 상품 언급, 프로필 링크, 스토어 정보가 있다고 해서 실제 판매량, 순매출, ROI를 입증할 수 있는 것은 아닙니다. 이 가이드의 두 액션은 상업적 성과를 증명하지 않으므로, 추정 GMV를 플랫폼 사실처럼 결과 테이블에 넣지 마십시오.

7단계: 반복 관측으로 변화 추적하기

프로필이나 동영상을 한 번 호출하면 스냅샷만 얻습니다. 성장을 분석하려면 비교 가능한 관측이 필요합니다. 즉, 식별자가 일관되고, 필드 정의가 같고, 관측 간격이 명확하며, 각 실행에서 데이터 조회가 성공해야 합니다. 이후 실행이 실패했다고 팔로워 수나 조회수가 0으로 떨어진 것은 아닙니다.

고정 동영상 집합과 변동 동영상 집합을 구분하십시오. 고정 집합을 추적하면 시간에 따른 수치 변화를 볼 수 있지만, 최근 동영상 묶음을 가져오면 콘텐츠 구성 자체가 바뀝니다. 어떤 동영상이 포함됐는지 추적하지 않고 이런 시계열을 곡선 하나로 이어 붙이면 그 곡선은 해석할 수 없습니다.

동영상이 사라졌다고 삭제된 것은 아닙니다. 현재 샘플 범위를 벗어났을 수 있습니다. 이름 변경, 고정 항목 변경, 타임스탬프 파싱 실패, 필드 누락은 품질 메모에 기록하십시오. 데이터 양이 줄었다고 크리에이터를 비정상이나 신뢰할 수 없는 대상으로 자동 분류하지 마십시오.

선별 결과의 변화를 추적할 때는 W3C PROV의 엔터티, 활동, 파생 관계를 적용해 동영상 샘플, 규칙 버전, 생성된 목록을 연결하십시오. 개념적 원칙만 빌려 오는 것이며, RDF 도입을 요구하거나 PROV 교환 사양 준수를 주장하는 것은 아닙니다.

오류 발생 시 복구 가능한 기록 남기기

401, 403, 할당량 문제는 인증, 기능 권한, 계정 조건을 각각 확인하십시오. 파라미터 오류는 실패한 요청을 반복하지 말고 응답의 안내에 따라 수정합니다. 인식할 수 없는 응답 형태는 검토 대기열로 보내고, 프로필의 빈 객체와 동영상 목록의 빈 배열을 하나의 성공 상태로 합치지 마십시오.

네트워크 타임아웃이 발생해도 서버는 요청을 완료했을 수 있으므로, 중복 과금이 없다고 가정하고 무작정 재시도하지 마십시오. 호출 로그를 확인하기 전에 시작/종료 타임스탬프, 액션, 민감하지 않은 파라미터 요약, 추적 ID를 보관하십시오. 실제 비용은 최종 조사 결과의 행 수가 아니라 과금 내역과 청구서로 결정됩니다.

검증 가능한 선별 목록 전달하기

쓸모 있는 크리에이터 선별 기록에는 선정 근거와 근거의 한계가 담겨야 합니다. 계정 식별자, 샘플 출처, 관측 타임스탬프, 계산 규칙, 제외 항목, 콘텐츠 검토 메모, 파트너 확인이 필요한 사항이 여기에 포함됩니다. API 응답 하나를 완전한 실사 결과로 포장하거나, 공개 데이터를 읽을 수 있다는 사실을 무제한 저장 및 재표시 권한으로 여기지 마십시오.

규모를 늘리기 전에 권한이 있는 계정 하나로 프로필, 동영상, 지표를 검증하십시오. 데이터 API는 수동 수집 작업을 줄여 주지만, 선별 품질은 지표를 명확히 설명하고 모든 판단을 실제 샘플에 근거하는 데 달려 있습니다.