Screenshot API v1

以下は POST /api/v1/screenshots.

認証

API キーを Authorization ヘッダーに送信してください:

Authorization: Bearer <api_key>

スクリーンショットを作成

エンドポイント: POST /api/v1/screenshots

本文: JSON

最小リクエスト例

curl -X POST "https://api.page-ops.com/api/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

同期リクエスト（許可される場合）

curl -X POST "https://api.page-ops.com/api/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "mode": "sync",
    "timeoutMs": 8000,
    "fullPage": false
  }'

完了前に同期ウィンドウが切れた場合、API は status=processing. 以下を使ってポーリングを続けてください: GET /api/v1/screenshots/{jobId}.

主要パラメータ

url

必須。キャプチャ対象の URL。

mode

任意。 async （デフォルト）または sync.

timeoutMs

これは sync. で必須です。次を満たす必要があります: > 0 かつ < 10000.

fullPage

任意。 sync モードでは、 false.

同期モード制約

たとえ mode=sync, を指定しても、以下を満たさない限りサーバーは async にフォールバックします:

mode == "sync"

timeoutMs != null

0 < timeoutMs < 10000

fullPage == false

パラメータ一覧（完全版）

項目	型	必須	デフォルト	説明
url	string	はい	-	対象 URL。
mode	string	いいえ	async	次を受け付けます: async または sync （大文字・小文字は区別されません）。;
timeoutMs	int?	いいえ	-	sync の場合のみ使用されます。次を満たす必要があります: 0 < timeoutMs < 10000.
fullPage	bool	いいえ	false	sync では false.
viewport	object?	いいえ	-	ビューポートを上書きします。
format	string?	いいえ	-	現在サポートされているのは png のみです。他の形式は将来のバージョン向けに予約されています。
quality	int?	いいえ	-	現在は無視されます（将来的に jpeg/webp でのみ使用予定）。
waitUntil	string?	いいえ	-	推奨値: load, domcontentloaded, networkidle.
delayMs	int?	いいえ	-	waitUntil 後の追加遅延。
selector	string?	いいえ	-	特定の要素のみをキャプチャします。
headers	object?	いいえ	-	追加のリクエストヘッダー辞書。
cookies	array?	いいえ	-	注入する Cookie の一覧。
javascript	string?	いいえ	-	注入するカスタム JS（実装依存）。;
css	string?	いいえ	-	注入するカスタム CSS（実装依存）。;
device	string?	いいえ	-	推奨値: desktop/iphone/ipad/pixel.
strictDevice	bool?	いいえ	-	true の場合、未対応デバイスは失敗すべきです（実装依存）。;
colorScheme	string?	いいえ	-	推奨値: light/dark/no-preference.
proxy	string?	いいえ	-	将来のバージョン向けに予約されており、現在は無視されます。
trace	bool?	いいえ	-	将来のバージョン向けに予約されており、現在は無視されます。
har	bool?	いいえ	-	将来のバージョン向けに予約されており、現在は無視されます。
returnDom	bool?	いいえ	-	将来のバージョン向けに予約されており、現在は無視されます。
returnNetwork	bool?	いいえ	-	将来のバージョン向けに予約されており、現在は無視されます。
priority	int?	いいえ	-	将来のバージョン向けに予約されており、現在は無視されます。

viewport

項目	型	必須	説明
viewport.width	int	いいえ	ビューポートの幅。
viewport.height	int	いいえ	ビューポートの高さ。

cookies[]

項目	型	必須	説明
cookies[].name	string	はい	Cookie 名。
cookies[].value	string	はい	Cookie 値。
cookies[].domain	string?	いいえ	Cookie ドメイン。
cookies[].path	string?	いいえ	Cookie パス。

レスポンス例

非同期（デフォルト）

{ "jobId": "<guid>", "status": "pending" }

同期（完了）

{ "jobId": "<guid>", "status": "completed", "result": { "url": "https://..." } }

同期（失敗）

{ "jobId": "<guid>", "status": "failed", "errorMessage": "..." }

同期（タイムアウト）

{ "jobId": "<guid>", "status": "processing" }

非同期呼び出し（または同期タイムアウト）の場合は、 GET /api/v1/screenshots/{jobId} で状態を確認してください。想定される値: pending, processing, completed, failed, expired.

エラー

HTTP	発生条件	本文
400	body がない、または url がない/空	BadRequest
401	API キーが無効または欠落	ミドルウェア応答
402	クォータ超過	{ "error": "quota_exceeded", "operationKey": "screenshot.capture", ... }
429	レート制限	{ "error": "rate_limited", "operationKey": "screenshot.capture", ... }
404	ジョブが見つかりません	NotFound

実践例

一般的な統合ニーズに対応した実用例です。

対象サイトの認証トークンを渡す（headers 経由）

キャプチャ対象ページが保護されている場合（Bearer/JWT/session token）、次を使って転送してください: headers:

{
  "url": "https://example.com/dashboard",
  "headers": {
    "Authorization": "Bearer <target_site_token>"
  }
}

Cookie を設定する（セッションベースのログイン）

Web サイトが認証に Cookie を使用している場合は、次を使って渡してください: cookies:

{
  "url": "https://example.com/account",
  "cookies": [
    { "name": "session", "value": "<cookie_value>", "domain": "example.com", "path": "/" }
  ]
}

カスタムリクエストヘッダー（User-Agent / locale）

{
  "url": "https://example.com",
  "headers": {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "Accept-Language": "en-US,en;q=0.9"
  }
}

ビューポート + 形式 + 品質

{
  "url": "https://example.com",
  "viewport": { "width": 1280, "height": 720 },
  "format": "jpeg",
  "quality": 85
}

ページ読み込み待機 + 遅延追加

{
  "url": "https://example.com",
  "waitUntil": "networkidle",
  "delayMs": 500
}

特定要素をキャプチャ（selector）

{
  "url": "https://example.com/pricing",
  "selector": "#pricing"
}

状態を取得

ジョブをポーリング:

GET /api/v1/screenshots/{jobId}