본문 바로가기
개발가이드사이트 정보URL 화면캡처

URL 화면캡처 API

명세 내보내기
OpenAPI 3.0.3Postman 컬렉션Markdown

입력한 URL의 화면을 캡처합니다.

POSThttps://apick.app/rest/url_screenshot
인증
Bearer 키
요청 형식
form-data
응답
JSON · 파일
경로
1개

왜 URL 화면캡처인가

웹페이지 화면을 이미지로 즉시 박제

링크 미리보기, 증빙 보관, 화면 점검을 위해 사람이 일일이 캡처하고 있나요? URL만 넣으면 그 페이지 화면을 이미지로 돌려줘 증빙과 썸네일을 자동으로 남깁니다.

도입 효과

  • 반복되는 수동 캡처 업무를 자동화
  • 그 시점의 화면을 증빙으로 보관
  • 썸네일·미리보기 이미지를 바로 생성

이런 곳에서 많이 씁니다

  • 광고 대행사 게재 화면 증빙 보관
  • 메신저·게시판 링크 썸네일 생성
  • 운영팀 배포 후 화면 점검 리포트
  • 저작권 침해 페이지 증거 확보
가입하고 API 키 받기API 키 하나로 바로 호출 · 실패한 요청은 과금되지 않습니다

알아둘 점

이용 전 확인

웹 페이지 주소를 보내면 그 페이지 화면을 JPEG 이미지 파일로 돌려줍니다. 응답 본문이 JSON이 아니라 이미지 파일 자체이므로 파일로 저장하세요. 사이트 변경 기록, 증빙 화면 보관, 썸네일 생성에 씁니다.

캡처할 수 있는 최대 크기는 가로 2000px, 세로 10000px입니다.

캡처에 성공하면 한 건당 5P가 차감됩니다. 차감액은 응답 헤더 cost에서 확인하세요. 실패하면 이미지 대신 JSON 오류(data.error)가 오며 과금되지 않습니다.

http·https로 시작하는 공개 인터넷 주소만 받습니다. 사내망·사설 IP·localhost 주소는 캡처하지 않습니다. 응답까지 길면 30초 가까이 걸리므로 클라이언트 대기 시간은 60초 이상으로 두세요.

요청과 응답

API 요청
POST/rest/url_screenshot
  • Bearer 인증
  • multipart/form-data
  • 파일 응답
요청 파라미터 1개 · 필수 1
파라미터
설명
urlstring필수
캡처할 페이지의 전체 URL입니다. http·https를 포함해 보내며, 로그인·차단 페이지는 캡처가 실패할 수 있습니다.
예시
https://www.naver.com/
응답 필드 파일

정상 응답은 파일 본문입니다. 실패 시 JSON 오류가 올 수 있으므로 HTTP 상태와 Content-Type을 먼저 확인하세요.

입력 조건·전송 규칙
항목
설정
메서드·주소
POST https://apick.app/rest/url_screenshot
인증 헤더
Authorization: Bearer — 내 계정의 API 인증키
본문 형식
multipart/form-data
요청 예시

사용 예시

상황별로 보내는 값과 응답에서 확인할 값을 모았습니다. 언어 탭에서 그대로 복사해 쓸 수 있습니다.

예시 1. 페이지 화면 저장

페이지 화면을 JPEG 파일로 저장합니다. 응답 본문이 이미지 파일 자체입니다.

요청POST/rest/url_screenshot
curl --fail-with-body --request POST 'https://apick.app/rest/url_screenshot' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'url=https://www.naver.com/' \
  --dump-header response.headers --output result.bin
# response.headers의 Content-Type을 확인한 뒤 파일을 사용하세요.
  • 응답 헤더 Content-Type이 image/jpeg이면 본문을 파일로 저장합니다.
  • Content-Type이 JSON이면 실패이므로 본문의 data.error를 확인합니다. 과금되지 않습니다.
예시 2. 이벤트 페이지 증빙 보관

공지·이벤트 페이지가 게시된 상태를 날짜별로 보관할 때 씁니다.

요청POST/rest/url_screenshot
curl --fail-with-body --request POST 'https://apick.app/rest/url_screenshot' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'url=https://example.com/event' \
  --dump-header response.headers --output result.bin
# response.headers의 Content-Type을 확인한 뒤 파일을 사용하세요.
  • 응답 헤더 cost로 차감액을 확인하고, 파일 이름에 요청 시각을 붙여 저장합니다.
  • 사내망·localhost 주소는 이 호스트로는 요청할 수 없습니다.로 거절됩니다.

응답 처리

HTTP 성공과 업무 결과를 구분하세요. 경로별 응답 필드와 예시는 위 요청과 응답에 함께 있습니다.

