shotanvil

shotanvil-examples

shotanvil スクリーンショット API の使用例と、ライブ同期される OpenAPI 仕様のコピーです。1 screenshot = 1 request、本当に無料の無料プラン、月額 $9 から利用できます。

ベース URL：https://api.shotanvil.com

アクセス方法

GET /take と POST /render-html は、次の 3 つのアクセス方法をこの順序で確認します。

1. x402 — X-Payment ヘッダーを送信します（呼び出しごとの支払い、登録不要、テストネットで決済）。
2. API キー — X-Api-Key: <key> または ?access_key=<key> を送信します。
3. キーなし — 認証情報は不要です。IP ごとにレート制限され、オペレーターがキーなしアクセスを有効にしている場合に限り利用できます。

無効な API キーは、キーなしアクセスが有効な場合でも、常に 401 エラーになります。キーの入力ミスがあっても、より低いプランへひそかに切り替わることはありません。

shotanvil.com で API キーを取得してください。

クイックスタート

スクリーンショットを撮影します。

curl "https://api.shotanvil.com/take?url=https://example.com" \
  -H "X-Api-Key: $SHOTANVIL_API_KEY" \
  -o screenshot.png

生のバイト列ではなく、テキストとメタデータを JSON として取得します。

curl "https://api.shotanvil.com/take?url=https://example.com&response_format=json" \
  -H "X-Api-Key: $SHOTANVIL_API_KEY"

インライン HTML をレンダリングします。

curl -X POST https://api.shotanvil.com/render-html \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $SHOTANVIL_API_KEY" \
  -d '{"html": "<html><body><h1>Hello</h1></body></html>"}' \
  -o out.png

実行可能なその他の例：examples/curl.sh、 examples/node/screenshot.mjs。

よく使う GET /take パラメーター

パラメーター	型	備考
url	文字列、必須	対象ページの URL。http/https のみ。
format	文字列	png（デフォルト）、jpeg、webp、または pdf。
full_page	bool	ビューポートだけでなく、スクロール可能なページ全体の高さをキャプチャします。
viewport_width / viewport_height	int	320–3840 / 240–2160。
cache_ttl	int	このレンダリングをキャッシュする秒数。0–86400。
fresh	bool	このリクエストではキャッシュの読み取りを回避します。
block_ads	bool	EasyList を基にしたブロックリストを使って、広告ネットワークへのリクエストをブロックします。
block_cookie_banners	bool	一般的な Cookie 同意バナーを非表示にする CSS のブロックリストを挿入します。
dark_mode	bool	ナビゲーション前に prefers-color-scheme: dark をエミュレートします。
response_format	文字列	binary（デフォルト）は生のバイト列を返します。json は画像（base64）と抽出したテキスト／メタデータをラップして返します。

すべてのパラメーターのリファレンス、リクエスト／レスポンスのスキーマ、各フィールドの実例は openapi.json にあります。任意の OpenAPI ビューアー（例： editor.swagger.io）で開くと、ブラウズ可能な形式で確認できます。

レート制限

各 API キーには、1 秒あたりのレート制限と 1 日あたりの呼び出し上限があります。GET /usage では、 現在のキーの当日分の使用状況を確認できます。いずれかの上限を超えると、retry_after_s フィールドを含む 429 が返されます。

openapi.json の同期を保つ

このリポジトリの openapi.json は、ライブの GET https://api.shotanvil.com/openapi.json エンドポイントから取得したある時点のコピーです。手書きではなく、API の進化に伴って実際の内容とずれていきます。

気軽に閲覧する範囲を超えて参照する前、または今後このリポジトリを更新する前に、再取得して差分を確認してください。

curl -sS https://api.shotanvil.com/openapi.json -o /tmp/openapi.latest.json
diff openapi.json /tmp/openapi.latest.json

差分がある場合は内容を確認し、新しいコピーで openapi.json を置き換えてコミットしてください。openapi.json を直接編集しないでください。

ライセンス

このリポジトリの例は MIT ライセンスです。自由にコピーして調整してください。openapi.json は shotanvil API の説明であり、参考情報としてのみ提供されています。