REQEO API · MCP

내 계정에서 API 키를 확인하세요. API와 웹은 리퀘오 계정의 포인트를 함께 사용합니다.

MCP 주소: https://reqeo.com/mcp/skills

Skills (검색·실행)

검수를 거친 Skill 을 검색하고 실행합니다. 인증키와 포인트는 다른 리퀘오 API 와 같고, 결과를 정상적으로 받았을 때만 차감되며, 실행 전에 예상 금액을 조회할 수 있습니다.

Skills 란

Skill 은 판매자가 등록하고 리퀘오이 심사해 게시한 실행 상품입니다. 입력 형식·결과 형식·가격·처리 상한이 Skill 마다 정해져 있으며, 웹·REST·MCP 어디에서 실행해도 같은 실행 번호와 같은 과금 규칙을 씁니다.

항목
내용
과금
결과가 약속한 형식으로 반환된 실행만 차감합니다. 차감 금액은 Skill 의 기본 금액에, AI 사용 비용을 별도로 청구하는 Skill 이면 실제 사용 비용을 더한 값입니다. 한글 표기 정규화는 글자 수 요금에 AI 사용 비용이 포함됩니다. 실패·시간초과·취소는 차감하지 않습니다.
예약
접수할 때 최대 금액을 예약하고, 끝나면 실제 금액만 차감한 뒤 차액을 바로 돌려줍니다. 실패하면 전부 돌려줍니다. 잔액이 최대 금액보다 적으면 접수되지 않습니다.
이용 조건
1회 이상 결제한 계정에서 실행할 수 있습니다. 한 계정에서 동시에 진행할 수 있는 실행은 5건입니다.
결과 보관
결과는 실행 뒤 7일 동안 조회할 수 있습니다. 입력은 실행이 끝나면 삭제합니다.
생성형 AI
uses_generative_ai 가 true 인 Skill 은 생성형 AI 가 결과를 만듭니다. 내 서비스 화면에 결과를 보여 줄 때 이 사실을 함께 표시해 주세요.

빠른 시작

검색으로 skill_id 를 찾고, 상세에서 입력 형식을 확인한 뒤 실행합니다. 실행 요청에는 요청마다 고유한 Idempotency-Key 헤더가 필요합니다.


curl "https://reqeo.com/rest/skills?query=상품명" \
-H "Authorization: Bearer 인증키"
        

curl -X POST "https://reqeo.com/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}'
        

요청 형식

요청 본문과 응답은 모두 JSON 입니다. 다른 리퀘오 API 의 data·api 봉투를 쓰지 않고, 아래 응답 항목이 최상위에 바로 옵니다.

Header
이름
필수
설명
Authorization
O
Bearer 인증키
Content-Type
POST 에 필수
application/json
Idempotency-Key
실행 요청에 필수
이 실행을 구분하는 고유 값. 영문·숫자와 . _ : - 로 1~128자
경로
Method
URL
설명
GET
https://reqeo.com/rest/skills
검색. query, category, sort, cursor, limit(최대 20)
GET
https://reqeo.com/rest/skills/{skill_id}
상세. 입력·결과 형식, 가격, 처리 상한, 예제
POST
https://reqeo.com/rest/skills/{skill_id}/quotes
예상 금액 조회. 입력을 검사하고 이 입력으로 실행했을 때의 예상 금액과 최대 금액을 알려 줍니다. 실행하지 않습니다
POST
https://reqeo.com/rest/skills/{skill_id}/runs
실행
GET
https://reqeo.com/rest/skills/runs/{run_id}
실행 상태. 성공한 실행은 결과를 함께 돌려줍니다
GET
https://reqeo.com/rest/skills/runs/{run_id}/result
결과만 조회
POST
https://reqeo.com/rest/skills/runs/{run_id}/cancel
취소. 끝나지 않은 실행만 취소됩니다
GET
https://reqeo.com/rest/skills/usage
내 실행 내역. cursor, limit(최대 50)

조회·예상 금액 조회·취소는 무료입니다. skill_id 자리에는 sk_ 로 시작하는 번호나 Skill 주소(slug)를 쓸 수 있습니다.

검색 순서와 고를 때 참고하는 값

검색의 sort 로 결과 순서를 고릅니다. 생략하면 등록 순서입니다. 검색어는 Skill 의 이름·요약·설명과 판매자 이름에서 찾습니다.

