# URL 화면캡처



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



인증: Authorization: Bearer $APICK_API_KEY

본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다.

인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다.



## POST /rest/url_screenshot 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.error` (string): 오류 원인을 설명하는 문구입니다. 성공 응답에는 없거나 빈 문자열입니다.

- `data.success` (integer): 업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.

## API 요청: POST /rest/url_screenshot



### 입력

- `url` (string, 필수): 캡처할 페이지의 전체 URL입니다. http·https를 포함해 보내며, 로그인·차단 페이지는 캡처가 실패할 수 있습니다.



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string"
        },
        "success": {
          "type": "integer",
          "description": "응답 헤더입니다. 성공하면 1입니다."
        }
      }
    },
    "api": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "응답 헤더입니다. 성공하면 1입니다."
        },
        "cost": {
          "type": "integer",
          "description": "응답 헤더입니다. 차감된 포인트입니다."
        },
        "ms": {
          "type": "integer",
          "description": "응답 헤더입니다. 처리 시간(밀리초)입니다."
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

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

```

### curl

```curl

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을 확인한 뒤 파일을 사용하세요.

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("url", "https://www.naver.com/");
const response = await fetch("https://apick.app/rest/url_screenshot", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
if ((response.headers.get("content-type") || "").includes("json")) {
  throw new Error(JSON.stringify(await response.json()));
}
const { writeFile } = await import("node:fs/promises");
await writeFile("result.bin", new Uint8Array(await response.arrayBuffer()));

```

### python

```python

import os
import requests
parts = [
    ("url", (None, "https://www.naver.com/")),
]
response = requests.request("POST", "https://apick.app/rest/url_screenshot",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120), stream=True)
response.raise_for_status()
if "json" in response.headers.get("Content-Type", ""):
    raise RuntimeError(response.json())
with open("result.bin", "wb") as output:
    for chunk in response.iter_content(65536):
        output.write(chunk)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'url' => 'https://www.naver.com/',
];
$curl = curl_init('https://apick.app/rest/url_screenshot');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$type = curl_getinfo($curl, CURLINFO_CONTENT_TYPE) ?: "";
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
if (strpos($type, "json") !== false) { throw new RuntimeException($body); }
file_put_contents('result.bin', $body);

```

## 사용 예시 1. 페이지 화면 저장

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

```bash

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. 이벤트 페이지 증빙 보관

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

```bash

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` 주소는 `이 호스트로는 요청할 수 없습니다.`로 거절됩니다.

## 코드·오류

## 상세 기능·요금

이용 전 확인 웹 페이지 주소를 보내면 그 페이지 화면을 JPEG 이미지 파일로 돌려줍니다. 응답 본문이 JSON이 아니라 이미지 파일 자체이므로 파일로 저장하세요. 사이트 변경 기록, 증빙 화면 보관, 썸네일 생성에 씁니다. 캡처할 수 있는 최대 크기는 가로 2000px, 세로 10000px입니다. 캡처에 성공하면 한 건당 5P가 차감됩니다. 차감액은 응답 헤더 cost에서 확인하세요. 실패하면 이미지 대신 JSON 오류(data.error)가 오며 과금되지 않습니다. http·https로 시작하는 공개 인터넷 주소만 받습니다. 사내망·사설 IP·localhost 주소는 캡처하지 않습니다. 응답까지 길면 30초 가까이 걸리므로 클라이언트 대기 시간은 60초 이상으로 두세요.

## 상세 요청

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

## 상세 응답

필드타입설명 본문binary성공하면 JPEG 이미지 파일 본문입니다. Content-Typestring응답 헤더입니다. 성공하면 image/jpeg, 실패하면 JSON 형식입니다. 이 값으로 성공·실패를 먼저 나누세요. Content-Dispositionstring응답 헤더입니다. attachment; filename=output.jpeg입니다. successinteger응답 헤더입니다. 성공하면 1입니다. costinteger응답 헤더입니다. 차감된 포인트입니다. msinteger응답 헤더입니다. 처리 시간(밀리초)입니다. msgstring응답 헤더입니다. 캡처 결과 안내 문구이며 URL 인코딩되어 있으므로 디코딩해서 읽습니다. 실패하면 HTTP 상태가 4xx이고 본문은 아래와 같은 JSON입니다. { "data": { "error": "알 수 없는 이유로 실패했습니다.", "success": 0 }, "api": { "success": true, "cost": 0, "ms": 3120 } } 응답을 받으면 Content-Type이 image/jpeg인지 먼저 확인하고, 아니면 본문을 JSON으로 읽어 data.error를 확인하세요.

## 상세 코드·정책

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

## 상세 예제

결과 예시 [이미지]
