검수를 거친 Skill 을 검색하고 실행합니다. 인증키와 포인트는 다른 에이픽 API 와 같고, 결과를 정상적으로 받았을 때만 차감되며, 실행 전에 예상 금액을 조회할 수 있습니다.
Skill 은 판매자가 등록하고 에이픽이 심사해 게시한 실행 상품입니다. 입력 형식·결과 형식·가격·처리 상한이 Skill 마다 정해져 있으며, 웹·REST·MCP 어디에서 실행해도 같은 실행 번호와 같은 과금 규칙을 씁니다.
uses_generative_ai 가 true 인 Skill 은 생성형 AI 가 결과를 만듭니다. 내 서비스 화면에 결과를 보여 줄 때 이 사실을 함께 표시해 주세요.검색으로 skill_id 를 찾고, 상세에서 입력 형식을 확인한 뒤 실행합니다. 실행 요청에는 요청마다 고유한 Idempotency-Key 헤더가 필요합니다.
curl "https://apick.app/rest/skills?query=상품명" \
-H "Authorization: Bearer 인증키"
curl -X POST "https://apick.app/rest/skills/sk_예시번호/runs" \
-H "Authorization: Bearer 인증키" \
-H "Idempotency-Key: order-20261002-0001" \
-H "Content-Type: application/json" \
-d '{"input": {"product_name": "튼튼한 접이식 우산"}, "max_cost_points": 80}'
Skill 의 금액은 실행마다 같은 기본 금액과, AI 를 쓰는 Skill 에서 실행마다 달라지는 AI 사용 비용으로 이루어집니다. AI 사용 비용은 입력 크기와 결과 길이에 따라 정해지므로, 실행 전에 POST /rest/skills/{skill_id}/quotes 로 예상 금액과 최대 금액을 조회할 수 있습니다. 조회는 무료이며 실행하지 않습니다.
INVALID_INPUT 으로 답합니다quote_id 에 넣는 번호(예상 금액 조회 응답)
curl -X POST "https://apick.app/rest/skills/sk_예시번호/quotes" \
-H "Authorization: Bearer 인증키" \
-H "Content-Type: application/json" \
-d '{"input": {"product_name": "튼튼한 접이식 우산"}}'
{
"quote_id": "q_5d1c0a9b8e7f6a5b4c3d2e1f",
"skill_id": "sk_예시번호",
"version": "1",
"price_points": 60,
"estimated_points": 62,
"max_points": 64,
"usage_priced": true,
"expires_at": "2026-10-02T03:05:00.000Z",
"limits": { "max_input_chars": 200, "timeout_seconds": 30 },
"billing_rule": "validated_result"
}
실제 차감액은 실행이 끝난 뒤 응답의 billing.charged_points 로 확인합니다. max_points 를 넘지 않습니다.
요청 본문과 응답은 모두 JSON 입니다. 다른 에이픽 API 의 data·api 봉투를 쓰지 않고, 아래 응답 항목이 최상위에 바로 옵니다.
query, category, cursor, limit(최대 20)cursor, limit(최대 50)조회·예상 금액 조회·취소는 무료입니다. skill_id 자리에는 sk_ 로 시작하는 번호나 Skill 주소(slug)를 쓸 수 있습니다.
같은 Idempotency-Key 로 같은 요청을 다시 보내면 새로 실행하지 않고 처음 실행을 그대로 돌려줍니다. 통신이 끊겨 응답을 받지 못했을 때는 같은 키로 다시 보내세요. 포인트는 한 번만 차감됩니다.
같은 키에 다른 입력을 보내면 IDEMPOTENCY_CONFLICT(409) 로 거부됩니다. 새 실행에는 새 키를 쓰세요. 연결이 끊겨도 접수된 실행은 계속 진행되며, 멈추려면 취소를 호출합니다.
실행이 끝나면 200, 아직 진행 중이면 202 를 돌려줍니다. 202 를 받으면 run_id 로 상태를 조회하세요.
id, version, titleoutput_schema 형식self)와 결과 조회(result) 경로
{
"run_id": "run_3f2a9c0d8e7b4a61b5c4d3e2f1a09b8c",
"status": "succeeded",
"skill": { "id": "sk_예시번호", "version": "1", "title": "상품명 규칙 검사" },
"billing": { "status": "captured", "reserved_points": 0, "charged_points": 62, "refunded_points": 0 },
"created_at": "2026-10-02T03:00:00.000Z",
"completed_at": "2026-10-02T03:00:02.100Z",
"links": { "self": "/rest/skills/runs/run_3f2a9c0d8e7b4a61b5c4d3e2f1a09b8c", "result": "/rest/skills/runs/run_3f2a9c0d8e7b4a61b5c4d3e2f1a09b8c/result" },
"result_expires_at": "2026-10-09T03:00:02.100Z",
"result": { "passed": false, "issues": ["금지어 포함: 최저가"], "suggestion": "튼튼한 접이식 우산" }
}
접수 전에 거절된 요청은 아래 형식으로 답하며 포인트를 예약하지 않습니다. 접수된 뒤 실패한 실행은 상태 조회에서 failure_code 와 billing.status: "released" 로 확인합니다.
{ "error": { "code": "INVALID_INPUT", "message": "입력값이 상품의 입력 형식과 맞지 않습니다.", "details": { "errors": [{ "path": "$.product_name", "message": "필수 값입니다." }] } } }
PRICE_EXCEEDS_LIMIT 는 details 에 예상 금액과 최대 금액을 담아 줍니다details.errors 에서 항목을 확인하세요Retry-After 뒤에 다시 요청하세요예상 금액을 조회한 뒤 실행하고, 202 를 받으면 상태를 조회하는 흐름입니다.
const BASE = "https://apick.app/rest/skills";
const headers = { Authorization: "Bearer " + process.env.APICK_API_KEY, "Content-Type": "application/json" };
const input = { product_name: "튼튼한 접이식 우산" };
const quote = await (await fetch(BASE + "/sk_예시번호/quotes", { method: "POST", headers, body: JSON.stringify({ input }) })).json();
const key = crypto.randomUUID(); // 재시도할 때는 같은 값을 다시 씁니다
let response = await fetch(BASE + "/sk_예시번호/runs", {
method: "POST",
headers: { ...headers, "Idempotency-Key": key },
body: JSON.stringify({ input, quote_id: quote.quote_id, max_cost_points: quote.max_points }),
});
let run = await response.json();
if (!response.ok) throw new Error(run.error.code);
while (!["succeeded", "failed", "timed_out", "cancelled"].includes(run.status)) {
await new Promise((resolve) => setTimeout(resolve, 2000));
run = await (await fetch(BASE + "/runs/" + run.run_id, { headers })).json();
}
console.log(run.status, run.billing, run.result);
AI 도구에 https://apick.app/mcp/skills 를 등록하면 아래 도구를 쓸 수 있습니다. 인증과 등록 방법은 MCP 연동 가이드와 같습니다.
idempotency_key 가 필수이며 결과를 받았을 때만 실제 사용한 만큼 차감
claude mcp add --transport http apick-skills https://apick.app/mcp/skills \
--header "Authorization: Bearer 인증키"
자동으로 실행하는 에이전트에는 max_cost_points 를 함께 넘기도록 지시해 정한 금액보다 비싼 실행이 시작되지 않게 하세요.