Screenshot Capture API

The Screenshot Capture API allows you to capture and analyze screenshots of web pages using InsightEmbed's AI capabilities. This API enables visual content analysis without requiring users to manually take screenshots.

Capturing Screenshots

Capture Screenshot

POST /capture/screenshot

Capture a screenshot of a specified URL.

Request Parameters

Parameter	Type	Required	Description
url	string	Yes	The URL to capture
width	integer	No	Viewport width in pixels (default: 1280)
height	integer	No	Viewport height in pixels (default: 800)
full_page	boolean	No	Capture full page height (default: false)
delay	integer	No	Delay in milliseconds before capture (default: 0)
selector	string	No	CSS selector to capture specific element
format	string	No	Image format: 'png' or 'jpeg' (default: 'png')
quality	integer	No	Image quality for JPEG (1-100, default: 80)

Example Request

{
  "url": "https://example.com",
  "width": 1024,
  "height": 768,
  "full_page": true,
  "delay": 500,
  "format": "jpeg",
  "quality": 90
}

Example Response

{
  "success": true,
  "data": {
    "screenshot_id": "scr_1a2b3c4d5e6f",
    "url": "https://example.com",
    "timestamp": "2023-06-15T10:30:45Z",
    "image_url": "https://api.insightembed.com/v1/screenshots/scr_1a2b3c4d5e6f.jpeg",
    "width": 1024,
    "height": 3240
  },
  "meta": {
    "processing_time": 2.34
  }
}

Analyzing Screenshots

Analyze Screenshot

POST /analyze/screenshot

Analyze a previously captured screenshot or a screenshot provided as a URL.

Request Parameters

Parameter	Type	Required	Description
screenshot_id	string	No*	ID of a previously captured screenshot
image_url	string	No*	URL of an image to analyze
prompt_template	string	No	Custom prompt template to guide the analysis
max_tokens	integer	No	Maximum number of tokens in the response (default: 256)
context	string	No	Additional context about the content to improve analysis

*Either screenshot_id or image_url must be provided.

Example Request

{
  "screenshot_id": "scr_1a2b3c4d5e6f",
  "prompt_template": "Describe the main elements visible on this webpage",
  "max_tokens": 200,
  "context": "E-commerce product page"
}

Example Response

{
  "success": true,
  "data": {
    "analysis": "The webpage is an e-commerce product page featuring a smartphone. The main elements include: 1) A large product image of a black smartphone, 2) Product title 'XYZ Smartphone Pro', 3) Price information showing '$799.99', 4) A 'Buy Now' button in orange, 5) Product specifications listed in a table format, 6) Customer reviews section with star ratings, 7) Related products carousel at the bottom.",
    "tokens_used": 72,
    "analysis_id": "ana_2b3c4d5e6f7g",
    "screenshot_id": "scr_1a2b3c4d5e6f"
  },
  "meta": {
    "processing_time": 1.56
  }
}

Capture and Analyze in One Step

POST /capture-and-analyze

Capture a screenshot of a URL and analyze it in a single API call.

Request Parameters

Combines parameters from both the capture and analyze endpoints.

Parameter	Type	Required	Description
url	string	Yes	The URL to capture
width	integer	No	Viewport width in pixels (default: 1280)
height	integer	No	Viewport height in pixels (default: 800)
full_page	boolean	No	Capture full page height (default: false)
delay	integer	No	Delay in milliseconds before capture (default: 0)
prompt_template	string	No	Custom prompt template to guide the analysis
max_tokens	integer	No	Maximum number of tokens in the response (default: 256)
context	string	No	Additional context about the content

Example Request

{
  "url": "https://example.com/products/smartphone",
  "width": 1024,
  "height": 768,
  "delay": 1000,
  "prompt_template": "What is the main product shown and its key features?",
  "max_tokens": 150,
  "context": "Mobile phone product page"
}

Example Response

{
  "success": true,
  "data": {
    "screenshot": {
      "screenshot_id": "scr_3c4d5e6f7g8h",
      "url": "https://example.com/products/smartphone",
      "timestamp": "2023-06-15T11:45:30Z",
      "image_url": "https://api.insightembed.com/v1/screenshots/scr_3c4d5e6f7g8h.png",
      "width": 1024,
      "height": 1560
    },
    "analysis": {
      "text": "The main product shown is the 'UltraPhone X12' smartphone. Key features include a 6.7-inch OLED display, 5G connectivity, 128GB storage, 12MP triple camera system, and all-day battery life. The product is priced at $699 with free shipping.",
      "tokens_used": 48,
      "analysis_id": "ana_4d5e6f7g8h9i"
    }
  },
  "meta": {
    "processing_time": 3.78
  }
}

Error Handling

The Screenshot Capture API uses standard HTTP status codes and returns detailed error information in the response body.

Common Errors

Status Code	Error Code	Description
400	invalid_request	Missing required parameters or invalid format
401	authentication_error	Invalid or missing API key
403	forbidden	The API key doesn't have permission for this operation
404	not_found	The specified screenshot_id doesn't exist
422	capture_failed	Failed to capture screenshot (invalid URL, timeout, etc.)
429	rate_limit_exceeded	You've exceeded your rate limit
500	service_error	Internal service error

Error Response Example

{
  "success": false,
  "error": {
    "code": "capture_failed",
    "message": "Failed to capture screenshot: timeout after 30 seconds",
    "param": "url"
  }
}

Best Practices

1. Optimize Capture Parameters: Adjust width, height, and delay parameters based on the target website to ensure complete content loading.

2. Use Selectors: When you only need a specific part of a page, use the selector parameter to capture just that element.

3. Set Appropriate Delays: For pages with dynamic content, set a sufficient delay to ensure all content is loaded before capture.

4. Combine Operations: Use the capture-and-analyze endpoint for efficiency when you need both operations.

5. Handle Errors Gracefully: Implement proper error handling, especially for capture failures which can occur due to various network or website issues.

6. Respect Website Terms: Ensure you have permission to capture and analyze content from target websites.

Quotas and Limits

Plan	Daily Screenshot Limit	Max Screenshot Size	Max Dimensions
Free	50 screenshots	5 MB	1920×1080
Starter	200 screenshots	10 MB	2560×1440
Pro	1,000 screenshots	20 MB	3840×2160

For more information about quotas and rate limits, see the API Reference Overview.