설치하고 첫 요청 보내기

터미널 두 줄과 코드 열 줄이면 첫 응답을 받습니다. 여기까지 5분쯤 걸립니다.

설치하기

Node.js 18 이상이면 됩니다. 버전이 기억나지 않으면 node -v 부터 찍어 보세요.

# 프로젝트 안에서 실행합니다
npm install pelt

# 키는 파일에 적지 말고 환경 변수로 둡니다
export PELT_KEY="sk_live_여기에_발급받은_키"

첫 요청 보내기

클라이언트를 한 번 만들어 두고 계속 씁니다. 요청마다 새로 만들면 연결을 다시 여느라 느려집니다.

import { Pelt } from "pelt";

// 키는 환경 변수에서 읽어 옵니다
const pelt = new Pelt({ apiKey: process.env.PELT_KEY });

const res = await pelt.documents.create({
  title: "9월 정산 보고서",
  tags: ["finance", "2026"],
  timeout: 20000,
});

console.log(res.id, res.status);

응답 읽기

응답은 항상 같은 모양입니다. status 가 queued 면 아직 처리 중이고, 결과는 result 에 들어옵니다.

{
  "id": "doc_8f2a41",
  "status": "queued",
  "created_at": 1789459200,
  "result": null
}

필드가 뜻하는 것

막혔을 때

여기서 걸리는 경우가 거의 다 아래 셋입니다.

• 401 이 돌아옵니다. 키 앞뒤에 따옴표나 공백이 붙었는지 보세요. echo $PELT_KEY | cat -A 로 눈에 안 보이는 글자까지 확인할 수 있습니다.
• 응답이 계속 queued 입니다. 처리가 끝나기를 기다리는 요청이 아닙니다. 웹훅 받기 쪽을 보세요.
• 사내망에서 연결이 안 됩니다. 프록시를 쓰고 있다면 HTTPS_PROXY 를 함께 넘겨야 합니다.

다음에 볼 것

요청 하나를 보내 봤다면, 이제 여러 건을 한꺼번에 넣고 끝나는 대로 받아 보는 쪽이 실제 쓰임에 가깝습니다. 아래 세 문서를 이 순서로 읽으면 막히는 데 없이 이어집니다.

• 묶음 처리 — 문서 백 건을 한 번에 올리고, 끝난 것부터 받아 옵니다.
• 웹훅 받기 — 다 됐는지 계속 물어보지 않아도 됩니다. 끝나면 서버로 알려 줍니다.
• 오류 다루기 — 어떤 오류를 다시 시도해도 되고 어떤 것은 그러면 안 되는지 정리해 뒀습니다.