sort 값
값
순서
recommended
추천. 평점과 최근 사용, 좋아요를 함께 반영합니다
popular
인기. 최근 30일 동안 많이 실행되고 좋아요를 많이 받은 순서
used
지금까지 많이 실행된 순서
likes
좋아요가 많은 순서
rating
평점이 높은 순서
new
최근에 게시된 순서
mine
이 인증키의 계정이 많이 실행한 Skill 만, 많이 실행한 순서로
liked
이 인증키의 계정이 좋아요를 누른 Skill 만, 최근에 누른 순서로
참고 항목 (검색·상세 응답)
이름
타입
설명
usage_label
String
사용 건수 구간. 1,000회 미만, 1,000+, 2,000+, 5,000+, 1만+, 2만+, 5만+, 10만+ 처럼 올라갑니다
like_count
Integer
좋아요 수
review_count
Integer
리뷰 수. 리뷰는 그 Skill 을 실행해 결과를 받은 계정만 남깁니다
rating_average
Number
평점(1~5, 소수 첫째 자리). 리뷰가 없으면 null

curl "https://reqeo.com/rest/skills?sort=popular&limit=5" \
-H "Authorization: Bearer 인증키"
        

좋아요와 리뷰는 리퀘오 웹의 Skill 화면에서 남깁니다.

실행 요청 항목

Body (JSON)
이름
타입
필수
설명
input
Object
O
Skill 상세의 input_schema 에 맞는 입력. 정의되지 않은 항목은 거부됩니다
max_cost_points
Integer
X
최대 금액이 이 값보다 높으면 실행하지 않습니다. 그래서 실제 차감액은 이 값을 넘지 않습니다. 자동 호출에는 넣는 것을 권합니다
version
String
X
실행할 버전. 생략하면 현재 게시 버전. 게시 버전과 다르면 거부됩니다
quote_id
String
X
예상 금액 조회로 받은 번호. 5분 동안, 같은 계정·같은 입력에만 쓸 수 있습니다
wait_seconds
Integer
X
결과를 기다릴 시간(0~20초, 기본 20). 그 안에 끝나지 않으면 접수 응답(202)을 받습니다

가격과 예상 금액 조회

스킬 최종가는 기본요금(판매자 금액 + 기본 수수료) + 실제 AI 사용료입니다. AI 사용료는 모델별 단가와 실제 사용량으로 계산하며, 2026년 11월 6일부터 시간대별 요금이 있는 모델은 시간대와 관계없이 같은 단가를 적용합니다. AI 사용료에는 기본 수수료를 다시 곱하지 않습니다. 입력 크기와 결과 길이에 따라 달라지므로 실행 전에 POST /rest/skills/{skill_id}/quotes로 예상 금액과 최대 예약금을 무료 조회하세요. 예약금과 실제 확정액은 다르며 사용하지 않은 예약금은 해제됩니다.

한글 표기 정규화는 글자 수로 계산한 판매자 금액과 기본 수수료를 합산하며, AI 사용 비용을 별도로 더하지 않습니다. TTS에서 normalize_text가 true(기본)이면 이 스킬을 한 번 실행하고 그 최종가를 합성 요금에 더합니다. false이면 스킬 실행·요금이 없습니다. TTS 제작이 실패하면 스킬 요금까지 환불되며, 연결을 끊어도 제작이 끝나면 정상 과금됩니다. TTS 개발가이드

예상 금액 조회 요청 Body (JSON)
이름
타입
필수
설명
input
Object
O
실행할 때 보낼 입력. 형식이 맞지 않으면 INVALID_INPUT 으로 답합니다
version
String
X
버전. 생략하면 현재 게시 버전
금액 항목 (검색·상세·예상 금액 조회 응답)
이름
타입
설명
price_points
Integer
기본 금액. 실행마다 같습니다
usage_priced
Boolean
true 면 AI 사용 비용이 더해져 실행마다 금액이 달라집니다. false 면 항상 기본 금액입니다
estimated_points
Integer
예상 차감 금액. 검색·상세에서는 예제 입력 기준, 예상 금액 조회에서는 보낸 입력 기준입니다
max_points
Integer
이 입력으로 나올 수 있는 최대 금액(예상 금액 조회 응답). 실행을 접수할 때 이만큼 예약합니다
quote_id
String
실행 요청의 quote_id 에 넣는 번호(예상 금액 조회 응답)
expires_at
String
조회 결과의 유효 기한(ISO 8601, 5분)

curl -X POST "https://reqeo.com/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 를 넘지 않습니다.

요청 재시도와 멱등키

같은 Idempotency-Key 로 같은 요청을 다시 보내면 새로 실행하지 않고 처음 실행을 그대로 돌려줍니다. 통신이 끊겨 응답을 받지 못했을 때는 같은 키로 다시 보내세요. 포인트는 한 번만 차감됩니다.

같은 키에 다른 입력을 보내면 IDEMPOTENCY_CONFLICT(409) 로 거부됩니다. 새 실행에는 새 키를 쓰세요. 연결이 끊겨도 접수된 실행은 계속 진행되며, 멈추려면 취소를 호출합니다.

응답

