탐색으로 건너뛰기

Capabilities API

Capabilities API

BeatAPI의 모든 기능은 같은 방식으로 세 번의 호출로 사용합니다. 소셜 미디어 데이터(Xiaohongshu, Douyin, TikTok, Bilibili, Weibo, X, Instagram, YouTube 등), 텍스트·이미지·영상·의사 결정 모델, 웹 검색, 미디어 워크플로가 모두 해당됩니다.

  1. Search로 사용자가 필요한 기능을 찾아 reference 하나를 고릅니다.
  2. Inspect로 해당 참조의 입력값, 가격, 실행 가능 여부를 확인합니다.
  3. Run으로 실행해 결과를 받거나, 폴링할 작업을 받습니다.

모든 응답에는 다음에 정확히 어떤 호출을 해야 하는지 알려 주는 next가 포함됩니다. 에이전트는 계약을 직접 추론할 필요 없이 이 값을 복사해 <placeholders>만 채우면 됩니다. 참조는 반환된 값을 그대로 복사하고, 직접 만들어 내지 마세요.

Search와 Inspect는 무료이며 키가 필요하지 않습니다. Run은 계정 잔액을 사용하며 Authorization: Bearer <BeatAPI API key>가 필요합니다. 키는 sk- 접두사가 있어도 없어도 동작합니다. 같은 세 가지 작업은 https://beatapi.io/mcp의 MCP 도구 capabilities_search, capabilities_inspect, capabilities_run으로도 제공됩니다.

curl -sS -X POST https://api.beatapi.io/v1/capabilities/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"小红书 搜索笔记"}'
필드타입의미
querystring사용자가 원하는 내용을 사용자의 표현 그대로 적습니다. 플랫폼 + 동작 형태로, 중국어나 영어로 작성합니다(抖音 用户作品, tiktok user profile, video model). 완전한 문장도 사용할 수 있습니다.
kindstring선택 사항: model, data 또는 workflow.
platformstring선택 사항: xiaohongshu, 小红书처럼 slug 또는 이름을 지정합니다.
limitinteger1–50, 기본값 5.
cursorstring이전 페이지의 next_cursor.
viewstringcompact(기본값)는 결과마다 카드 하나를 반환하고, full은 전체 계약을 반환합니다.
group_bystringfunction은 일치 항목을 기능별로 묶습니다.

응답의 data에는 reference, title, summary, price, readiness와 한 줄짜리 입력 signature로 구성된 간단한 카드가 담깁니다. understood는 쿼리에서 어떤 단어가 반영되고 어떤 단어가 무시되었는지 보여 줍니다.

  • 개요. 플랫폼 이름만 담은 쿼리(小红书)나 group_by: "function"을 보내면 groups가 채워집니다. 플랫폼이 제공하는 기능을 검색, 콘텐츠, 댓글, 사용자, 트렌드, 피드, 커머스, 라이브 등 기능별로 보여 주며, 각 항목에는 개수, 예시 참조, 나머지 항목을 조회하는 search 인수가 포함됩니다. 빈 쿼리를 보내면 카탈로그 맵을 반환합니다.
  • 일치 항목 없음. 결과가 0건이면 빈 페이지 대신 쿼리를 바꾸는 방법을 담은 hints와 플랫폼 slug를 함께 반환합니다.

Inspect

curl -sS -X POST https://api.beatapi.io/v1/capabilities/inspect \
  -H 'Content-Type: application/json' \
  -d '{"reference":"data:xiaohongshu.app_v2.search_notes"}'

Inspect는 전체 계약을 반환합니다. input_schema(필수 필드, 타입, 제한), pricing, execution.mode(sync는 응답으로 바로 답하고 async는 작업을 반환), readiness, 그리고 참조가 채워져 있고 모든 필수 입력에 자리 표시자가 들어간 Run 호출인 next가 포함됩니다.

readiness의미
readyRun으로 실행할 수 있으며 입력, 출력, 가격이 공개되어 있습니다.
runnableRun으로 실행할 수 있고 입력은 문서화되어 있지만, 출력 형태는 공개되어 있지 않습니다. 결과에서 필요한 값을 직접 읽으세요.
listedRun으로 실행할 수 없거나 입력이 문서화되어 있지 않습니다. next에서 이유를 확인하고 대안을 검색하세요.

추측했거나 철자가 틀린 참조에는 404 not_found와 함께 가장 가까운 공개 참조인 suggestions, 그리고 그중 가장 적합한 항목을 조회하는 next를 반환합니다.

Run

curl -sS -X POST https://api.beatapi.io/v1/capabilities/run \
  -H "Authorization: Bearer $BEATAPI_API_KEY" -H 'Content-Type: application/json' \
  -d '{"reference":"data:xiaohongshu.app_v2.search_notes","input":{"keyword":"AI 视频"},"view":"preview"}'
필드의미
referenceInspect로 확인한 참조입니다.
operationstart(기본값), status 또는 result.
inputstart의 경우: Inspect로 확인한 input_schema를 따릅니다. input 안에 알 수 없는 필드가 있으면 거부됩니다.
task_idstatus의 경우: 비동기 시작 시 반환된 작업입니다.
request_idresult의 경우: 동기 시작 시 반환된 request_id입니다.
viewfull(REST 기본값) 또는 preview. 상태 폴링에도 사용할 수 있습니다.
max_itemspreview를 사용하면 items에 남길 요소 수입니다. 기본값 5, 최대 50.
fields남길 경로입니다. 목록 각 요소의 키는 items[].<key>로, 그 밖에는 루트부터 점으로 구분한 경로로 지정합니다([]는 배열을 순회합니다).
idempotency_key작업마다 고유한 값으로, 최상위에서 reference 옆에 둡니다(또는 Idempotency-Key 헤더). 같은 시작 요청을 재시도할 때만 다시 사용하세요.

