Skip to content

Release Screenshot API support in v0.2.0 #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fatwang2 merged 2 commits into from
Jul 25, 2026
Merged

Release Screenshot API support in v0.2.0 #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
48914e1
Add Screenshot API support
fatwang2 Jul 25, 2026
b654923
Release Screenshot API support in v0.2.0
fatwang2 Jul 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,23 @@ print(result["zipUrl"])
Use `start_deepcrawl`, `get_deepcrawl_status`, and `wait_for_deepcrawl` when
the application needs to control persistence or polling itself.

## Screenshot

Screenshot responses are binary image bytes rather than JSON:

```python
from pathlib import Path

screenshot = client.screenshot(
"https://example.com",
format="png",
full_page=True,
)

Path("screenshot.png").write_bytes(screenshot["data"])
print(screenshot["content_type"], screenshot.get("request_id"))
```

The clients also support news, crawl, sitemap, trending, extract, usage, and
batch operations exposed by the Search1API HTTP API. Requests time out after
30 seconds and retry `429` and transient `5xx` responses twice by default.
Expand Down
259 changes: 257 additions & 2 deletions openapi/search1api.openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
"openapi": "3.1.0",
"info": {
"title": "Search1API",
"description": "Web search, news, crawling, and content extraction APIs for AI agents. Supports pay-per-request via MPP and x402 protocols.",
"description": "Web search, news, crawling, screenshot, and content extraction APIs for AI agents. Supports pay-per-request via MPP and x402 protocols.",
"version": "1.0.0",
"x-guidance": "Search1API provides web search, news aggregation, URL crawling, sitemap extraction, trending topics, content extraction, and deep crawling. All paid endpoints accept POST with a JSON body. Use POST /search with a \"query\" field for web search. Use POST /news with a \"query\" field for news. Use POST /crawl with a \"url\" field to crawl a page. Use POST /sitemap with a \"url\" field to extract sitemap URLs. Use POST /trending with a \"search_service\" field for trends. Use POST /extract with a \"url\" field for structured content extraction. Use POST /deepcrawl with a \"url\" field for deep multi-page crawling."
"x-guidance": "Search1API provides web search, news aggregation, URL crawling, webpage screenshots, sitemap extraction, trending topics, content extraction, and deep crawling. All paid endpoints accept POST with a JSON body. Use POST /search with a \"query\" field for web search. Use POST /news with a \"query\" field for news. Use POST /crawl with a \"url\" field to crawl a page. Use POST /screenshot with a \"url\" field to render a PNG, JPEG, or WebP image. Use POST /sitemap with a \"url\" field to extract sitemap URLs. Use POST /trending with a \"search_service\" field for trends. Use POST /extract with a \"url\" field for structured content extraction. Use POST /deepcrawl with a \"url\" field for deep multi-page crawling."
},
"x-discovery": {
"ownershipProofs": []
Expand Down Expand Up @@ -775,6 +775,261 @@
}
},
"paths": {
"/screenshot": {
"post": {
"operationId": "screenshot",
"summary": "Render a web page as a PNG, JPEG, or WebP image",
"tags": [
"Screenshot"
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/jpeg": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/webp": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"402": {
"description": "Payment Required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"504": {
"description": "Gateway Timeout",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"x-payment-info": {
"protocols": [
"mpp"
],
"pricingMode": "fixed",
"price": "0.006"
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 4096
},
"format": {
"type": "string",
"enum": [
"png",
"jpeg",
"webp"
],
"default": "png"
},
"full_page": {
"type": "boolean",
"default": false
},
"viewport": {
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 320,
"maximum": 2560,
"default": 1440
},
"height": {
"type": "integer",
"minimum": 200,
"maximum": 1440,
"default": 900
},
"device_scale_factor": {
"type": "number",
"minimum": 1,
"maximum": 2,
"default": 1
}
},
"additionalProperties": false,
"default": {
"width": 1440,
"height": 900,
"device_scale_factor": 1
}
},
"wait_until": {
"type": "string",
"enum": [
"domcontentloaded",
"load",
"networkidle"
],
"default": "load"
},
"wait_for_selector": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"delay_ms": {
"type": "integer",
"minimum": 0,
"maximum": 5000,
"default": 0
},
"timeout_ms": {
"type": "integer",
"minimum": 1000,
"maximum": 30000,
"default": 20000
},
"quality": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"omit_background": {
"type": "boolean",
"default": false
},
"color_scheme": {
"type": "string",
"enum": [
"light",
"dark"
],
"default": "light"
},
"animations": {
"type": "string",
"enum": [
"disabled",
"allow"
],
"default": "disabled"
}
},
"required": [
"url"
],
"additionalProperties": false
}
}
}
}
}
},
"/search": {
"post": {
"operationId": "search",
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "hatchling.build"

[project]
name = "search1api"
version = "0.1.0"
version = "0.2.0"
description = "Official Python client for Search1API"
readme = "README.md"
license = { file = "LICENSE" }
Expand Down
2 changes: 1 addition & 1 deletion src/search1api/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,4 +35,4 @@
"UnprocessableEntityError",
]

__version__ = "0.1.0"
__version__ = "0.2.0"
Loading
Loading