실패하면 HTTP 상태가 4xx이고 본문은 아래와 같은 JSON입니다.

{
  "data": { "error": "알 수 없는 이유로 실패했습니다.", "success": 0 },
  "api": { "success": true, "cost": 0, "ms": 3120 }
}

응답을 받으면 Content-Type이 image/jpeg인지 먼저 확인하고, 아니면 본문을 JSON으로 읽어 data.error를 확인하세요.

원문 응답 필드 표 보기
필드
타입
설명
본문
binary
성공하면 JPEG 이미지 파일 본문입니다.
Content-Type
string
응답 헤더입니다. 성공하면 image/jpeg, 실패하면 JSON 형식입니다. 이 값으로 성공·실패를 먼저 나누세요.
Content-Disposition
string
응답 헤더입니다. attachment; filename=output.jpeg입니다.
success
integer
응답 헤더입니다. 성공하면 1입니다.
cost
integer
응답 헤더입니다. 차감된 포인트입니다.
ms
integer
응답 헤더입니다. 처리 시간(밀리초)입니다.
msg
string
응답 헤더입니다. 캡처 결과 안내 문구이며 URL 인코딩되어 있으므로 디코딩해서 읽습니다.

오류 코드

응답을 아래 순서로 확인하세요. 결과 유무와 과금 여부는 서로 다릅니다.

  1. HTTP 상태전송·인증·입력 오류
  2. api.successAPI 처리 여부
  3. data · result업무 결과와 오류 문구
  4. api.cost이번 요청의 과금
서비스 코드·조건

오류 코드

data.error
HTTP
대처
필수 입력값이 없습니다.
400
url을 채워 다시 요청합니다.
URL 형식이 올바르지 않습니다.
400
주소 철자와 형식을 확인합니다.
http 또는 https로 시작하는 주소만 사용할 수 있습니다.
424
https://를 붙여 보냅니다.
이 호스트로는 요청할 수 없습니다.
424
사내망·사설 IP·localhost 주소입니다. 공개 인터넷 주소만 쓸 수 있습니다.
호스트를 확인할 수 없습니다.
424
존재하지 않는 도메인입니다. 철자를 확인합니다.
알 수 없는 이유로 실패했습니다.
424
페이지가 열리지 않았거나 캡처에 실패했습니다. 브라우저에서 주소가 열리는지 확인한 뒤 다시 요청합니다.
처리 시간 초과로 실패했습니다. 잠시후 다시 시도해 주세요.
408
data.success가 3입니다. 잠시 뒤 다시 요청합니다.

오류 응답은 모두 과금되지 않습니다.

인증·포인트 오류 result.error 문구
코드
HTTP
의미·조치
유효하지 않은 API키 입니다.
401
Authorization: Bearer 헤더의 인증키를 확인하세요.
허용되지 않은 IP주소 입니다.
401
마이페이지의 허용 IP 설정과 요청 서버 IP를 확인하세요.
비활성화된 계정입니다.
401
계정 이용 상태를 고객지원으로 문의하세요.
사용 가능한 포인트이 부족합니다.
200
HTTP 200이어도 result.error가 있으면 실패입니다. 포인트를 충전한 뒤 다시 요청하세요. 이 응답은 과금되지 않습니다.
인증 정보를 확인할 수 없습니다.
424
일시적인 확인 실패입니다. 잠시 후 다시 시도하세요.
폼 입력 오류 error.code
코드
HTTP
의미·조치
FORM_DATA_INVALID
400
필드 이름·값의 타입·배열 인덱스를 확인하세요. 인덱스는 0부터 연속으로 사용합니다.
FORM_DATA_FIELD_CONFLICT
400
같은 값과 중첩 경로를 동시에 지정하지 마세요.
MULTIPART_LIMIT_OR_PARSE_ERROR
400·413
boundary·파일 크기·필드 개수를 확인하세요. 서비스별 제한이 우선 적용됩니다.

요금·이용 조건

기본 요금기본 단가 5P · 건당

실제 차감 금액은 응답의 api.cost로 확인하세요. 상세 요금은 요금정책에서 볼 수 있습니다.

연동 팁

  • 요청 예제의 오류 처리 포함 모드는 시간 제한과 업무 실패 판정을 함께 보여줍니다.
  • 인증키는 서버 환경변수에 두고 브라우저·앱에 넣지 마세요.
  • HTTP 성공과 업무 결과를 구분하고, 실패 응답의 오류 문구를 그대로 기록하세요.
추가 예제·서비스별 연동 안내

결과 예시

[이미지] URL 화면캡처 결과 예시

개발가이드 검색

API 이름·경로·파라미터·오류 코드로 찾을 수 있습니다.

표시 가격은 기본 단가입니다. 상세 과금 조건은 각 가이드에서 확인하세요.