Seller API · MCP 연결하기

1. Seller 이용권과 API 키를 준비하세요

유효한 Seller 이용권으로 로그인한 뒤 ‘내 배치’ 아래 API 키 영역에서 키를 생성하세요. 전체 키는 생성 직후 한 번만 표시돼요. 안전한 환경 변수 HARUDOWN_API_KEY에 저장하고 브라우저 코드나 공개 저장소에 넣지 마세요. 아래 예제의 공유 링크와 YOUR_BATCH_ID, YOUR_RESULT_ID를 실제 값으로 바꾸세요. 키가 노출되면 해당 영역에서 폐기하고 새로 만드세요.

2. 배치를 제출하세요

POST /api/batches에 links 배열과 requestId를 보내세요. Seller는 샤오홍슈 또는 더우인 공유 링크 1~500개를 제출할 수 있어요. requestId는 영문·숫자·밑줄·하이픈 8~120자로 지정하세요. 응답은 HTTP 202와 배치 id이며 파일이 즉시 반환되지는 않아요. 같은 작업을 재전송할 때는 같은 requestId와 링크 배열을 유지하세요. 새 작업에는 새 requestId를 사용하세요.

curl 'https://harudown.com/api/batches' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "links": ["PASTE_YOUR_PUBLIC_SHARE_LINK"],
    "requestId": "my-batch-20261105-001"
  }'

3. 상태를 확인하고 CSV를 받으세요

GET /api/batches로 최근 100개 배치를, GET /api/batches/{id}로 상세 상태와 items를 조회하세요. queued는 대기, processing은 처리 중, completed는 처리 종료를 뜻해요. completed여도 항목별 status가 failed일 수 있으므로 error와 result_id를 확인하세요. 몇 초 간격으로 조회하고 처리 종료 후 멈추세요. GET /api/batches/{id}/export는 CSV를 반환해요. CSV에는 인증이 필요한 다운로드 주소가 들어 있으며 원본 미디어 주소는 포함되지 않아요.

curl 'https://harudown.com/api/batches/YOUR_BATCH_ID' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY"

curl 'https://harudown.com/api/batches/YOUR_BATCH_ID/export' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY" \
  --output results.csv

4. 성공한 결과의 원본 주소를 받으세요

성공한 항목의 result_id로 GET /api/download?id={result_id}를 요청하세요. HTTP 307 응답의 Location이 원본 미디어 주소예요. 아래 요청은 헤더만 출력해요. 원본 주소의 허용된 호스트를 확인한 뒤 인증 헤더 없이 별도 요청으로 파일을 받으세요. Bearer 키를 원본 서버에 전달하지 마세요. 사진 결과는 image=0부터 사진 순번을 지정해요. API · MCP 결과 보관에는 기간 제한이 없지만 원본 파일과 주소의 유효 기간은 원본 서버가 관리해요.

curl --get 'https://harudown.com/api/download' \
  --data-urlencode 'id=YOUR_RESULT_ID' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY" \
  --dump-header - --output /dev/null

5. MCP 클라이언트에서 연결하세요

POST 요청과 Bearer 인증을 지원하는 클라이언트에 /api/mcp를 설정하세요. 현재 HTTP POST JSON-RPC 응답을 제공하며 GET/SSE 연결은 제공하지 않아요. initialize 후 tools/list로 도구를 확인하고 tools/call로 실행하세요. create_batch(links, requestId), list_batches, get_batch(id), retry_batch_payment(id)를 제공해요. 마지막 도구는 계정·기존 결제 문제로 멈춘 배치를 재개하며 실패한 개별 링크를 재분석하지 않아요. 도구 응답의 content 안에는 JSON 문자열이, 업무 오류에는 isError: true가 들어 있어요.

curl 'https://harudown.com/api/mcp' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'

curl 'https://harudown.com/api/mcp' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

curl 'https://harudown.com/api/mcp' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_batch","arguments":{"id":"YOUR_BATCH_ID"}}}'

인증이나 요청이 실패할 때

401이면 키 누락·형식 오류·폐기 여부와 Seller 이용권 만료를 확인하세요. INVALID_LINK는 공개 공유 링크를 다시 복사하고, INVALID_REQUEST_ID는 요청 ID 형식을 확인하세요. REQUEST_CONFLICT는 같은 requestId에 다른 링크를 보낸 경우예요. 만료 후 새 API 요청은 차단되지만 이미 접수된 작업은 계속 처리돼요. 새 CSV 내보내기와 API 조회에는 다시 유효한 Seller 이용권이 필요해요.