API 빠른 시작: 첫 파일 변환하기
API 키를 만들고, 파일을 보내고, 작업이 끝나기를 기다린 뒤 결과를 다운로드하는 과정을 그대로 복사해 쓸 수 있는 요청 예제로 설명합니다.
핵심 답변
대시보드 → API 및 키에서 키를 만든 다음, 공개 파일 URL, 파일 이름, 대상 형식을 담아 POST https://maxscanner.app/api/v1/jobs/ 요청을 보냅니다. API는 즉시 jobId를 반환합니다. status가 "completed"가 될 때까지 몇 초마다 GET /api/v1/jobs/{jobId}/ 요청으로 폴링하고, 완료되면 5분 안에 output.downloadUrl을 다운로드합니다.
빠른 시작
- 1대시보드 → API 및 키를 열고 ‘API 키 만들기’를 선택한 다음 ‘파일 처리’를 체크하고 키를 복사합니다(키는 한 번만 표시됩니다).
- 2키는 MAXSCANNER_API_KEY 같은 환경 변수에 저장합니다. 클라이언트 측 코드에는 절대 넣지 마십시오.
- 3url, filename, format을 담아 POST /api/v1/jobs/ 요청을 보냅니다. 202 응답의 jobId를 보관합니다.
- 4status가 completed 또는 failed가 될 때까지 2~10초마다 GET /api/v1/jobs/{jobId}/ 요청을 보냅니다.
- 5output.downloadUrl은 바로 다운로드하십시오. 서명된 링크는 5분 후 만료됩니다.
시작하기 전에
모든 요청은 https://maxscanner.app/api/v1/ 아래로 보내며, 키는 Bearer 토큰으로 전달합니다. 요청 URL은 슬래시로 끝나야 합니다. 슬래시가 없는 URL에는 308 리디렉션이 반환되고 대부분의 HTTP 클라이언트가 이를 따라가지만, 처음부터 슬래시를 붙이면 왕복을 한 번 줄일 수 있습니다.
무료 요금제에서는 하루 10회, 한 달 100회까지 요청할 수 있으며, 연동을 구축하고 테스트하기에 충분합니다. 유료 요금제는 대신 월간 크레딧을 사용하며, 엔드포인트마다 0~3크레딧이 차감됩니다.
- 기본 URL: https://maxscanner.app/api/v1/
- 헤더: Authorization: Bearer <your key>
- 본문: Content-Type: application/json을 지정한 JSON
- 파일: URL 가져오기 또는 직접 업로드로 최대 50 MB
Word 파일을 PDF로 변환하기
jobs 엔드포인트는 입력 형식과 출력 형식을 보고 알맞은 프로세서를 선택합니다. 공개 URL을 전달하면 작업을 만들 때 서버가 직접 파일을 다운로드합니다(최대 50 MB, 30초 이내. 리디렉션은 따라가지 않으므로 최종 파일 링크를 사용하십시오). 비공개 파일은 직접 업로드를 사용하고 대신 sourceKey를 전달하십시오(파일 및 업로드 가이드 참조). Idempotency-Key 헤더를 추가하면 요청을 재시도해도 두 번째 작업이 생성되지 않습니다.
curl -X POST 'https://maxscanner.app/api/v1/jobs/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quickstart-0001' \
-d '{ "url": "https://example.com/report.docx", "filename": "report.docx", "format": "pdf" }'결과 기다리기
작업은 비동기로 처리되므로 큰 파일 때문에 HTTP 연결을 계속 열어 둘 필요가 없습니다. 상태 URL을 폴링하되, 약 2초 간격으로 시작해 최대 10초까지 간격을 점차 늘립니다. 작은 Office 파일은 보통 20초 안에 끝나지만, 1080p 동영상은 몇 분이 걸릴 수 있습니다. status가 completed가 되면 output에 콘텐츠 유형, 바이트 단위 크기, 서명된 downloadUrl이 담깁니다.
curl 'https://maxscanner.app/api/v1/jobs/6f0c2a6e-8a1b-4a53-9a0e-2b1f4c9d7e11/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY"다음 단계
처리할 파일이 몇 개를 넘어서면 폴링 대신 웹훅을 사용하고, 재시도 규칙은 작업 가이드에서 확인하십시오. 그런 다음 하려는 작업에 맞는 기능 가이드(OCR, PDF 도구, 이미지, 미디어, 저장된 워크플로 실행)를 선택하십시오.
자주 묻는 질문
SDK를 설치해야 합니까?
아니요. API는 일반 HTTPS와 JSON을 사용하므로 HTTP 요청을 보낼 수 있는 언어나 노코드 도구라면 무엇이든 사용할 수 있습니다. 코드 예제 가이드에 Node.js, Python, PHP, cURL로 작성한 전체 예제가 있습니다.
다운로드 링크는 얼마 동안 유효합니까?
5분입니다. 링크가 만료되면 작업 상태를 다시 요청해 새 링크를 받으십시오.
테스트 모드가 있습니까?
테스트에는 무료 요금제를 사용하십시오. 엔드포인트는 동일하며, 계정마다 하루 10회, 한 달 100회로 요청이 제한됩니다.