탭은 쌓이고, 비교는 시작도 못 했다

비교할 자료는 다 찾았는데 브라우저 탭만 잔뜩 열려 있습니다. 한 페이지씩 본문을 복사하고 원래 링크를 붙이다 보니, 정작 읽고 비교할 시간은 줄어듭니다. 요약을 보고 “이건 어디에 나온 말이지?” 싶으면 탭을 다시 뒤져야 하고요.

AI에게 분석을 맡기려던 일이 AI가 읽을 자료를 준비하는 수작업으로 바뀐 겁니다. 다음 조사에서도 이 준비를 반복해야 한다면, 찾아둔 링크에서 본문과 출처를 한꺼번에 모아두는 방법이 필요합니다.

Olostep 배치는 URL마다 이름을 붙여 제출하고, 처리가 끝난 항목의 본문을 다시 가져오는 도구입니다. 여기서는 공개 문서 두 개로 시작해 AI의 답에서 원문까지 되짚어볼 수 있는 참고자료를 만들어보겠습니다.

설치 없이 브라우저에서 두 주소부터

첫 수집은 공식 API 문서의 Try it 요청 화면에서 진행할 수 있습니다. 별도 코드는 필요 없지만 Olostep 계정, 대시보드에서 발급한 API 토큰, 요청에 사용할 크레딧은 준비해야 합니다. API 요청은 Authorization: Bearer <API-TOKEN> 형식으로 인증합니다.

  1. Olostep에 가입하거나 로그인합니다. 이어서 API Keys 화면에서 토큰을 만들고 대시보드에서 사용할 수 있는 크레딧을 확인하세요.
  2. Create Batch 문서의 Try it을 엽니다. 인증란에는 화면 안내에 맞춰 API 토큰을 넣습니다. 헤더 전체를 직접 입력하는 환경이라면 Bearer와 토큰 사이에 공백 하나를 둡니다.

두 링크에 찾기 쉬운 이름을 붙이세요

items에 항목 두 개를 만들고 각각 custom_id와 url을 입력합니다. custom_id는 나중에 회수한 본문이 어느 주소에서 왔는지 찾는 이름입니다. 첫 요청에서는 파서 같은 선택 항목을 비워두고 Markdown 본문 회수부터 확인해도 됩니다.

custom_idurl
batches-guidehttps://docs.olostep.com/features/batches
retrieve-guidehttps://docs.olostep.com/api-reference/retrieve

요청 데이터는 다음 모양입니다.

{"items":[
  {"custom_id":"batches-guide","url":"https://docs.olostep.com/features/batches"},
  {"custom_id":"retrieve-guide","url":"https://docs.olostep.com/api-reference/retrieve"}
]}

접수번호가 아니라 본문까지 받아야 끝입니다

배치는 제출, 완료 확인, 항목 조회, 본문 회수의 순서로 진행됩니다. 생성 직후에는 본문 대신 in_progress 상태의 배치 정보가 올 수 있으므로 첫 응답만 받고 끝내면 안 됩니다.

  1. Create Batch에서 두 URL을 제출합니다. 응답에서 새로 반환된 id를 저장하세요. 이 값이 이후 요청에 사용할 batch_id입니다. 문서에 미리 표시된 예시 값과 실제 응답 값을 혼동하지 않는 것이 중요합니다.
  2. Batch Info에서 상태를 확인합니다. 저장한 batch_id로 조회하고 status가 completed일 때 다음 단계로 갑니다. 처리 시간은 대상 페이지와 계정 환경에 따라 달라질 수 있으므로 고정된 완료 시간을 전제로 자동화하지 마세요.
  3. Batch Items에서 문서별 번호를 받습니다. 완료 항목에는 custom_id, 원래 url, 본문 회수에 쓸 retrieve_id가 포함됩니다. 실패 항목도 status=failed로 따로 조회하세요.
  4. Retrieve Content에서 본문을 가져옵니다. 각 retrieve_id와 formats=markdown을 사용해 조회합니다. 응답의 markdown_content를 같은 항목의 custom_id, 원래 URL과 함께 저장하세요.

첫 성공 기준은 네 값이 연결되는 것입니다.

두 문서 모두 custom_id, 원래 URL, retrieve_id, 비어 있지 않은 Markdown 본문이 한 묶음으로 저장되어야 합니다. 배치 ID만 받았거나 본문과 URL의 짝을 확인하지 못했다면 아직 AI 참고자료가 완성된 게 아닙니다.

요청이 막히면 오류를 먼저 분류하세요. 401이나 invalid_api_key는 토큰과 Bearer 형식을, 402나 credits_exhausted는 크레딧을 확인할 신호입니다. 완료 목록에 문서가 없다면 실패 항목을 따로 조회합니다. size_exceeded=true라면 응답 본문 대신 제공된 호스팅 URL에서 콘텐츠를 받아 보관해야 합니다. 이 URL은 7일 후 만료됩니다.

