> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Capabilities API

> BeatAPI의 모든 기능(소셜 데이터, 모델, 웹 검색, 워크플로)을 하나의 Search → Inspect → Run 흐름으로 사용합니다. 모든 응답에는 다음에 호출할 내용이 담겨 있습니다.

# 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`으로도 제공됩니다.

## Search

```bash
curl -sS -X POST https://api.beatapi.io/v1/capabilities/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"小红书 搜索笔记"}'
```

| 필드         | 타입      | 의미                                                                                                                                |
| ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `query`    | string  | 사용자가 원하는 내용을 사용자의 표현 그대로 적습니다. 플랫폼 + 동작 형태로, 중국어나 영어로 작성합니다(`抖音 用户作品`, `tiktok user profile`, `video model`). 완전한 문장도 사용할 수 있습니다. |
| `kind`     | string  | 선택 사항: `model`, `data` 또는 `workflow`.                                                                                             |
| `platform` | string  | 선택 사항: `xiaohongshu`, `小红书`처럼 slug 또는 이름을 지정합니다.                                                                                  |
| `limit`    | integer | 1–50, 기본값 5.                                                                                                                      |
| `cursor`   | string  | 이전 페이지의 `next_cursor`.                                                                                                            |
| `view`     | string  | `compact`(기본값)는 결과마다 카드 하나를 반환하고, `full`은 전체 계약을 반환합니다.                                                                           |
| `group_by` | string  | `function`은 일치 항목을 기능별로 묶습니다.                                                                                                     |

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

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

## Inspect

```bash
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` | 의미                                                                      |
| ----------- | ----------------------------------------------------------------------- |
| `ready`     | Run으로 실행할 수 있으며 입력, 출력, 가격이 공개되어 있습니다.                                  |
| `runnable`  | Run으로 실행할 수 있고 입력은 문서화되어 있지만, 출력 형태는 공개되어 있지 않습니다. 결과에서 필요한 값을 직접 읽으세요. |
| `listed`    | Run으로 실행할 수 없거나 입력이 문서화되어 있지 않습니다. `next`에서 이유를 확인하고 대안을 검색하세요.         |

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

## Run

```bash
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"}'
```

| 필드                | 의미                                                                                           |
| ----------------- | -------------------------------------------------------------------------------------------- |
| `reference`       | Inspect로 확인한 참조입니다.                                                                          |
| `operation`       | `start`(기본값), `status` 또는 `result`.                                                          |
| `input`           | `start`의 경우: Inspect로 확인한 `input_schema`를 따릅니다. `input` 안에 알 수 없는 필드가 있으면 거부됩니다.             |
| `task_id`         | `status`의 경우: 비동기 시작 시 반환된 작업입니다.                                                            |
| `request_id`      | `result`의 경우: 동기 시작 시 반환된 `request_id`입니다.                                                   |
| `view`            | `full`(REST 기본값) 또는 `preview`. 상태 폴링에도 사용할 수 있습니다.                                           |
| `max_items`       | `preview`를 사용하면 `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](/seo)에 있습니다.

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

```json
{ "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`이면 재시도하지 말고 호출을 수정하세요. 전체 표는 [오류](/errors)에 있습니다.

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