실행이 끝나면 200, 아직 진행 중이면 202 를 돌려줍니다. 202 를 받으면 run_id 로 상태를 조회하세요.

실행 응답
이름
타입
설명
run_id
String
실행 번호
status
String
queued · running · completing · succeeded · failed · timed_out · cancelled
skill
Object
실행한 Skill 의 id, version, title
result
Object
status 가 succeeded 일 때만. Skill 의 output_schema 형식
billing
Object
과금 상태
status
String
reserved(예약) · captured(차감) · released(차감 없음) · partially_refunded · refunded
reserved_points
Integer
예약 중인 포인트(최대 금액). 끝나면 0 이 됩니다
charged_points
Integer
실제로 차감된 포인트
refunded_points
Integer
환불된 포인트
failure_code
String
실패로 끝난 실행의 사유
result_expires_at
String
결과 보관 기한(ISO 8601)
created_at / completed_at
String
접수·종료 시각(ISO 8601)
links
Object
상태 조회(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": "필수 값입니다." }] } } }
        
오류 코드
HTTP
코드
뜻과 대응
400
IDEMPOTENCY_KEY_REQUIRED
실행 요청에 Idempotency-Key 헤더가 없습니다
401
AUTH_REQUIRED
인증키가 없거나 올바르지 않습니다
402
INSUFFICIENT_POINTS
포인트가 부족합니다. 충전한 뒤 새 키로 다시 요청하세요
403
NOT_ALLOWED / PAYMENT_REQUIRED
권한이 없거나, 결제 이력이 없는 계정입니다
404
SKILL_OR_RUN_NOT_FOUND
Skill 이나 실행을 찾을 수 없습니다. 다른 계정의 실행도 이 코드로 답합니다
409
IDEMPOTENCY_CONFLICT
같은 키로 다른 요청이 이미 접수됐습니다
409
QUOTE_EXPIRED / VERSION_UNAVAILABLE / PRICE_EXCEEDS_LIMIT
예상 금액 조회·버전·상한 금액을 다시 확인한 뒤 요청하세요. PRICE_EXCEEDS_LIMIT 는 details 에 예상 금액과 최대 금액을 담아 줍니다
409
RUN_NOT_CANCELLABLE / RESULT_NOT_READY
이미 끝난 실행은 취소할 수 없고, 끝나지 않은 실행은 결과가 없습니다
410
RESULT_EXPIRED
결과 보관 기간이 지났습니다
422
INVALID_INPUT
입력이 Skill 의 입력 형식과 다릅니다. details.errors 에서 항목을 확인하세요
429
RATE_LIMITED / BUDGET_EXCEEDED
동시 실행 수 또는 사용 한도를 넘었습니다. Retry-After 뒤에 다시 요청하세요
503
TEMPORARILY_UNAVAILABLE
일시적으로 접수할 수 없습니다. 같은 키로 상태를 확인한 뒤 다시 요청하세요
실행 실패 사유 (failure_code)
값
뜻
EXECUTION_FAILED
실행 중 오류가 났습니다
OUTPUT_INVALID
결과가 약속한 형식과 달라 제공하지 않았습니다
TIMED_OUT
처리 시간 상한을 넘었습니다
CANCELLED
요청에 따라 취소했습니다
UPSTREAM_UNAVAILABLE
일시적으로 처리할 수 없었습니다. 잠시 후 새 Idempotency-Key로 다시 실행하세요

호출 예제

예상 금액을 조회한 뒤 실행하고, 202 를 받으면 상태를 조회하는 흐름입니다.


const BASE = "https://reqeo.com/rest/skills";
const headers = { Authorization: "Bearer " + process.env.REQEO_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);
        

MCP 연동 예시

AI 도구에 https://reqeo.com/mcp/skills 를 등록하면 아래 도구를 쓸 수 있습니다. 인증과 등록 방법은 MCP 연동 가이드와 같습니다.

도구
하는 일
search_skills
작업에 맞는 Skill 검색. sort 로 추천·인기·많이 쓴 순서를 고릅니다 (무료)
get_skill
입력·결과 형식, 기본 금액과 예상 금액, 예제 확인 (무료)
quote_skill
입력 검사와 예상 금액·최대 금액 조회 (무료)
run_skill
실행. idempotency_key 가 필수이며 결과를 받았을 때만 실제 사용한 만큼 차감
get_skill_run
실행 상태와 결과 조회 (무료)
cancel_skill_run
끝나지 않은 실행 취소 (무료)

claude mcp add --transport http apick-skills https://reqeo.com/mcp/skills \
  --header "Authorization: Bearer 인증키"
        

자동으로 실행하는 에이전트에는 max_cost_points 를 함께 넘기도록 지시해 정한 금액보다 비싼 실행이 시작되지 않게 하세요.