공식 문서와 공개 요청 화면을 확인해 작성했으며, 유효한 API 토큰으로 배치 생성과 본문 회수를 직접 실행한 결과는 아닙니다.

터미널에서 같은 요청 보내기

Bash, curl, jq를 쓰는 개발자라면 같은 흐름을 터미널에서 반복할 수 있습니다. 먼저 토큰을 화면에 노출하지 않고 환경 변수로 준비하세요.

read -rs OLOSTEP_API_KEY
export OLOSTEP_API_KEY

1. 배치를 만들고 실제 응답의 ID를 저장합니다.

curl --fail-with-body --silent --show-error \
  https://api.olostep.com/v1/batches \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"items":[{"custom_id":"batches-guide","url":"https://docs.olostep.com/features/batches"},{"custom_id":"retrieve-guide","url":"https://docs.olostep.com/api-reference/retrieve"}]}' \
  > batch.json
batch_id=$(jq -er '.id' batch.json)

2. 완료 상태를 확인합니다.

curl --fail-with-body --silent --show-error \
  "https://api.olostep.com/v1/batches/$batch_id" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  | jq -r '.status'

3. 완료 항목을 조회합니다.

curl --fail-with-body --silent --show-error --get \
  "https://api.olostep.com/v1/batches/$batch_id/items" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  --data-urlencode 'status=completed' \
  --data-urlencode 'limit=50' \
  > items.json
jq '{items, cursor}' items.json

응답에 cursor가 있으면 같은 목록 요청에 그 값을 추가해 다음 페이지를 가져옵니다. 실패 항목은 status=failed로 별도 조회합니다.

4. 문서 이름으로 retrieve_id를 찾아 본문을 받습니다.

retrieve_id=$(jq -er '.items[] | select(.custom_id == "batches-guide") | .retrieve_id' items.json)
curl --fail-with-body --silent --show-error --get \
  https://api.olostep.com/v1/retrieve \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  --data-urlencode "retrieve_id=$retrieve_id" \
  --data-urlencode 'formats=markdown' \
  > content.json
jq -e '.markdown_content | length > 0' content.json

두 번째 문서도 해당 custom_id로 찾아 같은 방식으로 회수합니다. 공식 형식에 맞춘 예제이며 실제 서비스 호출 결과는 검증하지 않았습니다.

모은 자료에는 답의 형식까지 지정하세요

본문을 확보했다면 “Olostep 사용법을 알려줘”처럼 넓게 묻기보다, 첨부한 자료에서만 답하고 원래 URL을 표시하도록 요청하는 편이 좋습니다.

첨부한 두 문서만 읽고 신규 계정의 배치 한도와 본문을 회수하는 순서를 정리해줘. 각 답에 원래 문서 URL을 붙이고, 문서에 없는 내용은 확인되지 않았다고 표시해줘.

공식 문서에서 확인할 수 있는 답은 신규 계정의 배치당 한도가 100개이며, 한도 상향은 제공사에 문의해야 한다는 내용입니다. 구조화 JSON이 필요하다면 배치를 제출할 때 대상에 맞는 파서를 지정해야 합니다. 파서 없이도 Markdown이나 HTML은 회수할 수 있지만, 모든 사이트에 공통으로 맞는 파서나 출력 품질이 보장되는 것은 아닙니다.

두 URL이 통과한 뒤에 1만 개로 늘리세요

Olostep의 공식 배치 최대치는 1만 URL이지만 신규 계정의 시작 한도는 배치당 100개입니다. 따라서 두 문서에서 본문과 출처의 짝을 확인한 뒤 100개, 더 큰 묶음 순서로 확대하는 편이 현실적입니다.

  • 누락을 확인하세요. 완료 목록만 보지 말고 실패 목록을 따로 조회하며, 제출한 custom_id 전체와 결과를 대조합니다.
  • 커서를 끝까지 읽으세요. Batch Items에 cursor가 반환되면 다음 요청에 전달합니다. 첫 페이지의 최대 50개만 저장하고 전체 배치가 끝났다고 판단하면 안 됩니다.
  • 배열 순서를 믿지 마세요. 결과의 위치가 아니라 custom_id로 원래 URL과 회수한 본문을 연결합니다.
  • 본문을 직접 보관하세요. 호스팅 URL은 7일 뒤 만료되므로 다시 사용할 자료는 작업 직후 별도 저장소로 옮깁니다.

URL 목록이 이미 있고 여러 페이지를 한꺼번에 모으는 일이 반복될 때 배치가 잘 맞습니다. 한 페이지만 즉시 읽어야 한다면 공식 문서가 안내하는 단일 스크래핑 방식이 더 단순할 수 있어요.

목표는 1만 번의 요청을 성공시키는 것이 아닙니다. AI가 읽은 본문마다 원래 주소를 다시 열 수 있고, 빠진 항목을 찾아 재처리할 수 있는 참고자료를 만드는 것입니다.