시작 요청의 반환값은 종류에 따라 다릅니다.

종류모드input결과
소셜·웹 데이터동기해당 동작의 input_schema데이터 래퍼(envelope). preview를 사용하면 목록이 items에 들어갑니다
웹 리서치(data:web.research)비동기, 30초~3분{"query": …}작업을 반환합니다. next에 안내된 대로 10–15초마다 폴링하세요. 결과는 data.output에 있으며, 실패한 실행은 과금되지 않습니다
텍스트 모델동기{"input": "<prompt or messages>"}, 선택 사항 instructions, max_output_tokens, temperature{object: "text.result", model, status, output_text, usage, request_id}
JEV(model:jev-1.14, model:jev-1.13)동기{"state": …, "questions": …}{id, model, answers, usage}
콘텐츠 검수, 텍스트(model:beat-moderation-1.0)동기{"input": "<text to check>"}{id, model, results, policy_version, usage}
콘텐츠 검수, 이미지(model:beat-moderation-vision-1.0)동기{"image_url": "<link or data URL>", "input": "<optional text>"}{id, model, results, policy_version, usage}
콘텐츠 검수, 텍스트와 최대 4장의 이미지(model:beat-moderation-2.0)동기{"input": "<optional text>", "image_urls": ["<link or data URL>"]}. 이미지 하나는 image_url로도 보낼 수 있습니다{id, model, results, policy_version, usage}
이미지·영상 모델, 워크플로비동기해당 기능의 input_schema작업을 반환합니다. succeeded 또는 failed가 될 때까지 5–10초마다 operation: "status"로 폴링하세요

SEO 도구는 data:seo.* 기능입니다. 동기로 실행되며 input는 도구의 요청 본문이고, 전체 목록은 SEO API에 있습니다.

결과 보기. 플랫폼 페이로드는 수십 KB에 이르고, 목록이 들어 있는 위치도 플랫폼마다 다릅니다. view: "preview"는 결과의 주요 목록을 최상위 items로 끌어올리고(처음 max_items개, 각 요소 내부도 정리), 원래 위치를 items_total과 함께 items_path(data.data.items, results, …)에 표시합니다. 긴 문자열은 줄이고 응답은 크기 예산 안으로 유지하며, 잘린 경우 result_ref와 함께 truncated로 표시합니다. fields는 지정한 경로만 남기며, 각 요소의 키는 items[].<key>로 지정합니다. 전체 결과는 같은 키로 1시간 동안 무료로 다시 조회할 수 있습니다.

{ "reference": "data:xiaohongshu.app_v2.search_notes", "operation": "result", "request_id": "<request_id>", "fields": ["items[].<key>"] }

REST의 기본값은 view: "full"이고, MCP 서버의 기본값은 preview입니다.

사용하는 방식에 맞춘 next

X-Beat-Client: mcp 또는 http(기본값)를 보냅니다. 이 값은 next.call의 작성 방식만 바꿉니다.

  • http: https://api.beatapi.io를 대상으로 하는 완전한 curl 명령입니다. 키가 필요한 호출에는 Authorization: Bearer $BEATAPI_API_KEY가 포함됩니다.
  • mcp: {"tool": "capabilities_run", "arguments": {…}}. BeatAPI MCP 서버가 이 헤더를 대신 보냅니다.

next.action은 search, inspect, run, status, result, none 중 하나이며, next.note는 호출이 무엇을 반환할지 알려 줍니다.

오류

모든 오류에는 retryable이 포함됩니다. 값이 false이면 재시도하지 말고 호출을 수정하세요. 전체 표는 오류에 있습니다.

상태코드조치
400bad_request다시 Inspect하고 지적된 필드를 수정하세요.
401missing_api_key키를 보내지 않았습니다. Authorization: Bearer <key>를 추가하세요.
401invalid_api_key키가 잘못되었거나 만료, 비활성화, 소진되었습니다. 대시보드에서 확인하세요. 재시도하지 마세요.
402insufficient_credits잔액을 충전하세요.
403forbidden이 키나 계정으로는 이 기능을 사용할 수 없습니다. 예를 들어 무료 크레딧으로 쓸 수 없는 모델이 해당하며, 충전하면 사용할 수 있습니다.
404not_foundsuggestions 중 하나를 사용하거나 다시 검색하세요.
409idempotency_conflict같은 idempotency_key를 다른 요청에 사용했습니다. 새 키를 사용하세요.
429rate_limit_exceededRetry-After 헤더(또는 retry_after_seconds)만큼 기다리세요.
500internal_error한 번 재시도하세요.
503processing_unavailable 또는 그 밖의 processing_* 코드호출을 완료하지 못했으며 과금되지 않았습니다. 백오프를 적용해 재시도하세요. 비동기 시작 요청은 같은 idempotency_key로 재시도하세요.

MCP에서는 게이트웨이에 도달한 도구 호출이 항상 도구 결과로 반환됩니다. 게이트웨이 오류는 isError: true와 함께 같은 JSON 오류 형식을 텍스트로 담아 돌아오므로, 에이전트가 이를 읽고 호출을 고칠 수 있습니다.

OpenAPI를 가져오는 에이전트 플랫폼용

https://beatapi.io/agent-openapi.json은 이 세 가지 작업과 웹 검색, Bearer 인증, 에이전트용 설명만 담은 경량 OpenAPI 문서입니다. OpenAPI로 도구를 만드는 플랫폼에 가져와 사용하세요. 전체 계약은 https://beatapi.io/openapi.json에, 에이전트 가이드는 https://beatapi.io/skill.md에 있습니다.