핵심 개념

UnifAPI 곳곳에서 몇 가지 단어가 등장합니다. 한 번 익혀 두면 나머지 문서를 더 빨리 읽을 수 있습니다.

Skill

에이전트가 UnifAPI MCP로 실행할 수 있는 작업별 워크플로입니다. Skill은 KOL 가격 산정 브리프나 크리에이터 후보 목록 같은 원하는 출력에서 출발한 다음, 증거가 필요할 때 에이전트가 공개 데이터 작업을 발견하고 호출하게 합니다.

Skills는 에이전트 사용자에게 권장되는 시작점입니다. API 레퍼런스는 그 뒤에 있는 데이터 계층입니다.

Provider

API가 데이터를 노출하는 공개 플랫폼 — 예를 들어 TikTok, Twitter/X, LinkedIn, YouTube, Reddit 또는 Instagram. 모든 provider에는 최상위 경로 접두사가 있습니다.

https://api.unifapi.com/tiktok/...

Operation

provider 내부의 단일 호출 가능한 공개 데이터 엔드포인트 — 예를 들어 GET /tiktok/videos/{id}. 모든 operation에는 API 레퍼런스에 고유한 페이지가 있으며, MCP는 list_operations와 get_operation을 통해 operation 디스커버리를 노출합니다.

표준 스키마

같은 종류의 리소스 — Video, User, Comment — 를 반환하는 모든 operation은 동일한 표준 스키마를 사용합니다. 따라서 GET /tiktok/videos/{id}와 GET /tiktok/users/{id}/videos는 모두 동일한 필드 이름과 타입을 가진 Video 객체를 반환합니다.

표준 형태는 OpenAPI 명세의 components.schemas에 있으며 다음을 포함합니다: Video, Author, Music, MusicDetail, Comment, User, Hashtag, LiveRoom.

식별자

ID는 **불투명한 문자열(opaque string)**입니다. 긴 숫자처럼 보이지만, 정밀도를 보존하기 위해 문자열로 취급하세요(일부는 > 2^53).

• TikTok user id(sec_uid)는 긴 base64 토큰입니다. 예: MS4wLjABAAAA....
• TikTok video, music, hashtag id는 숫자처럼 보이는 문자열입니다. TikTok user 엔드포인트는 지원되는 경우 공개 handle, 숫자형 user id 또는 sec_uid를 허용합니다.

/tiktok/users/resolve?username=jennmelon으로 사용자 이름을 안정적인 user id로 변환하세요. /tiktok/videos/resolve?url=...로 공유 URL을 동영상으로 변환하세요.

공개 응답 엔벨로프

성공 응답은 동일한 최상위 엔벨로프를 사용합니다:

{
  "request_id": "req_...",
  "data": {
    /* resource or list payload */
  },
  "pagination": {
    "cursor": "1711494099000",
    "has_more": true
  },
  "billing": {
    "credits_charged": 10,
    "records_charged": 10,
    "balance_remaining": 90,
    "truncated_due_to_balance": false
  }
}

• request_id — 지원 및 추적을 위한 UnifAPI 요청 id.
• data — 비즈니스 페이로드.
• pagination — 리스트 operation이 계속될 수 있을 때 존재.
• billing — 호출에 대해 과금된 credits와 records.

페이지네이션

• pagination.has_more — 페이지가 적어도 하나 더 있으면 true.
• pagination.cursor — 다음 페이지를 위해 ?cursor=로 다시 전달할 불투명한 문자열. has_more가 false이면 null.

limit 쿼리 파라미터는 최대 50으로 제한됩니다.

커서는 의도적으로 불투명합니다: 어떤 소스는 정수 오프셋을, 어떤 소스는 타임스탬프를, 어떤 소스는 페이지 토큰을 사용합니다. UnifAPI가 이 차이를 숨깁니다. pagination.cursor를 파싱하려 하지 마세요.

오류 엔벨로프

모든 오류는 단일 중첩 엔벨로프를 공유합니다:

{
  "error": {
    "type": "...",
    "message": "...",
    "request_id": "...",
    "issues": [
      /* validation only */
    ]
  }
}

error.type은 닫힌 어휘(validation_error, not_found, unauthorized, ...)입니다. 오류를 참고하세요.

Workspace

과금 및 접근 경계입니다. OAuth MCP 세션, API 키, 사용량, 청구서가 모두 워크스페이스 수준에 존재합니다. 대시보드에서 팀원을 초대하세요 — 그들은 동일한 키와 사용량 카운터를 공유합니다.

공개 데이터 경계

UnifAPI는 공개 데이터를 제공합니다. OAuth는 UnifAPI MCP 접근과 워크스페이스 credits를 인가하며, 비공개 소스 계정을 인가하지 않습니다. 워크플로에 사용자의 비공개 SaaS 데이터가 필요하다면, UnifAPI를 해당 OAuth 통합 계층으로 취급하는 대신 커넥터 플랫폼과 함께 사용하세요.