API and agent guide

What the service does

Reverse Video Search helps find pages containing visual matches for a video frame or image. Video frames are extracted locally in the browser. Manual frame extraction is free; automated searches require an authenticated account and credits. Matches are leads to investigate, not proof of original authorship. Private or unindexed sources may not be found.

Authentication

Use an existing account session access token supplied by the account owner in the Authorization: Bearer <token> header. There is no dedicated API-key issuance or OAuth client flow for agents. Never include tokens in URLs, prompts, logs or shared examples. The API uses the same permissions and credit balance as the web application.

Search an image or extracted frame

POST /api/search/single-image with Content-Type: application/json. Send exactly one of image_url (a publicly reachable HTTP or HTTPS image URL) or image (a base64 image data URL), plus providers: an array containing one to three of serpapi_reverse (Google Lens), yandex_reverse (Yandex), bing_reverse (Bing). Internal and unsafe URLs are rejected. A video URL or video file is not a valid input to this endpoint; extract a frame first.

Costs, duplicate detection and retries

This operation spends account credits and stores a search. Confirm the account owner has authorized the search and its cost. Insufficient credits returns HTTP 402. By default, a matching previous image hash and provider set may return payload.duplicate=true and payload.existing without a new search. force=true bypasses this check and can spend credits again. Duplicate detection is not an idempotency guarantee: do not automatically retry after a timeout or an ambiguous failure. Check account history first. Empty or failed provider tasks trigger refunds; consult the returned accounting fields.

Read results and errors

Successful HTTP responses wrap data in { error: null, meta: {...}, payload: {...} }. A new search returns payload.id, image_url, image_hash, balance_after, total_charged, status and results. Each result has a provider and status (ok, empty or error); successful results contain matches. A batch can return HTTP 200 with status=partial_failure. Inspect every result and preserve source URLs. HTTP 401 means an invalid or expired session, 403 a forbidden provider, 422 invalid input, and 500 a server failure. Error bodies contain error.type and may include error.message.

Browser agents and privacy

The home page provides the interactive video workflow. Browser agents need file-upload and video/canvas support to extract frames. Only extracted images are submitted for automated video searches, but submitted frames are stored and made reachable by external search providers. Do not submit sensitive images without the account owner’s authorization. Documentation is public; account histories, downloads and results remain authenticated. This site does not currently expose an MCP server or accept whole videos through the documented image API.

Request body example

{
  "image_url": "https://example.com/frame.png",
  "providers": [
    "serpapi_reverse"
  ],
  "force": false
}

Replace the example URL with a reachable image you are authorized to search.